Trace and span fields
Agents
A trace is one answer taken apart: a tree of spans, one per step the agent took, with the judge's verdict joined on. The same fields appear in the Traces table, on the trace page, in the span inspector and in the JSON that Download JSON and the table's export produce. This page lists them; Read one trace in full shows the page they render on.
Who can use it: the Builder role or higher, in a tenant licensed for agents.
A trace in the Traces table
Each row, and each object in the table's JSON export, has these fields.
| Field | Meaning |
|---|---|
id | The trace id, 32 hex characters |
spans | How many spans the trace holds |
started_at, started_relative | When the run started, absolute and as an age |
q, a | The question, up to 600 characters once the conversation context the platform prepends is removed, and the answer, up to 1,200 characters; a chat agent's answer comes from the stored message, with its citations |
dur | Duration in milliseconds |
tok, tok_in, tok_out, cached | Tokens in total, in, out, and served from a provider cache |
cost | Cost in US dollars, or null when nothing priced the run; null means unknown, not free |
model | The model that served, when known |
citations, kb_cites | The knowledge citations on the answer and their count |
status | ok or error; quality lives in judge, not here |
user, session | Who asked, and in which session, when the run stamped them |
judge | The judge's score from 0 to 5, or null when the judge has not reached the trace |
Tokens and cost are read from the spans when they carry them, and otherwise from the AI Gateway's usage records that fall inside the run's time window plus two seconds. That is how chat agents, whose runs carry no model-call spans, get their figures.
The table's filters are predicates on these fields: low quality is a judge score under 3.5, slow is a duration above the window's 95th percentile, errored is a status of error, and refused and hallucination read the judge's flags. The thumbs-down filter is accepted and returns nothing, with a marker saying feedback is not yet collected. The list returns fifty rows by default and at most five hundred, and has no paging cursor.
The trace page
Download JSON on a trace saves the page's object.
| Field | Meaning |
|---|---|
agent_id, trace_id, short_id | The agent, the trace, and its first eight characters |
question, answer | Up to 600 and 4,000 characters, cleaned as above |
user, session, agent_version, started, started_relative | Read from the run's root span |
judge | score, reasoning up to 600 characters, and dimensions holding whichever of helpfulness, accuracy and completeness the judge filled; null when not evaluated |
slo_ms | The latency objective the duration is coloured against, 5,000 unless your operator changed it |
spans | The spans as the platform returned them, described below |
rows, timeline_ms, duration_ms, longest_span_ms, tokens_in, tokens_out, cost | Computed in the browser from the spans, for the waterfall and the figures |
llm_calls, iterations | Always zero and always absent: the first counts a kind name the platform never writes, the second is not in the payload |
A span
| Field | Meaning |
|---|---|
span_id, parent_span_id | The span and its parent; the root's parent is empty |
name | The step's name: the tool or function the agent called, or the workflow's own sentinel |
type | workflow_root, llm_call, tool_call, retrieval or unknown, decided as below |
start_time, end_time, duration_ms | Microsecond timestamps and the duration |
tokens.input, tokens.output, cost | Tokens and cost on this span; zero when the step carried none |
status | OK, ERROR or UNSET. A tool that returned a typed error without raising is ERROR |
model, provider | The model and provider on a model-call span |
ttft_ms, decode_tps | In the inspector only: time to first token, and output tokens per second after it; null when either is missing |
The kind is decided from the stored step: the workflow's root is workflow_root; any span carrying a model is llm_call; a named step with no model is tool_call; a step whose name is a bracketed framework sentinel collapses into the root. The legend on the trace page names six kinds; the recorded kinds are these five.
What is stored
Behind every span is one row kept for ninety days: the fields above plus the tenant, the agent's name and owning team as they were at the time, the agent version, the session and user ids, the span kind, a status message, the full attribute bag and the span's events. The attribute names in the bag are listed on the developer site's OpenTelemetry attributes page.
The judge writes a separate row per trace, kept for 180 days and replaced when a trace is evaluated again: judge_score, helpfulness, accuracy and completeness, each from 0 to 5; the flags refused, hallucination_flagged, pii_in_output and safety_violation; reasoning, up to 2 KB; the judge model and its rubric version; the evaluation's own cost and latency; and a failure cluster id and label where Issues grouped it.
Limits and behaviour
- The trace id is the run's own trace identity. The gateway's usage records for the run's model calls carry the same id when it propagated; the time window is the fallback.
- The root span's question is the prompt as the runtime saw it. Only the injected conversation context is stripped from it.
- A model-call span with zero tokens means the provider reported none; the trace's totals then come from the gateway window.
- The user and session fields are filled only when the run stamped them on its spans. On the current build the agent runtime does not, so they are empty for agent runs.