← Blog

The state of the OpenTelemetry GenAI semantic conventions (July 2026)

2026-07-17

If you instrument an LLM or agent framework today, “using the OpenTelemetry GenAI semantic conventions” does not identify one telemetry schema. The conventions moved to a dedicated repository in 2026, every GenAI-specific surface remains in Development status, and the popular frameworks emit several different generations of the attributes at once. I ran into all three facts directly while tracing BrewTrace and APAB, and the ranking search results mostly miss them. This is the current map, as of July 17, 2026.

The conventions moved

The GenAI conventions now live in their own repository, open-telemetry/semantic-conventions-genai, which extends the core semantic conventions and holds the GenAI spans, events, metrics, provider pages, and MCP material. The main semantic-conventions repository’s v1.42.0 release (June 12, 2026) deprecated and moved all gen_ai.* content; v1.43.0 (July 3) ships none. The old documentation page at opentelemetry.io is now a pointer to the new home.

The practical catch: the dedicated repository has no releases or tags yet, and its README’s schema-URL section is still a TODO. You can follow a commit, a framework release, or a dated snapshot, but there is not yet a versioned GenAI-conventions release with a finalized schema URL to pin against. The last versioned cut of the GenAI conventions is main-repo v1.42.0, published as it moved out.

Stability is the same story stated precisely: as of July 17, 2026, no GenAI-specific span, event, metric, or attribute in the dedicated repository is marked Stable; the GenAI conventions remain Development. (Shared core attributes referenced in the same tables, such as error.type and server.address, are Stable; the gen_ai.* surface is not.)

The rename timeline

Six releases account for most of the churn a practitioner will meet in the wild:

The v1.38 evaluation event deserves a note because it connects tracing to eval harnesses: gen_ai.evaluation.result carries a required gen_ai.evaluation.name, a numeric score.value or categorical score.label, a recommended explanation, and a recommended gen_ai.response.id for correlation when direct span parenting is unavailable.

What frameworks actually emit

The specification is one thing; the telemetry that lands in your backend is another. The most useful measurement I have is my own: tracing a Strands Agents application into Jaeger, the spans carried legacy gen_ai.system=strands-agents (no gen_ai.provider.name), token usage under both attribute generations with identical values, and current-style span names (invoke_agent, chat, execute_tool). That mix is normal, and it is what the transition machinery produces by design. The state of the frameworks I have checked or traced:

Strands Agents defaults to the frozen v1.36-era compatibility behavior described above; the latest conventions are opt-in (issue #877). Query both provider fields and both token generations, and record the tested version. The BrewTrace walkthrough shows the full trace.

Pydantic AI uses the current structured format by default (instrumented models) and also emits gen_ai.system alongside gen_ai.provider.name for compatibility. Prefer the current fields while tolerating the duplicates.

Vercel AI SDK 7 is a new-generation implementation; OpenTelemetry support moved to the dedicated @ai-sdk/otel package (telemetry docs), emitting gen_ai.provider.name and gen_ai.usage.input_tokens, with the old ai.* namespace kept as a legacy path.

LangSmith documentation and examples remain mixed across generations, and its OpenTelemetry ingestion accepts both. Inspect the stored trace rather than inferring the schema from one example.

OpenAI Agents SDK ships built-in tracing on its own architecture (tracing docs); it does not emit the OTel GenAI conventions natively. OTel export goes through contributed instrumentation or a custom processor.

OpenLLMetry migration status varies by instrumentation package and configuration: some paths emit current structured attributes, others retain older behavior. Test the exact package and version rather than assigning one status to the whole project.

How to build on a moving spec

Pin your versions. The framework, the instrumentation, the OTel SDK, and the exporter each carry convention assumptions. A minor framework upgrade can change your attribute names.

Publish a dated tested-with table. In anything you write or ship, record exactly what you observed and when:

Query both generations. During the transition your analytics should recognize gen_ai.system and gen_ai.provider.name, and gen_ai.usage.prompt_tokens / input_tokens and completion_tokens / output_tokens. Coalesce with precedence; never sum the pairs, because frameworks that duplicate for compatibility emit the same value under both names:

COALESCE(
  attributes['gen_ai.provider.name'],
  attributes['gen_ai.system']
) AS gen_ai_provider

Own your internal representation. Keep a versioned internal model of providers, models, messages, token usage, tool calls, and evaluations; map framework telemetry into it, and map outward to the current convention at export time. A Development-status external schema should never be your database contract. This is the same own-the-spec argument from the eval harness post, applied to telemetry.

Keep custom attributes out of gen_ai.*. A future revision can claim any name in a reserved namespace. BrewTrace stamps its domain attributes as brew.*, taste.*, and eval.* for exactly this reason.

The opt-in mechanism, for when you want the new behavior: instrumentations participating in the transition preserve the earlier v1.36-era output by default, and where the instrumentation supports it, setting OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental selects the latest experimental conventions. Confirm with a real exported span; not every framework honors the variable identically.

The takeaway

OpenTelemetry remains the right interchange layer for LLM and agent telemetry, and the conventions are converging on a good shape: structured messages, first-class agent spans, an evaluation event. But “OpenTelemetry-compatible” is not yet a sufficient schema contract for GenAI telemetry. Pin what you run, inspect what actually lands, normalize across generations, and date what you tested.

This is independent analysis based on public OpenTelemetry specifications, release notes, framework documentation, and locally observed telemetry. The projects and trademarks mentioned belong to their respective owners; no affiliation or endorsement is implied. The views are my own and do not represent any current or former employer.