Lesson 18 got instrumentation right: every `agent.run`, `llm.call`, and `tool.*` boundary in an agent's execution now emits an OpenTelemetry span with a parent-child relationship, and those spans land in a backend as a trace. That trace is not just a log with extra structure — once a run exists as a tree of spans, the *shape* of that tree becomes diagnostic on its own, independent of what any individual span's attributes say.
This matters because reading spans one at a time doesn't scale. A production agent might emit forty spans per run and your team runs thousands of evals a week; nobody is opening every span's JSON by hand. What scales is recognizing shapes: a trace that is a long flat sequence of near-identical calls looks nothing like a trace that fans out into five parallel tool calls, and neither looks like a trace that is one span consuming almost the entire run. Each shape has a name, a cause, and a fix, and you can often tell which one you're looking at from the collapsed tree view alone, before reading a single attribute.
This lesson covers the anatomy of a span tree; span kinds, attributes, events and status; the recognizable pathological shapes — loops, runaway delegation, hotspots, straggling fan-outs — next to what a healthy trace looks like; why summing span durations double-counts and what critical path means instead; and how a trace's `trace_id` correlates it back to the eval case, log line, and metric that produced it.
Analogy🏏Cricket
🏏 Think of it like cricket: A commentator settling into the studio after a completed ODI doesn't start by rereading the ball-by-ball text commentary from over one; she pulls up the worm graph — the cumulative run curve plotted across all fifty overs — because the shape alone tells most of the story before she checks a single delivery. A steady, climbing line means boundaries kept coming at a healthy clip. A long flat stretch, barely rising for ten overs, means the batting side got stuck playing out dot ball after dot ball against a spinner like Kuldeep Yadav, unable to break out — the same flat shape you'd see if a chase had simply stalled. A line that suddenly plunges near-vertical for two overs, with three wickets falling in that window, marks a single hostile spell — Bumrah bowling full and straight at the death — that did almost all the damage on its own, while everything before and after stayed comparatively uneventful. None of these diagnoses require reading a single line of commentary; the shape of the curve — climbing, flat, or collapsing — points the analyst straight at the over that matters. That's exactly how an engineer should read an agent trace: before opening a single span's attributes, the shape of the span tree — flat and repetitive, deeply nested, or dominated by one block — already tells you where the story went wrong.
🏏 Showing the Cricket analogy — a Cricket version isn’t available for this concept yet.