The collapsible step tree

Altitude 02 is a list of rows. You know how to render a tree; the recursion is not the problem and this lesson will not spend a paragraph on it. The problem is that three shapes in real agent telemetry have no obvious row, and the obvious rendering of each one states something the data never said.

Two calls that ran at the same time. One call that took two attempts. A run that has not finished arriving. Every trace panel meets all three, and the naive version gets all three wrong in the same direction: it renders a plausible story instead of an incomplete one.

Naming these three as the hard cases is this course’s own engineering analysis, built on documented gaps in the span model rather than on anything OpenTelemetry enumerates. The specification does not discuss rendering at all. What it does is state, in each case, that the fact your row wants to assert is not one it carries.

Case one: parallel siblings

Two enrichment calls ran at once. The runtime emitted two spans. Your component stacks them vertically, because that is what a list does, and a reviewer reads vertical order as causal order and concludes the second call used the first call’s output.

The overlap is recoverable, but only from timestamps, and only if you went looking. Sorting by start time does not fix this — it produces the same vertical list with a defensible sort key, which is worse, because now the sequence looks deliberate.

Underneath it is the finding from the span-model lesson, and it is the most load-bearing negative fact in this course. There is no normative rule that a tool execution nests under the model call that requested it. The conventions’ own non-normative examples say of a chat → tool → chat sequence that “the relationship between below spans depends on how user application code is written”, and that the spans are likely to be siblings under an encompassing span. So the nesting in your payload is an artifact of one program, and sibling rows carry no ordering claim beyond the timestamps on them.

What the row has to do, then, is narrow: say concurrency out loud, or say nothing about order. Rendering overlapping siblings with a shared start marker, or grouping them under a “ran together” label, both work. A bare vertical list works too, as long as it does not decorate itself with the connective tissue — numbered ordinals, downward arrows, an indent that implies descent — that turns adjacency into sequence.

Case two: the retried step

The specification is blunt about this one by omission. A span is one operation that happened. Two attempts at the same logical thing are two spans, related by nothing except adjacency, identical attributes, and an Error status on the first. There is no attempt number, no parent-of-attempts, no field that says “this is the same work again.”

So one row that reads enrich_property, 2 attempts, first timed out is a claim your component makes. It is the right claim. It is still a claim, and that has two consequences most implementations miss.

The grouping key is a heuristic you author. Same tool name, identical serialized arguments, adjacent in time, earlier one errored — that is a reasonable rule and it is a rule, not a reading. Write it down where a colleague can find it, because the day it is wrong, the component will have hidden a genuinely duplicated call by merging it into one row, which is the same category of lie as splitting one call into two.

Grouping belongs at altitude 02 and nowhere below it. The step list shows logical operations, so it groups. The full trace shows what was emitted, so it shows both spans, unmerged, with their own statuses and their own durations. If the inspector also groups, there is no altitude left at which a reader can check the grouping rule against the data, and the invariant from the altitudes lesson — no fact above that cannot be traced below — is broken by the component that was supposed to enforce it.

Case three: the run still arriving

This is the one that looks easiest and is the deepest, because the distinguishing fact is not in the span model at all.

Start with status. Unset is the default, and the specification tells instrumentation libraries to leave it that way unless there is an error. A span that is still running is Unset. A span that finished perfectly is also Unset. Status separates those two not at all.

Next try the end timestamp: an open span has none. Better, and still not enough, because a span with no end timestamp is also what you get from a process that died mid-step, an exporter that dropped the closing record, or a span whose closing record simply has not reached you yet in a streaming export. A missing end is a missing end. It is not a running step.

Then try absence: the branch you expect has no spans yet. This is the weakest signal of the three, because a trace is sampled and advisory by construction. W3C Trace Context states that trace flags are “recommendations given by the caller rather than strict rules”, and the tracing specification’s own sampling and span-limit machinery exists precisely so that not everything is recorded. A gap may mean not-yet, or never, or not-sampled, and the span data cannot tell you which.

What the three have in common

Each case is the view being asked to assert a relationship the data does not carry. Order, in the parallel case. Sameness, in the retry case. Liveness, in the streaming case. In all three the naive rendering is not a bug in the drawing code; it is the drawing code answering a question nobody decided.

Which means the fix is in the same place all three times. Each relationship becomes an explicit, named field on your run object, set by a rule you wrote, and the tree renders that field rather than inferring it from row position. A component that computes “these two are the same call” inside its render pass has put a policy decision somewhere no reviewer will ever find it.

What this does not cover

The tree now has rows that do not lie about order, sameness or liveness. What it does not have is anything inside a row. A step list row carries enough of a tool’s arguments to identify what it acted on — the record id, the URL, the query — and the complete arguments and results live one altitude down, where they are the most useful and most dangerous content in the whole component. That is the tool-call inspector lesson, which closes this module and is where redaction gets decided.

This lesson also said nothing about per-step timing beyond a duration column, and nothing at all about cost. Both are the cost and latency module, which takes the token counts sitting on your model-call spans and is deliberate about the difference between a number that was emitted and a number that was multiplied by a price off a vendor page.