# Trace viewer

Show what happened in a run in order: which step called which tool, how long each took, and where it broke.

For: Engineers and ops people finding out why a run went wrong.

Web page: https://candor.themethodic.com/screens/trace-viewer

## Layouts

### Timeline alone

Pick it when: Embedded in a run page: a wide strip that opens on the first failure.

Layout: Rows of nested spans as bars on a shared clock, the failing one solid and the ones after it pale.

Items:

- **Trace viewer** (`trace-viewer`, Pro; https://candor.themethodic.com/docs/trace-viewer.md): Each span as a bar on a shared clock, nested under its parent, opening on the first failure.
- **Run receipt** (`run-receipt`, Pro; https://candor.themethodic.com/docs/run-receipt.md): What the run cost.

```bash
npx candor-ui add trace-viewer run-receipt
```

### Timeline with a span panel

Pick it when: People click into a span to read its input, output and error.

Layout: The timeline on the left and the selected span's detail on the right.

Items:

- **Trace viewer** (`trace-viewer`, Pro; https://candor.themethodic.com/docs/trace-viewer.md): The timeline.
- **Payload** (`payload`, free; https://candor.themethodic.com/docs/payload.md): Code or query text the agent ran, shown as a block.
- **Log stream** (`log-stream`, Pro; https://candor.themethodic.com/docs/log-stream.md): The log lines from that span.

```bash
npx candor-ui add trace-viewer payload log-stream
```

### Who handed off to whom, first

Pick it when: Multi-agent runs, where the first question is which agent did this.

Layout: A tree of agents on the left and the timeline of the selected agent's spans on the right.

Items:

- **Run tree** (`run-tree`, Pro; https://candor.themethodic.com/docs/run-tree.md): The orchestrator and the specialists it handed work to.
- **Trace viewer** (`trace-viewer`, Pro; https://candor.themethodic.com/docs/trace-viewer.md): The selected agent's spans.
- **Agent avatar** (`agent-avatar`, free; https://candor.themethodic.com/docs/agent-avatar.md): Tells the agents apart at a glance.

```bash
npx candor-ui add run-tree trace-viewer agent-avatar
```

## Rules that matter most here

- **Unknown stays unknown** (https://candor.themethodic.com/principles#unknown-stays-unknown): A span still running stretches to now and has no duration; a missing span is a gap, not a guess.
- **Motion never says something false** (https://candor.themethodic.com/principles#motion-follows-the-outcome): The span that broke is solid, the ones that failed because of it are pale, and nothing animates after the outcome.
- **Reasoning is believed, not verified** (https://candor.themethodic.com/principles#reasoning-is-believed): A span's reasoning text is the agent's account, labelled as such.

## Patterns that cover part of it

- Agent trace viewer for React: https://candor.themethodic.com/patterns/agent-trace-viewer.md

## Brief for a coding agent

Paste this to the agent that builds the screen.

```text
Build a trace viewer with Candor UI: TraceViewer draws one run as nested spans on a shared clock.
Pass spans as plain data (id, parent, kind, start, duration, status). Candor does not collect traces.
It opens on the first failure; the span that broke is solid red, the ones that failed because of it are pale red.
A span still running stretches to now and shows no duration.
For multi-agent runs add RunTree beside it, and RunReceipt for cost.
Open a selected span's input and output as Payload blocks; model text in them is text, never markup.
See the agent-trace-viewer pattern and the run-forensics example.

Start from the "Timeline alone" layout: Rows of nested spans as bars on a shared clock, the failing one solid and the ones after it pale.
Candor items: trace-viewer (https://candor.themethodic.com/docs/trace-viewer.md), run-receipt (https://candor.themethodic.com/docs/run-receipt.md).
Install: npx candor-ui add trace-viewer run-receipt
Read each item's docs before using it and take its props from there; don't guess them. Pro and Premium items need the person's licence key, which they add with `npx candor-ui key <key>`; don't ask for it.
```