Tracing data model
Understand how spans, traces, and sessions represent agent work in Judgment.
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.
Example: one sales-assistant session
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.
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.
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.
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
Streaming
Keep a root open until generation and its callbacks finish.
Durable work
Trace loops, queues, workflow engines, retries, and approval waits.
Subprocess models
Record model calls made through a CLI or subprocess.
Bundled and serverless runtimes
Preserve instrumentation through bundling and runtime freezes.
Distributed tracing
Propagate one live request across services.
Trace subagents
Decide when delegated work deserves a linked trace.
Next step
Instrument your agent, then run real agent work and verify the resulting trace in Judgment. Use Add attributes and context after the trace structure is correct.