Observability
Telemetry & observability
How Guardion records every evaluation as structured telemetry — sessions, traces and spans — so you can audit decisions, investigate incidents and export the data.
Unless you opt out per request (log: false), every POST /v1/guard evaluation is recorded as telemetry. The data is organized in three nested levels — sessions, traces and spans — plus aggregated findings, and is stored in a columnar analytics store optimized for high-volume querying and dashboards.
The hierarchy
A session contains many traces; a trace contains many spans. Spans link to their session and trace, and to a parent span, so a full interaction reconstructs into a tree.
| Level | Granularity | Represents |
|---|---|---|
| Session | A conversation / agent run | All traces sharing one session id. |
| Trace | One request / turn | All spans produced while handling a single evaluation. |
| Span | One event | A single step — a message, a tool call, a guardrail run, the final decision. |
Spans (events)
Spans are the atomic records. Each span has a type describing what the event was:
| Span type | Event |
|---|---|
prompt / request | Inbound message or request being evaluated. |
completion | Model response. |
tool_call / tool_result | A tool invocation and its result. |
tool_schema | A tool / MCP definition that was scanned. |
guardrail | A detector result for the turn. |
decision | The final policy decision. |
Alongside the type, a span carries the signals you query and chart: is_flagged, is_denied, is_redacted, risk_level, risk_score, the decision, plus tokens, latency_ms, model and provider.
Sessions
The session record rolls up its traces into aggregates: total requests and tokens, flagged and denied counts, the highest severity seen, first/last activity, dominant intent and drift. This is what powers session-level risk and the incident view — and it is the same accumulated context the policy engine reads at decision time.
Findings
Repeated detections are aggregated into findings, grouped by policy, detector, label and signature, with an occurrence count, severity, first/last seen and an investigation status. Findings turn a stream of individual flags into a deduplicated, triageable list.
Exporting telemetry
Pull the data out through the API: Export logs for span-level events and Export findings for the aggregated findings. Attach your own metadata on each POST /v1/guard call (for example customer_id) to slice telemetry by your own dimensions.