TRACING AND SPANS

CAPTURING THE RIGHT DETAILS Each span should capture: The span identifier and the parent identifier, to rebuild the tree. The start time and end time, to measure duration. The input, such as the search query or the prompt. The output, such as the returned results or the model's reply. The status, meaning success or error. The error message, if there was one, in full. Take care with privacy. Inputs and outputs may contain personal data, so many teams mask or limit what is stored, as you will see in Chapter 41. ANATOMY OF A TRACE A trace has a simple shape that is easy to picture. The whole run is one trace, and the trace contains a tree of spans. The top span covers the entire run from start to finish. Inside it sit child spans, such as one for each model call and one for each tool call. A child span can have its own children, such as a tool call that itself makes two network requests. Every span records when it started, when it ended, a name, a status of success or error, and a few labels called attributes, such as the tool name or the number of tokens used. Because each span knows its parent, the spans can be drawn as a timeline in which the long bars show where the time went. A trace viewer draws this picture automatically from the recorded spans.