What does one agent trace capture step by step?
An agent trace is a structured per-step log of every LLM call, tool call, timing, token, and cost in one task run, captured by tools like Langfuse, LangSmith, or Arize Phoenix.
Imagine your agent is a detective solving a case across a whole city in one afternoon. It interviews witnesses, checks records, drives to addresses, makes phone calls. At the end of the day the case is either solved or not. If it failed, you want to know exactly where it went wrong. Was it the second interview? The wrong address on the fourth stop? Tracing is a body camera plus a notebook strapped to the detective. Every conversation, every street it walked, every call it made, every minute that passed, is recorded as a separate timestamped entry. When the case fails, you can scrub back to step seventeen and see what the detective heard, what it said, and what it decided to do next.
Concept explanation~2 min read
Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example. Click to expand.
Concept explanation~2 min read
Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example. Click to expand.
Agent tracing is the practice of recording every step an agent takes during one task run as a structured, timestamped, parent-linked span. The collection of spans for one task is the trace. The collection of traces over time is the dataset you debug, evaluate, and improve the agent from.
It is hard to overstate how central tracing is to running an agent in production. A traditional web service has one input and one output per request, and a log line per request is usually enough to debug it. An agent has one input, but it produces a fan-out of LLM calls, tool calls, internal decisions, and state updates before it returns. A single user message can quietly spawn dozens of steps. When the final output is wrong, the question is not whether the system failed; it is which step failed.
This explanation builds out what a trace contains step by step, why the tree shape of the data matters, which production tools capture traces today, and how teams put traces to work for debugging, evaluation, and cost control. The goal is the mental model that lets you sit in front of any tracing UI and immediately know what you are looking at.
What a single span captures
A trace is built out of spans, and a span is the atomic unit of observability for one step. The standard fields are remarkably similar across tools, because they all converge on the OpenTelemetry GenAI semantic conventions or something close to them.
For an LLM call, the span holds the fully rendered prompt that was sent to the model, with variables substituted into the template. It holds the model identifier and version, the response text, the input and output token counts, the wall-clock latency, and a computed dollar cost based on the model's price card. Optional fields include the temperature, top-p, stop sequences, and any tool-use schema the model was offered.
For a tool call, the span holds the tool name, the arguments the agent passed in as JSON, the result the tool returned, and any error. The latency is measured the same way as an LLM call. If the tool is itself another LLM (such as a sub-agent), the child span tree continues underneath.
A few other span types show up regularly. A state-update span records what changed in the agent's working memory. A retrieval span records the query, the documents pulled back, and their similarity scores. A planner span records the high-level plan that was just produced, before any tool ran. Each span has a parent span identifier, which is how the tree gets stitched together. Without parent identifiers you have a list, not a tree, and a list cannot represent a recursive agent.
Situations where this technique stops working.
2–4 min · Everything important, quickly.
Real products, models, and research that use this idea.
- Langfuse provides hosted and self-hosted tracing for LangChain, LlamaIndex, and the Anthropic and OpenAI SDKs, with span trees and per-step cost breakdowns.
- LangSmith is LangChain's first-party tracing product and ships built-in spans for every chain, tool, and retriever in the LangChain ecosystem.
What an interviewer would ask next. Try answering before peeking at the approach.
QA trace captures everything that happened on a task. How do you find the trace that explains a specific user complaint a week later?
Indexing and search. Traces must be tagged with user, session, task, and agent-version identifiers, and the tracing UI must offer free-text search over prompts and responses. Without those affordances the trace exists but is unreachable.
Red flags & common mistakes
The phrases that signal junior thinking. Click to expand.
Red flags & common mistakes
The phrases that signal junior thinking. Click to expand.
Treating tracing as a logging concern. A trace is structured: each step is a typed span with its parent, its inputs, its outputs, and its timing. Plain print statements lose the tree shape and the per-step inputs.
60 second bullets to scan on the way to the call.
Define an agent trace as a tree of spans for one task run.
Name the four fields a good LLM span holds: prompt, response, tokens, latency, cost.
Primary sources. Browse if you want the original framing.
Same topic, related formats. Practice these next.