Trace Span (Agent)
When an agent run goes wrong, the useful question is never "did it fail" but "where". Answering that needs the run broken into timed, labelled pieces. A trace span is one of those pieces: a single unit of work inside a run — one model call, one tool invocation, one retrieval — recorded with a start time, a duration, and the inputs and outputs that passed through it.
How spans build a trace
- Each span carries its own id and a parent id, so spans nest: a tool span sits inside the loop iteration that triggered it.
- The whole nested set for one run is the trace — a tree that reads as a timeline when drawn.
- Spans carry attributes: model name, token counts, cost, status, error message, the arguments the tool actually received.
Why agents need them specifically
A single model call can be understood from its request and its response. An agent cannot — it is nondeterministic, multi-step, and its interesting failures live in the relationships between steps. Spans make those visible: the retry that fired nine times, the retrieval that returned nothing and the plan that quietly drifted afterwards, the one tool call that ate forty seconds of a sixty-second budget. LangSmith, Arize Phoenix and OpenTelemetry-based instrumentation all record agent activity in this shape, and that is what lets latency, spend and correctness be attributed to a specific step instead of to the run as a whole.
A trace span is a single timed unit of work recorded inside an agent run — one model call, tool invocation or retrieval — with its start time, duration, inputs, outputs and status. Each span names a parent, so a run's spans nest into a trace that reads as a timeline. Spans are what make a nondeterministic multi-step run debuggable, letting latency, cost and failure be attributed to the exact step responsible.
Think of a parcel tracking page. You do not just see "delivered" or "lost" — you see each stage, when it happened and how long it took. A trace span is one of those stages, recorded for an AI assistant instead of a parcel.
When software works through a task on its own, it takes many small steps: think, look something up, call a service, think again. Each step is written down separately, with its timing and what went in and came out. Stacked together, they show the whole journey. That is how someone can go back afterwards and see which step was slow, which one failed, and where the job went off course.