Trace conventions
Reference for OpenTelemetry resource, context, root-span, and Judgment attribute conventions.
Judgment tracing uses standard OpenTelemetry traces and context, with a small set of Judgment attributes that add agent, session, customer, model, usage, and cost semantics.
Trace and root boundaries
| Convention | Requirement |
|---|---|
| One root | A trace has one root span with no parent span ID. Every agent, model, and tool span for that autonomous run descends from it. |
| Autonomous work | Start the root when the application can begin work and end it before the application waits for new outside input. |
| Complete export | End children before the root, then flush according to the process lifetime. |
| Session continuity | Use judgment.session_id to group separate traces from one conversation, job, or workflow. |
Queues, checkpoints, retries that resume later, and approval waits start a new trace in the same session. One live request crossing services remains one trace when its context is propagated.
Resource attributes
Set service identity and deployment metadata on the OpenTelemetry resource, not repeatedly on individual spans:
| Resource attribute | Meaning |
|---|---|
service.name |
Stable name of the service that emitted the span. Give each service in a distributed trace a distinct value. |
service.version |
Deployed version of that service. |
deployment.environment |
Environment such as development, staging, or production. |
Services in one distributed trace use the same Judgment project and distinct
service.name values.
OpenTelemetry context
Use the normal OpenTelemetry propagator to inject context into an outgoing carrier and extract or continue it before starting downstream spans. This preserves the standard trace ID, parent span ID, trace flags, and trace state across process boundaries.
The Judgeval propagation.inject, Tracer.continue_trace(), and
Tracer.continueTrace() helpers use this OpenTelemetry context. Judgment’s
session identity is carried in baggage so downstream child spans can inherit
it. Continue the context before starting any downstream child; a span started
first becomes a new trace.
Use Distributed tracing for the complete send-and-receive procedure. Do not propagate a live trace across a queue or approval wait that resumes later; pass a stable job or session ID instead.
Judgment span semantics
| Field | Convention |
|---|---|
| Span name | Name the work performed, such as retrieve_context or generate_answer. |
judgment.span_kind |
Use agent for decision/delegation and roots, llm for one model call, and tool for a tool, function, or retrieval call. |
judgment.input and judgment.output |
Store the input received and output produced by the span that owns the work. |
| Model and usage attributes | Store them on the llm span only so cost is not counted twice. |
| Error status | Mark both thrown failures and handled failures that the application returns. |
| Custom attributes | Use an application-owned namespace; judgment.* is reserved for documented keys. |
See Attribute keys for the exact public Judgment fields and Add attributes and context for the SDK procedures.
Existing OpenTelemetry providers
Judgment can participate in an existing OpenTelemetry provider. In Python, add the Judgment span processor to the provider:
tracer_provider.add_span_processor(tracer.get_span_processor())For an exporter that does not use Judgeval, send OTLP/HTTP directly and map its attributes when necessary. See Direct OTEL and Configure attribute mappers.