---
title: "Audit and Request Traces"
url: "https://docs.caracal.run/concepts/audit-ledger/"
markdown_url: "https://docs.caracal.run/markdown/concepts/audit-ledger.md"
description: "Decision events and diagnostics that explain Caracal authority."
page_type: "page"
concepts: []
requires: []
---

# Audit and Request Traces

Canonical URL: https://docs.caracal.run/concepts/audit-ledger/
Markdown URL: https://docs.caracal.run/markdown/concepts/audit-ledger.md
Description: Decision events and diagnostics that explain Caracal authority.
Page type: page
Concepts: none
Requires: none

---

The audit ledger records what Caracal decided, why it decided it, and which request or run produced the event.

## What Gets Audited

| Event area | Examples |
| --- | --- |
| Token exchange | Allow, deny, step-up required, policy diagnostics. |
| Gateway and connector use | Resource decision, mandate verification failure, request correlation. |
| Policy lifecycle | Policy creation, validation, policy-set activation, simulation. |
| Delegation | Edge creation, traversal, impact, revocation cascade. |
| Sessions | Spawn, terminate, revoke, expire. |
| Administration | Zone, application, resource, provider, grant, and challenge changes. |

## Audit Flow

```mermaid
flowchart LR
  STS["STS"] --> Redis["Audit stream"]
  Gateway["Gateway / connectors"] --> Redis
  Admin["Admin API"] --> Redis
  Redis --> Worker["Ingestion worker"]
  Worker --> Postgres["Audit tables"]
  Postgres --> Console["Console audit and explain views"]
  Postgres --> API["Admin API audit endpoints"]
```

## How to Use Audit

| Question | Where to look |
| --- | --- |
| Why was a request denied? | Console `request trace` or Admin API explain endpoint by request ID. |
| Which policy caused the decision? | Determining policies and diagnostics. |
| Did revocation propagate? | Session, delegation, and resource decision events. |
| Which run made a request? | Request ID, session ID, agent session ID, and trace context. |
| Was step-up required or satisfied? | Step-up challenge and exchange events. |

## Request IDs

Request IDs tie multiple events together. Keep the request ID from an SDK, Gateway, STS error, or Console trace whenever debugging. The explain view uses it to collect related decision events and diagnostics.

## Integrity and Retention

Audit events should be treated as operational evidence. Configure retention, export, and SIEM forwarding according to your deployment requirements. Do not rely on local process logs as the only authority trail.

## Next Step

Use [Guides](/guides/) when you are ready to apply the model.

## Related Pages

- [Tail and Query the Audit Stream](/guides/audit-stream/)
- [Trace One Protected Request](/tutorials/inspect-a-run/)
- [Operations](/operations/)