Designing a trace you can actually read

Our first trace view was a log. It was complete, and nobody read it.

Every tool call, every model response, every token count, in order, with timestamps to the millisecond. Engineers liked it for about a week. Support leads opened it once, scrolled, and closed it. When something went wrong, they messaged an engineer and asked what happened, which defeated the point of having a trace at all.

So we set ourselves a test: someone who didn't build the agent should be able to read a run top to bottom in a minute and say what it did and why. This is what it took.

Steps, not calls

A run can make forty tool calls. Most of them are the agent looking things up: search the orders, open one, open another, read the policy, read it again. Showing all forty, at the same weight, buries the three that matter.

We group calls into the steps from the agent's plan. "Find the order" is one row, even if it took six calls to get there. You can open the row to see all six, but you start with the step, written in the same words the agent used when it proposed the plan.

That one change cut the length of a typical trace from 40 rows to 7.

Say what happened in a sentence

Each step leads with a sentence, not a status. Compare:

• stripe.charges.list → 200 (2 items)
• Found two charges of $42.00 on Oct 3, 4 minutes apart.

The first is true. The second is what a person needs. The sentence is written by the agent at the time of the step and checked against the tool's actual response before we show it. If the two disagree, we show the raw response and flag it, because a confident wrong summary is worse than no summary.

The raw call is still there, one click away, in monospace, with the full request and response. Engineers didn't lose anything. They just stopped being the only people who could read a run.

Make decisions loud

The steps that change something (a refund, an email, an update to a record) get a different marker from the steps that only read. You can scan a trace for decisions without reading anything else.

Approvals get their own row: who was asked, who answered, how long it took, and what they changed. If a person edited the draft, we show the edit as a diff, so the next reader sees exactly what the agent wrote and what was sent.

When a customer asks why they got a refund, I open the run and the answer is the fourth line. I don't need anyone to explain it to me.

Time where it matters

We took timestamps off every row. Nobody needs to know a lookup started at 09:14:03.212. What people want is how long the run took, and which step was slow.

So each step shows its duration, and the slow ones get a bar. A run that took two minutes because a person took a minute and fifty seconds to approve looks very different from one where a tool timed out, and now you can see which at a glance.

The details that took longest

A few smaller things, each of which took longer than it should have:

1. Money and dates in the customer's format. A refund of 4200 in Stripe is $42.00 in the trace. A charge at 1696323600 is "Oct 3, 9:00am" in the workspace's time zone.
2. Names, not IDs. cus_Q8…f2 is "Dana Whitfield". The ID is still in the raw view, and it's still the thing you copy.
3. Failures in plain words. "Shopify said the order doesn't exist" beats a 404 with a stack trace. The stack trace is in the raw view.
4. No colour alone. Every status has an icon and a word, so a trace prints, reads in dark mode, and works for people who can't tell red from green.

How we know it works

We ran the one-minute test again with eight people from support and operations teams, none of whom had built the agent. Each read three real runs and answered three questions: what did it do, why, and would you have done the same.

On the old log, two out of eight could answer all three in under five minutes. On the new trace, seven out of eight answered in under a minute. The eighth took 70 seconds, and told us the approval diff was the part that convinced them.

Sample post. Replace the files in content/blog with your own.