---
title: "Inspect Diagnostics and Audit"
url: "https://docs.caracal.run/runtime-console/observability/"
markdown_url: "https://docs.caracal.run/markdown/runtime-console/observability.md"
description: "Inspect diagnostics, audit events, and request traces through the Console."
page_type: "reference"
concepts: []
requires: []
---

# Inspect Diagnostics and Audit

Canonical URL: https://docs.caracal.run/runtime-console/observability/
Markdown URL: https://docs.caracal.run/markdown/runtime-console/observability.md
Description: Inspect diagnostics, audit events, and request traces through the Console.
Page type: reference
Concepts: none
Requires: none

---

Observability workflows live in the Console because they need operator context, selected zones, and structured API responses.

## Diagnostics

Open `diagnostics` with `d`. The Console Doctor view runs the shared engine diagnostics across four sections:

| Section | Checks |
| --- | --- |
| `health` | API reachability, admin authentication, and operator clock skew against the platform. |
| `readiness` | Per-service `/ready` probes plus threshold evaluation of STS, Gateway, audit, and Coordinator operator metrics. |
| `zones` | Visible zones, resources, policy sets, and audit queryability. |
| `preflight` | Local secrets, keys, TLS material, and Postgres/Redis reachability. |

Doctor does more than report liveness: it evaluates the operator metrics it collects and raises a warning or failure when a signal needs action. Notable deeper checks include:

| Signal | Result | Why it matters |
| --- | --- | --- |
| Clock skew vs the API exceeds 30s | `fail` | Token `iat`/`nbf`/`exp` validation and audit ordering break when hosts are not NTP-synced. |
| STS OPA `compile_errors` > 0 | `fail` | A policy bundle will not compile, so token exchanges deny or run on a stale bundle. |
| Audit `tamper_mismatch_total` or `chain_breaks` > 0 | `fail` | Audit chain integrity is broken — treat as a security incident. |
| Audit `dlq_size` or `hmac_failures` > 0 | `warn` | Events are failing processing or HMAC verification before they age out. |
| Coordinator outbox `dead` rows, or a large `pending` backlog | `warn` | Spawn and revocation events are not propagating downstream. |

Useful Doctor controls include reload, all-zones or selected-zone checks, preflight-only checks, and strict readiness where warnings fail automation gates. The `Next actions` block collects the advice for every non-passing check.

This view is deeper than `caracal status`: `status` answers "is the stack up", while Doctor inspects internal health — policy compilation, audit integrity, event propagation, clock alignment, and local key material — that keeps the platform working correctly over time.

## Audit

Open `audit` with `a`. Audit records tie STS, Gateway, Coordinator, policy, and Control decisions to request IDs and authority anchors. Use the audit view to filter recent events, inspect denials, and gather incident context.

The audit view opens recent events immediately and streams new ones as they arrive. Press `f` for advanced filters: decision, event type, time window, request ID, agent session, agent label, and result limit. Time-window fields accept a relative window such as `15m`, `2h`, or `7d`, an ISO timestamp, or a date — the Console converts the value before querying the API. Use row actions to open the full event group (`enter`) or the decision trace (`x`) for the selected request.

Audit is an event ledger: it records what authorization decided. It is distinct from the `sessions` views, which show the live state of authority sessions, agent sessions, and delegation edges. Filter audit by `agent session` or `agent label` to connect a decision back to the session that made it.

## Request Trace

Open `request trace` with `t` when you already have a request ID — from a log line, error response, or Gateway header — and need the decision trace directly without scanning the audit list. It is the same trace reached by `x` on an audit row, exposed as a direct entry point. Trace output connects the request, selected resource, subject, scopes, determining policies, diagnostics, and result.

## Troubleshooting

| Symptom | Check |
| --- | --- |
| Diagnostics cannot reach API | Run `caracal status --ready`; custom deployments should confirm the Management API URL override. |
| Zone diagnostics show no zones | Confirm the admin token has visibility into the expected zone. |
| Audit records are missing | Confirm the selected zone, time window, and audit service readiness. |

For a symptom-first path from a failing application call to the right surface and tool, see [Troubleshoot by Symptom](/operations/troubleshooting/).

:::note[FAQ]
[Why is an audit event missing?](/reference/faq/#faq-018)
:::

## Next Step

Use [Manage Agents and Delegation](/runtime-console/agents/) when a request involves agent sessions, child sessions, or delegated authority.