--- title: "Tracing data model" description: "Understand how spans, traces, and sessions represent agent work in Judgment." seo: title: "Tracing Data Model | Judgment Docs" description: "Learn the Judgment tracing data model and choose trace, span, and session boundaries for AI agent work." --- Tracing records what your agent did. Each useful step becomes a span, the spans from one uninterrupted run form a trace, and related traces form a session. Judgment uses this structure to display, query, and evaluate agent work. ```mermaid flowchart TD Session["Session"] -->|"groups"| TraceA["Trace A"] Session -->|"groups"| TraceB["Trace B"] Session -->|"groups"| TraceC["Trace C"] TraceA -->|"contains"| SpanA1["Span 1"] TraceA -->|"contains"| SpanA2["Span 2"] TraceB -->|"contains"| SpanB1["Span 1"] TraceB -->|"contains"| SpanB2["Span 2"] TraceC -->|"contains"| SpanC1["Span 1"] TraceC -->|"contains"| SpanC2["Span 2"] ``` ## Example: one sales-assistant session > **Sales assistant example** > > A user asks, “Summarize my last meeting with Acme and draft a follow-up.” One > root span begins when the assistant receives that request and ends after it > returns the draft. Child spans record meeting search, transcript retrieval, > account lookup, model calls, and draft generation. Together, they form one > trace. > > If the user later says, “Send it,” that new request starts another trace. Both > traces share a session because they belong to the same continuing interaction. > > The root span must remain open until its child work finishes. Closing it before > the searches, model calls, or final response produces an incomplete trace and > leaves judges without the evidence needed to evaluate the run reliably. ## The data model | Term | What it covers | Use it when | | --- | --- | --- | | **Span** | One step, such as a model call, tool call, retrieval, or delegation. | You want to inspect the input, output, timing, metadata, or status of one step. | | **Trace** | One stretch of autonomous work, from one root through every child span. | You want to inspect or score one run end to end. | | **Session** | Related traces from one conversation, job, or workflow. | Work resumes after another request, queue delivery, retry, or human approval and should remain grouped. | A trace tree shows how the steps from one run nest. One support-chat trace, for example, can contain retrieval, response generation, and reply-saving spans. Design spans around the work the agent does, not around every function in the code. Start the root when the work begins, put useful agent steps beneath it, and end it only after its children finish. > **A useful trace tells the complete story** > > A teammate should be able to open one trace and identify the request, the > agent's final response, and the model, tool, retrieval, or application steps > that produced it. ## Choose what one trace covers Use one trace for an uninterrupted unit of agent work. When work pauses, continue in a new trace within the same session. > **Where one trace ends** > > Keep the trace open while the application can take the next step by itself. > End it when the application must wait for a user, request, queue delivery, > schedule, human approval, or another external signal. ## Group traces into sessions Use the same session ID for every trace in one conversation, job, or workflow. A crash, retry, replay, or worker replacement does not start a new session when the underlying job is still the same. | Work shape | Trace and session boundary | | --- | --- | | A chat turn or job that finishes without new outside input | One trace, which is also a one-trace session. | | A request that only places work on a queue | The worker starts the first trace when it receives the job. | | A request that starts or restarts work in its own process | The request gets its own trace in the job's session. | | Work before and after a human approval | Separate traces in one session. | | One live request crossing services | One distributed trace, with context propagated at every hop. | For example, one research session can group separate traces for submission, autonomous drafting, approval, and resumed final work. > **Instrumentation should not change the application** > > Do not buffer a streaming response or restructure jobs and retries to make the > trace tree look neater. Choose the guide that matches the application's real > runtime boundary. ## Keep agent work in the trace Every completed root becomes a trace that Judgment can score. Leave plumbing that contains no agent work out of the trace: - Health checks and status polls - Storage helpers - Routine middleware HTTP auto-instrumentation can create a root for every route. If the application already uses it, open a named `agent` span around the agent work and put the application input, output, and session ID on that span. ## Choose the matching runtime guide Keep a root open until generation and its callbacks finish. Trace loops, queues, workflow engines, retries, and approval waits. Record model calls made through a CLI or subprocess. Preserve instrumentation through bundling and runtime freezes. Propagate one live request across services. Decide when delegated work deserves a linked trace. ## Next step [Instrument your agent](/documentation/tracing/instrumentation), then run real agent work and verify the resulting trace in Judgment. Use [Add attributes and context](/documentation/tracing/attributes) after the trace structure is correct.