Skip to main content
A trace is one top-level generateText or streamText call. The Traces view lists them. Opening one shows the full execution as a waterfall you can inspect span by span and replay in real time. See the data model for how traces and spans are defined.

​
Traces list

A paginated table, newest first, over the selected date range. Columns: trace id, name (traceName, falling back to agentName, else Untitled trace), span count, tokens, duration, cost, and when it ran. Errored traces get a red badge; cleanly aborted traces (see below) get an amber one. Click a row to open the trace.

​
Waterfall

Each span is a row, indented under its parent, so nested tool calls and steps sit under the call that made them. Span types are color-coded: Each bar’s position and width match when the span started and how long it ran, so you can see at a glance what ran in sequence and what overlapped. A span’s status also tints its bar and badge: errors are red, and aborted spans are amber. An aborted span is a stream that was cancelled before it finished (a caller cancellation, an AbortSignal, or a timeout, via AI SDK v7’s onAbort). Aborts are not counted in the error rate, since a cancelled run isn’t a failure, and the steps that finished before the abort keep their own status. This is different from an abandoned trace, one that never finished and was closed by maxTraceAgeMs, which does count as an error.

​
Span detail

Click any span to open the inspector panel next to the waterfall. Depending on the span, it shows:
  • Timing: start time, duration, and time to first token. On reasoning models, that splits into thinking time plus time to first visible text.
  • Model: provider and model id.
  • Tokens & cost: input/output tokens, computed cost, the pricing source behind it, and a cost breakdown per dimension (prompt, completion, cache read/write, reasoning, image, web search, request) when more than one applies.
  • Model call: on v7 spans, how much time was the model itself versus tools.
  • Throughput: for streaming spans, a tokens-per-second number.
  • Provider signals: when captured, rate-limit headroom, the model build fingerprint, safety ratings, and grounding sources.
  • Tools available: the tools the model was offered for the call.
  • Payloads: the captured input and output, pretty-printed, in a scrollable block (subject to recordInputs/recordOutputs).
  • Metadata & errors: any span metadata, and the error message if the span failed.
Selecting the whole trace instead of a single span shows a summary: duration, cost, tokens, span and LLM-call counts, and errors.

​
Scores

If an eval has scored a trace or span, the scores appear in the inspector under Evals: one row per result, green for pass and red for fail (or the numeric score), with the judge’s reason inline and a link to that run on the eval page.

​
Replay

The waterfall can also replay the trace: press play to watch it rebuild on its real timeline, switch between 1x / 2x / 4x speed, and drag the ruler to seek. A throughput backdrop and a peak tokens-per-second readout sit behind the bars, and the first-token moment is marked on each LLM bar. Replay uses the token samples the SDK already records, so it needs no extra setup. Opening a trace with ?replay=1 plays it automatically.