OpenTelemetry 1.40 defines GenAI agent spans, metrics, and opt-in payload capture rules. Use this cheat sheet to instrument faster. Read now.
What OpenTelemetry GenAI SemConv gives you
OpenTelemetry 1.40 formalizes how GenAI systems should emit telemetry so traces, metrics, and related attributes share a common vocabulary. Instead of inventing your own span names and attribute keys per service, you map agent runs, model calls, tool use, and retrieval steps onto the GenAI semantic conventions. That makes dashboards portable, reduces copy-paste drift across teams, and lets you compare latency and error rates across frameworks without rewriting exporters every time a library renames an internal hook.
Treat this post as a field guide: the spans and metrics you should wire first, what attributes belong on them, and how payload capture stays opt-in so you do not leak prompts or completions by default. The goal is faster instrumentation—start from the convention, then fill in your provider-specific glue.
Agent spans: the skeleton of a GenAI trace
A GenAI workflow is rarely a single request. An agent may plan, call a model, invoke tools, retrieve documents, then call the model again. Semantic conventions encode that as a parent agent (or operation) span with child spans for model inference, tool execution, and other discrete steps. Name and type attributes tell backends what kind of work each span represents; status and error attributes mark failures at the step that actually failed, not only at the outer HTTP boundary.
When you instrument, create the outer span when the agent session or user-facing operation starts, and nest each model or tool call underneath it. Propagate context into async workers and queue consumers so multi-hop agent loops still form one trace. Keep attributes stable and low-cardinality for routing and filtering: operation name, system or provider family, model identifier class, and outcome. High-cardinality values (raw user IDs, free-text prompts) belong elsewhere—or not at all—unless you have an explicit capture policy.
Metrics that answer operational questions
Spans explain a single run; metrics show fleet health. GenAI conventions define counters and histograms for request volume, duration, token usage where available, and error rates. Instrument at the same boundaries as your spans so a spike in model-call latency lines up with slow child spans in traces. Prefer recording duration on the model and tool spans, and aggregating token or cost-proxy attributes only when your stack exposes them reliably—missing optional attributes is better than inventing zeros.
- Request and operation counts by operation type and outcome
- Latency histograms for agent end-to-end and for model or tool children
- Token or usage attributes when the provider returns them, with clear units
- Error counters tagged by failure class (timeout, rate limit, validation), not free-text messages
Export these with the same resource attributes you use for other services (service name, deployment environment) so GenAI traffic sits next to the APIs that call it. Alert on error rate and latency first; add token-based budgets only after the basic signals are trustworthy.
Opt-in payload capture: useful, never accidental
Payload capture—prompts, completions, tool arguments, retrieved chunks—is powerful for debugging and evaluation, and dangerous if always on. OpenTelemetry GenAI conventions treat content capture as opt-in: you enable it deliberately, scope it to environments or sampling rates you control, and keep PII and secrets out of attributes that leave the process. Default instrumentation should record structure (span graph, timings, status, non-sensitive metadata) without embedding full message bodies.
In practice: ship structural telemetry everywhere; turn on payload attributes only behind a config flag, with redaction for credentials and personal data, and with retention rules that match your data policy. When capture is off, empty or omitted content fields should be the normal case—not a bug. That split lets you instrument faster without waiting on legal or security review for every service: the cheat sheet path is structural spans and metrics first, payload second, always opt-in.