> ## Documentation Index
> Fetch the complete documentation index at: https://docs.foglamp.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Traces

> Inspect a single run: waterfall, span detail, scores, and replay.

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](/concepts/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:

| Type    | Color  | Meaning                       |
| ------- | ------ | ----------------------------- |
| `agent` | amber  | the root span, the whole call |
| `llm`   | violet | one model step                |
| `tool`  | blue   | one tool call                 |
| `other` | grey   | anything else                 |

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`](/sdk/configuration), 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`](/sdk/configuration)).
* **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](/dashboard/evals) 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.