Tracing and Observability
Capture every model call, tool call, and decision so you can see exactly what your agent did and why.
A user reports that your agent gave a wrong answer yesterday afternoon. What did it actually do? Which tools did it call, with what arguments, and what came back? Did it misread a tool result, or did the tool return bad data? Was it slow because the model thought for a long time, or because one API call took twenty seconds? If all you have is the final answer and a stack of print statements, you're guessing.
Tracing records every step of every run as a structured tree you can explore after the fact: each model call, each tool call, how long it took, what went in and out, and how the steps relate. In this lesson you'll learn the core OpenTelemetry concepts, instrument an agent loop in TypeScript, send traces to a viewer, and use them to answer real questions about your agent's behavior.
Why logs aren't enough for agents
A traditional web request does roughly the same thing every time, so a few log lines tell the story. An agent run is different. It might take two steps or twenty, call tools in any order, retry after errors, and branch based on what it reads. The final answer hides almost all of that.
Flat logs make this worse, not better. When ten runs execute concurrently, their log lines interleave, and you can't easily tell which tool call belonged to which run or which model response triggered it. What you need is:
- Grouping: everything that happened in one run, together.
- Structure: which step caused which, as a tree.
- Timing: how long each step took, so slowness has a location.
- Payloads: the actual inputs and outputs at each step, so wrong answers have an explanation.
That's precisely what a trace gives you.