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

# Observability

> Traces, spans, and observation types in RunAgain.

RunAgain organizes agent activity into **traces** and **spans**, following
OpenTelemetry semantics with a gen\_ai-aware data model.

## Traces & spans

* A **trace** is one end-to-end run (e.g. a single agent invocation, or a
  Claude Code session). Spans in a trace share a `trace_id`.
* A **span** is a single operation within a trace — an LLM call, a tool call,
  a retrieval step. Spans carry timing, status, and attributes.

## Observation types

Every span is classified so the UI can render it meaningfully:

| Type         | Meaning                                                           |
| ------------ | ----------------------------------------------------------------- |
| `generation` | An LLM call — carries provider, model, token counts, and cost.    |
| `tool`       | A tool / function call — carries the tool name and result status. |
| `span`       | A generic step (planning, retrieval, orchestration).              |

## Promoted fields

RunAgain promotes the common gen\_ai attributes to typed columns so they're fast
to query and chart:

* **Model** — request and response model
* **Tokens** — input, output, cache-read, cache-write, reasoning, total
* **Cost** — computed from tokens, or taken from a provider-supplied `cost_usd`
* **Identity** — `session_id`, `conversation_id`, `user_id`
* **Tool** — `tool_name`, status

Large `input` / `output` payloads are offloaded to blob storage above a size
threshold and referenced by hash, keeping queries fast.

## Sessions

Spans that share a `session_id` (or, for Claude Code, `session.id`) are grouped,
so you can follow a whole conversation or terminal session as one trace.

<Card title="See it in the app" icon="activity" href="/app/traces">
  The Traces page renders the span waterfall, tokens, cost and status.
</Card>