CSE Roadmap

Core tier · about 4 hours · 12 parts

Part 2 of 12 · 2 min read

A trace is a tree of timed spans, built by what wraps what

A run isn't one event, it's a tree -- an agent span that contains model-call and tool-call spans, which can themselves contain further calls -- and the tree shape itself tells you what happened in what order.

Think of a flight recorder in a plane: when something goes wrong, you don't guess what happened, you play back exactly what was recorded, in the order it happened.

In plain words: a trace is the full record of one request or run, a span is one timed operation inside it with a parent (except the root), and an attribute is a key-value pair attached to a span such as a token count or a model name -- and the tree structure comes directly from which span was active when another one started, which a stack-based tracer builds automatically just by tracking what's currently open.

A worked example. One simulated run produces a root invoke_agent span containing three chat spans and two execute_tool spans nested between them, each with its own start time, end time, status, and attributes like gen_ai.usage.input_tokens. Summing durations by span name across that run shows the three chat spans took 2.94 of the run's 3.28 total seconds -- 90% of the wall-clock time -- while the two execute_tool spans took only 0.34 seconds, immediately pointing at which kind of step to optimize.

The key lines. From code/mini-tracing/tracing.py:

# from code/mini-tracing/tracing.py
@contextlib.contextmanager
def span(self, name, **attrs):
    parent = self._stack[-1] if self._stack else None
    s = Span(name, parent.trace_id if parent else next(_ids), parent, self.clock(), attrs)
    (parent.children.append(s) if parent else self.roots.append(s))
    self._stack.append(s)

Read it as: the parent of a new span is simply whatever span is on top of self._stack at that moment. Nothing has to be told explicitly which span contains which. Opening a span inside another span's with block is what makes it a child. So the tree structure is a direct, automatic consequence of how the code happens to be nested.

Trace, span, attribute

A trace is the full record of one request or run. A span is one timed operation inside a trace, with a parent (except the root). An attribute is a key-value pair attached to a span, such as a token count.

Example: the root invoke_agent span containing three chat spans and two execute_tool spans, each carrying its own gen_ai.usage.input_tokens attribute, is a trace in miniature -- everything "what happened in this run" needs is already sitting in that one tree.