tracewell
●
run 8f2a1c · 12 spans · exit 1
Tracewell captures every span, tool call and token of your agent in production, then lets you re-run the exact failure against a different prompt or model. Fix it before you ship it.
3.4ms
median overhead per span
90 days
traces retained on the free tier
tracewell stream — checkout-agent
LIVE
12:04:07.118
span
agent.plan · 4 msgs → 1,204 tok
812ms
12:04:07.930
tool
search_inventory(sku=A-771)
61ms
12:04:08.001
tool
search_inventory(sku=A-771)
58ms
12:04:08.070
tool
search_inventory(sku=A-771)
63ms
12:04:08.140
warn
repeat tool call ×3 — no state change
—
12:04:08.220
span
agent.act · 9,881 tok · $0.0412
2.10s
12:04:10.330
fail
max_iterations exceeded · exit 1
—
12:04:10.331
save
trace persisted · replayable
3.4ms
12 spans · 11,085 tok · $0.0412
REPLAY ⏎
// 01 · incident
The agent answered wrong at 02:41. Your logs have the prompt and the final string, and nothing in between — no tool arguments, no intermediate messages, no token accounting. So you guess, you patch, you deploy, and you wait to see if it happens again.
$400 / night · 11 nights
A tool-call loop nobody could see, billed at full rate until someone read the invoice.
app.log — what you actually have
GREP
02:41:03
INFO
request received · user 44120
02:41:09
INFO
agent responded (6.2s)
02:41:09
WARN
customer flagged answer as wrong
# which tool ran? — not logged
# what arguments? — not logged
# how many tokens burned? — not logged
# can you run it again? — no
tracewell: 12 spans · every argument · replayable ✓
// 02 · anatomy
Four record types, one append-only stream, open schema. Everything the runtime knew at the moment it decided — kept in the shape you can query, diff and replay.
schema v3 · JSONL · OTel-compatible
01
span_id · parent_id
span
One unit of agent work — plan, act, reflect — with its start, end and causal parent. Nest them and you get the run's real control flow, not a flat log.
dur=812ms depth=2 status=ok
02
name · args · result
tool call
Full arguments in, full result out, serialised verbatim. This is the record that shows you the loop: same call, same args, three times, no state change.
search_inventory(sku="A-771")
03
prompt · completion
token
Per-span token accounting with the exact message list that produced it. Context-window blowups become a number on a line instead of a hunch.
in=9,204 out=677 ctx=61%
04
model · rate · usd
cost
Priced per span at the model's rate, rolled up per run, per route, per customer. The $400 night is visible on the first chart you open.
gpt-4o $0.0412 run total
// 03 · replay
Pick a captured run, swap the prompt version or the model, and Tracewell replays it against the recorded tool responses. Same inputs, new brain — a diff you can put in the pull request.
tracewell replay --run 8f2a1c
DIFF
prompt: v3 → v4
model: gpt-4o → claude-opus
tools: recorded
temp: 0.2
ORIGINAL · gpt-4o
exit 1
- plan: 4 steps
- tool: search_inventory ×7
- loop: no state change
- tokens: 11,085
- cost: $0.0412
- result: max_iterations
REPLAY · claude-opus
exit 0
+ plan: 3 steps
+ tool: search_inventory ×1
+ loop: none
+ tokens: 3,902
+ cost: $0.0148
+ result: answered · correct
64% fewer tokens · loop gone · verdict: ship it
replayed 1,000 runs in 4m 12s
// 04 · install
No sidecar, no collector to run, no agent rewrite. Import it, call init, and every span, tool call and token starts landing in the stream — at 3.4ms median overhead per span.
works with
LangGraph · LlamaIndex · OpenAI SDK
Anthropic SDK · CrewAI · bare loops
quickstart
SDK
pip install tracewell
import tracewell
tracewell.init("checkout-agent")
# every span is now captured
run = agent.invoke(task)
tracewell.replay(run.id, model="opus")
// 05 · deployment
Yes, it self-hosts. One Postgres, one container, no vendor telemetry leaving your VPC.
capability
SELF-HOSTED
CLOUD
runtime
1 container + 1 Postgres
managed, multi-region
trace data
never leaves your VPC
encrypted, EU or US
retention
your disk, your rules
90 days on the free tier
replay engine
identical, offline capable
identical, autoscaled
upgrades
pinned image tags
continuous
egress
zero vendor telemetry
agent → ingest only
postmortem-2026-04-11.md — resolved
P1
## root cause
We had a tool-call loop burning 400 dollars a night for eleven days. Tracewell found it in one replay.
Infrastructure lead, mid-size logistics platform
$4,400
burned before detection
1 replay
to reproduce the loop
18 min
from trace to merged fix
$
pip install tracewell && tracewell init
copy
3.4ms median overhead per span · traces retained for 90 days on the free tier
tracewell
· observability for agent runs
docs · trace format spec · status · security