AI systems make many decisions per request: which model to use, whether retrieval is allowed, whether a tool can be called, and which policy controls are applied. If you cannot explain those decisions after the fact, you cannot debug incidents or satisfy audits.
Decision logging is the practice of capturing why the system did something, not just what it did.
What to log as decisions
Focus on decisions that change risk, quality, or cost:
- Routing. Provider/model chosen, fallback used, and evaluated constraints (see routing and failover).
- Policy application. Which policy pack was applied and which checks were triggered (see policy layering).
- Tool authorisation. Allow/deny decisions and required approvals (see tool authorisation).
- Context decisions. What evidence was included, dropped, or redacted (see context engineering).
Use reason codes, not paragraphs
Free-form text is hard to analyse. Use structured reason codes and metadata so you can aggregate and alert. For example:
- ROUTE_RESIDENCY_AU when data residency forces a specific region.
- TOOL_DENY_MISSING_APPROVAL when a high-risk tool requires approval.
- CTX_TRUNCATED_TOKEN_BUDGET when context exceeds budget.
Make decisions part of your telemetry schema
Decision logs should be first-class telemetry events with consistent fields: request ID, user/tenant, policy version, prompt version, and decision outcomes (see telemetry schema and model registry).
Connect to incident response and audits
During an incident, decision logs help you isolate what changed: routing rule updates, policy changes, prompt changes, or tool enablement. They also support evidence packs by showing that controls were applied consistently (see incident response and compliance audits).
Keep logs safe and minimal
Decision logs do not require storing sensitive content. Prefer structured metadata over raw prompts, and apply retention rules aligned to risk (see retention and deletion).
Auditable AI is not just documentation. It is a system that records its decisions in a way humans can understand later.