Span trees break for agents

The span tree is one of the great ideas in distributed tracing. A request enters, fans out through services, and the nested waterfall shows you where the time went. For a request-shaped workload it is close to perfect.

Agent runs are not request-shaped, and the tree degrades badly.

What breaks

Depth stops meaning anything. In a service trace, nesting depth means causal containment — this call happened inside that one. In an agent trace, depth mostly records how the framework happened to structure its calls. A planning step, a tool call, and a sub-agent invocation land at whatever depth the abstraction produced. You end up reading the framework's internals rather than your agent's reasoning.

The interesting spans are the small ones. A waterfall draws attention by duration, so the 90-second LLM call dominates and the 40-millisecond tool call that returned malformed JSON — the actual cause of the failure — is a hairline you cannot click. The visual hierarchy is inversely correlated with diagnostic value.

Repetition collapses into noise. An agent that retries a tool six times produces six near-identical subtrees. The tree gives you no way to say "these are the same thing happening repeatedly, and here is what differed on attempt four" — which is the only question worth asking about a retry loop.

Sub-agents destroy the frame. When one agent spawns another, you either get a second disconnected trace or a subtree so deep it needs horizontal scrolling. The question you have — "which agent decided this?" — is not answerable by a shape built to express "which service was called".

Order gets lost. This is the one that surprises people. A tree is a hierarchy, not a sequence. But when you debug an agent, what you want to know is what happened next — and reconstructing chronological order from a nested tree with overlapping spans is genuinely hard. You end up mentally flattening the tree, which is a strong hint the tree was the wrong structure.

What replaces it

Read the run the way the agent experienced it: in order.

A transcript view renders the run as a linear sequence — prompt, thinking, tool call, tool result, next prompt — with each entry carrying its own cost, latency and token breakdown. It reads like a conversation with instrumentation attached, because that is what an agent run is.

What it gets right:

• Chronology is the primary axis, so "what happened next" is answered by scrolling rather than by inference.
• Every step has equal visual weight by default, so a 40ms broken tool result is as findable as a 90-second generation.
• Repetition is collapsible, so six retries read as one entry with a count and a diff rather than six subtrees.
• Long runs stay navigable, because a list of two hundred entries is an ordinary scroll while a tree of two hundred nested spans is not.

The tree is not useless

Worth being precise, because "span trees are dead" would be wrong. When you genuinely need to know what contained what — debugging a framework integration, tracking down where a retry wrapper was applied, understanding concurrency — the hierarchy is the correct view and the transcript cannot express it.

So it is a toggle, not a replacement. Transcript by default because that is what the majority of agent debugging needs; span tree one keypress away for the cases that need containment. Getting the default right is most of the value, since the default is what people reach for at 2am.

What none of this solves

A transcript makes a failed run readable. It does not tell you which step caused the failure — you still read it and decide. For a ten-step run that is fine; for a sixty-step multi-agent run it is still work.

Automatically localising a failure to the responsible step, tool, prompt or memory write is a genuinely unsolved problem — the literature calls credit assignment "highly underdeveloped" — and it is where we intend to go next. But a transcript is the honest prerequisite: you cannot attribute a failure in a representation you cannot read.

---

The transcript view and the span-tree toggle are part of what ships in the observability product. The span specification describes the attributes that make the transcript reconstructable from OpenTelemetry data.