Trace

Definition

A trace is the ordered record of everything one agent session did, broken into spans. A trace is keyed by session_id and agent_id; a span is a single operation within that session — a tool call, an LLM request, or a governance decision. Traces are how an operator reconstructs what an agent did, in what order, and what the gateway decided for a single run.

How it works

The gateway records a TraceResponse per session containing an ordered list of TraceSpan values. Each span carries:

• span_id — the span’s identifier.
• parent_span_id — links the span to the calling action, forming a tree.
• operation — the operation name.
• decision — the governance result for the span (for example allow or deny), when the span represents a governed action.
• start_time / end_time — ISO 8601 timestamps; end_time is absent while the span is still open.

The span_id / parent_span_id parent-child structure mirrors the OpenTelemetry span model, so a trace maps cleanly onto OTel concepts: a session trace is a trace, each governed action is a span, and the decision field is an attribute on the span. SDKs propagate identity and trace context per request — the Go SDK, for example, reads an explicit trace ID via WithTraceID and falls back to the active OpenTelemetry span context’s trace ID when none is set — so governance spans line up with the application’s own OTel spans.

flowchart TD
    S[Session trace] --> A["span: llm_call (allow)"]
    S --> B["span: tool_call db:write (require_approval)"]
    B --> C["span: approval (granted)"]
    S --> D["span: tool_call api:get (allow)"]

Example

The agent registry keeps a list of recent trace sessions per agent. From the CLI, inspecting an agent lists them, and a single session can be visualized:

$ aasm agent inspect quickstart-agent

Recent Traces:
SESSION_ID                        TIMESTAMP
9f3c…                             2026-06-15T12:04:11Z
Tip: run `aasm trace <session-id>` to visualize a trace

$ aasm trace 9f3c...

The SESSION_ID column is a hex-encoded session UUID, which is exactly what aasm trace takes as its argument. The section is printed only when the agent has recent traces.

In the dashboard, traces surface on the Live Ops route (/live): the L1 → L2 → L3 traffic pipeline (Identity → Capability → Scrub → External) and a tail -f event stream with agent / team / op-type / status filters render spans as they happen. The Audit Log route (/audit) shows the durable per-decision record that backs each governed span.

Related

• Audit — the hash-chained per-decision record behind governed spans.
• Agent — session_id keys a trace to one agent run.
• Policy — the source of each span’s decision.
• Observe in the dashboard — Live Ops and Audit Log routes.
• API reference — aa-api (TraceSpan, TraceResponse) rustdoc entry points.
• Quickstart (tracked under AAASM-418) — viewing a first trace end-to-end.

Last updated: 2026-09-28 by Chisanan232