TRACING AND SPANS

LEARNING GOALS By the end of this chapter you will be able to define a span and a trace, describe step-level tracing, and list what to capture at each step. SPANS AND TRACES A span is a record of a single unit of work, such as one model call or one tool call. A trace is the full chain of spans for one user request. Imagine a package delivered across the country. Each stop, such as the warehouse, the truck, and the local depot, is like a span. The complete tracking history from shop to doorstep is like a trace. Spans can be nested. A parent span, such as the whole request, can contain child spans, such as each tool call inside it. Each span carries its own identifier, and each child span stores its parent's identifier, so the chain can be rebuilt as a tree. STEP-LEVEL TRACING Step-level tracing records every step of the agent's chain of reasoning and action. When something is slow or wrong, you open the trace and read it like a story, from the first step to the last.