Traces & decisions

The Traces screen lets you inspect individual gateway requests: the guard decisions, the span timeline, and (subject to content mode) the payloads.

Traces & sessions#

A trace is one proxied request with its guard decisions and span timeline. A session groups related traces by the x-triage-session-id you pass, so you can follow a whole conversation. Classifier-only calls, from the SDK or REST endpoints rather than the gateway, are submitted as security events attributed to the same project. Their persistence is also best-effort; see Delivery semantics below.

Outcomes#

Each trace has an outcome badge:

The Traces filter uses these same labels (All outcomes / Allowed / Observed risk / Blocked / Error).

Verdicts#

Within a trace, each classifier reports a verdict:

Trace review is read-only. There is no current action to label a result or feed labels into threshold proposals or tenant adaptation. Use trace results to tune project thresholds manually. See Thresholds and calibration and Tenant adaptation.

Trace detail#

Opening a trace reveals three tabs. The header shows the outcome, mode, the trace-level decision action, and the guardrail/sanitization activity summary:

• Timeline. Spans as a Gantt-style bar list, showing where time went. Spans that carried a decision show its action (allow / block / harden / retry / escalate) inline, and expanding a span reveals its attributes and reason codes.
• Payloads. Request and response JSON and metadata, or a note that content was not retained under the current content mode.
• Decisions. Decision cards start with the trace-level Final Decision and Pre-Upstream Decision, followed by guard cards for Input, Output, Tool, and Tool Result evaluations (tool cards surface the enforced tool-policy action). A configured custom blocklist also emits a guard.input.custom_blocklist span with configured-term and match counts, but never the terms themselves; a match is included in the Input result. Action cards cover recorded pre-upstream controls, Tool Interception, Informed Retry, Model Escalation, and an activated CoT Integrity Conjunction with applied or simulated status and available facts. INT-CoT evaluation itself appears on the Timeline as a guard.cot_integrity span.

SDK check detail includes a Why this verdict panel built exclusively from classifier metadata: taxonomy labels, scores, thresholds, booleans, categories, and reason codes. Content-bearing classifier fields follow the project content mode and are omitted from metadata_only/redacted responses.

Live feed#

The Live toggle tails new proxy traces into the first page. Outcome, provider, session, time, and search filters pause the tail, as do pagination and the SDK-check-only view. The all-source and proxy-only views remain eligible. The button reads Live while the feed is connecting, streaming, or paused by the current view; Live (polling) while fallback polling is active; Live unavailable after a terminal access check; and Live off when disabled.

• After repeated transient stream failures, fallback polling refreshes the trace list and analytics every 15 seconds while attempting a new SSE connection every 60 seconds. A successful connection restores Live. Failure probes time out after five seconds and treat timeout, network failure, and 404 as transient.
• The backend rechecks project access every 60 seconds. A revoked or indeterminate check closes the stream so the client must reconnect and authorize again. After a stream error, an access probe returning 401 or 403 stops polling and reconnects and displays Live unavailable.
• The feed closes its stream and stops fallback polling while the browser tab is hidden. When the tab becomes visible, it immediately refreshes the trace list and analytics, then reconnects.
• Within the same eligible mounted feed, each validated trace can advance an in-memory resume cursor. A reconnect sends the latest cursor, and the server clamps persisted replay to five minutes. The backend also rescans a ten-second overlap to tolerate late commits. Bounded server and browser trace-ID sets suppress recent duplicates from overlap and replay.
• The resume cursor is not durable across a page reload, project change, turning Live off, or a filter or page change that makes the feed ineligible. A gap outside the bounded replay window is not inserted into the live view. Any trace that was persisted remains available through the normal list and filters.

Delivery semantics#

Trace and span writes are best-effort and bounded-loss by design. The proxy writes observability records through a bounded in-memory queue (default 4096). When the queue is full, the newest item is dropped and a warning is logged. The writer retries with a single reconnect per item, inserts are idempotent, and delivery never blocks the request path.

Direct classifier security events use a separate bounded in-memory queue (default 1024). An event is dropped if that queue is full, if the database writer was not initialized at startup, or if its write fails. These failures are logged and never change the classifier response. Traces and security events are operational telemetry, not a durable audit log.

If the database is unavailable at boot, the writer self-heals when the database recovers. Unexpected proxy exceptions still emit a proxy_internal_error trace before the request returns, so failed requests remain visible when the writer can deliver them.