TL;DR
A trace timeline encodes four things at once: bar length = duration, indentation = parent/child nesting, colour = span kind, position = order. Once you can read all four at a glance, you can size up a run in a couple of seconds.
Four things every timeline tells you
The same span anatomy from the last lesson, drawn on a time axis, becomes a timeline. Four visual cues carry all the information:
- Bar length = duration. A long bar is a slow step. The longest bar is your bottleneck — start there.
- Indentation = parent / child. A span nested under another happened inside it. A tool call indented under the run wrapper is part of that run; a model call indented under a tool is the tool calling the model.
- Colour = kind. Each span kind (Module 6 lesson 2) gets its own colour, so you can scan for "where are the LLM calls?" without reading every label.
- Position = order. Spans are laid out left-to-right in the order they started, so you can follow the run as a story from first step to last.
Analogy
A timeline is a Gantt chart for one run. Project managers read a Gantt chart without reading every task name — long bars are the tasks eating the schedule, indentation shows sub-tasks, and the left-to-right flow is the plan. A trace timeline is the same skill applied to three seconds of agent work.
Explore one
The timeline below is interactive. Select a span (click it, or focus it and press Enter) to see its details — the model it used, the tokens it consumed, how long it took. Notice how the longest bar lines up with the span that did the most work, and how the indentation matches the tree you saw drawn in the last lesson.
Reading order in practice
When a run is slow, you don't read every span. You find the longest bar, open it,
and ask "why did this step take so long?" That's the checkpoint: the longest bar
is the duration answer, and its indentation tells you the context — a long bar nested
under tool.execute is the tool's own work (often a model call the tool made), not
the top-level run stalling.
Nine times out of ten the longest bar is an LLM call with a large input — which is exactly what the next lesson is about.
Common mistake
Chasing the first bar (or the most colourful one) instead of the longest one. The timeline draws every span, but only a few matter for any given question. For "why slow," the only bar that matters is the longest; for "why expensive," it's the biggest LLM span. Let the question pick the cue — don't read the whole chart.
Key takeaways
Key takeaways
- Bar length = duration; indentation = nesting; colour = kind; position = order.
- The longest bar is the bottleneck — open it first.
- Indentation tells you whether a slow span is the run itself or work nested in a tool.
- You read a timeline by question, not top-to-bottom.
Go deeper: wall-clock time vs. self time, and parallelism
One subtlety the bars can hide: a parent's bar spans all its children, so the run wrapper is always the longest bar — but that doesn't mean the run wrapper is slow.
- Total (wall-clock) time is the parent bar's full length — it includes every child.
- Self time is how long a span spent on its own work, excluding children. The run wrapper's self time is usually near zero; its length is just the sum of what it contained.
So "the longest bar" really means the longest leaf or the span with the most self time, not the root. Good viewers show self time separately. The other subtlety: parallel spans (two tool calls the agent fired at once, Module 2) overlap on the timeline instead of stacking end-to-end — their bars share the same horizontal range. Overlap is a feature to look for: it means work happened concurrently, which is faster than the same spans laid end to end.