Documentation
tracellm replay
Replay a recorded execution timeline.
Overview
The tracellm replay command fetches a saved trace from MongoDB and re-executes its timeline step by step in the terminal. Each step is rendered with a tree visualization showing the execution order, status, input, and output.
Syntax
terminalCopy
bash
tracellm replay [OPTIONS] TRACE_ID
| Argument | Type | Required | Description |
|---|---|---|---|
| TRACE_ID | string | Yes | The trace ID to replay (e.g. tr_2kf9q3m1) |
| Option | Type | Default | Description |
|---|---|---|---|
| --speed | float | 1.0 | Replay speed multiplier (min 0.1) |
| --show-response | flag | false | Print the full saved response after replay |
What Happens Internally
- Fetches the trace from MongoDB by ID via
fetch_trace. - Renders metadata — trace ID, status, latency, retry count, and step count in a replay header panel.
- Iterates steps using Rich Live display. For each step it renders an execution tree showing which steps are completed (✓), active (▶), and pending, alongside a detail panel with tool name, duration, status, input (clipped to 200 chars), and output (clipped to 200 chars).
- Throttles timing — waits
duration / 1000 / speedseconds between steps, clamped between 80ms and 550ms. - Prints final report — a summary table plus a response preview (up to 600 chars). If
--show-responseis set, the full response is printed.
Example Output
Terminal outputCopy
text
Replaying execution timeline...
╭── Replay ────────────────────────────────────────────────╮
│ │
│ trace_id tr_2kf9q3m1 │
│ status SUCCESS │
│ latency 3420.00 ms │
│ retries 1 │
│ steps 9 │
│ │
╰──────────────────────────────────────────────────────────╯
╭── Replaying step 3/9 ────────────────────────────────────╮
│ │
│ ╭── Execution Timeline ─────────────────────────────╮ │
│ │ │ │
│ │ ✓ query.embed │ │
│ │ ✓ vector.search │ │
│ │ ▶ context.rerank │ │
│ │ ○ agent.plan │ │
│ │ ○ context.allocate │ │
│ │ ○ tool.chain │ │
│ │ ○ llm.generate │ │
│ │ │ │
│ ╰────────────────────────────────────────────────────╯ │
│ │
│ ╭── Step Detail ────────────────────────────────────╮ │
│ │ │ │
│ │ step 3/9 │ │
│ │ tool context.rerank │ │
│ │ duration 340 ms │ │
│ │ status OK │ │
│ │ input {"query": "Explain transformers",...} │ │
│ │ output {"reranked": true, "matches": 5} │ │
│ │ │ │
│ ╰────────────────────────────────────────────────────╯ │
│ │
╰──────────────────────────────────────────────────────────╯
Replay completeCommon Errors
| Error | Cause | Fix |
|---|---|---|
| Trace not found | Invalid trace ID or trace was deleted | Verify the trace ID with tracellm export or the dashboard |
| No steps to replay | Trace exists but has no recorded steps | Some traces may be empty — check the trace in the dashboard |
| MongoDB connection failed | Database is unreachable | Ensure MongoDB is running and MONGO_URL is correct |
Troubleshooting
Tip
Use
--speed 2 to replay twice as fast for quick debugging, or --speed 0.5 to watch each step in slow motion.