---
title: "Trace conventions"
description: "Reference for OpenTelemetry resource, context, root-span, and Judgment attribute conventions."
seo:
  title: "Judgment Trace Conventions Reference"
  description: "Reference for root spans, OpenTelemetry context propagation, service resources, and Judgment trace semantics."
---

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](/documentation/tracing/distributed) 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](/documentation/tracing/attribute-keys) for the exact public
Judgment fields and [Add attributes and context](/documentation/tracing/attributes)
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:

```python
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](/documentation/integrations/tracing-providers/direct-otel)
and [Configure attribute mappers](/documentation/tracing/attribute-mappers).

## Related pages

- [Tracing data model](/documentation/tracing)
- [Distributed tracing](/documentation/tracing/distributed)
- [Project routing](/documentation/reference/project-routing)