Traces

A trace is a tree

A trace is a tree of spans. The root span is the operation that kicked off the request, and every other span nests under the step that triggered it. They all share one trace ID, so the whole request stitches back together top to bottom, even when steps run across async tasks or services.

flowchart TD
accTitle: A trace is a tree of spans
accDescr: The support agent request is the root span with three child spans for intent classification, order lookup, and reply, and the reply span has its own retriever and response children
T["support_agent.run"] --> S1["llm.intent_classification"]
T --> S2["tool.check_order_status"]
T --> S3["chain.generate_reply"]
S3 --> S4["retriever.knowledge_base"]
S3 --> S5["llm.response_generation"]

The tree above is one support-agent request. The root support_agent.run is the whole request. Under it, llm.intent_classification reads the question, tool.check_order_status looks up the order, and chain.generate_reply writes the answer, which itself calls retriever.knowledge_base for the refund policy and llm.response_generation for the wording.

Read top to bottom, the tree is the exact path the request took, so when an answer comes out wrong you can see which step caused it.

What a trace isn’t

• Not a session. A session bundles many traces from one conversation or user. A trace is just one request inside it. See Sessions and users
• Not a log line. Logs are flat text events. A trace is a timed, structured tree with inputs, outputs, and cost at every step

Why it matters

Without traces, a wrong or slow answer is a dead end. You see the output but not the steps behind it, so debugging turns into guesswork over flat logs. A trace turns that into a readable path you can walk: you spot that the retriever pulled the wrong policy chunk, that one tool call dragged on for four seconds, or that an eval flagged the answer as unsupported. Latency, cost, errors, and quality all hang off the same request, so you debug from one place instead of stitching logs together by hand.

Keep exploring