OpenTelemetry GenAI semantic conventions

OpenTelemetry GenAI semantic conventions are a vendor-neutral schema for what an AI application should record in its traces. They define standard span types and attribute names under the gen_ai.* namespace covering model calls, tool calls, agent invocations, and sessions, so that a trace emitted by one application can be read by any observability backend that understands the convention.

The work began in the OpenTelemetry GenAI special interest group in 2024 and reached a state teams could reasonably build against by early 2026. Guidance from that period, including Zylos on OpenTelemetry for AI agents in February 2026 and agent observability guides from MLflow and Braintrust in June 2026, treats the conventions as the interoperability layer beneath the tooling market. Parloa defines AI observability as collecting and analyzing telemetry across AI system components to understand performance, cost, quality, and safety in real time; the conventions are what make that telemetry portable rather than locked to whichever vendor an organization picked first.

The problem with proprietary trace formats

Before a shared convention, every AI observability product defined its own trace shape. One called the model identifier model, another model_name, a third nested it under a provider object. Token counts were split by input and output under different names, reported as a total, or not captured. Tool calls were first-class spans in one system and log events in another.

The consequence was that instrumentation became an investment in a vendor rather than in the application. Switching backends meant rewriting instrumentation across every service that touched a model, and running two in parallel meant instrumenting twice. A second cost mattered more day to day: because each AI gateway, framework, and agent library emitted its own shape, one request crossing three of them produced three incompatible partial views.

What the conventions standardize

The conventions standardize two things: the operations that deserve a span, and the names of the attributes attached to those spans. Both live under the gen_ai namespace so they stay unambiguous alongside HTTP and database conventions in the same trace.

Operation identity. Every GenAI span declares what kind of operation it represents through gen_ai.operation.name, letting a backend distinguish a chat completion from an embedding call from a tool execution without knowing anything about the application.

Request parameters. The model being called and its parameters are recorded under stable names such as gen_ai.request.model, so cost and behavior can be attributed to a model version across every service rather than reconstructed from application-specific fields.

Usage and cost. Token accounting has standard attributes, including gen_ai.usage.input_tokens, which is what makes token usage aggregable across services and providers. Cost analysis is arithmetic on these fields; without a shared name, it is a per-vendor mapping exercise.

Tool and agent semantics. The conventions describe how to represent a tool call and an agent invocation as spans in their own right, with the tool name and agent identity as attributes, rather than burying them inside a model span.

Message content is also addressed: prompts and completions frequently contain personal data, so capturing them is explicitly opt-in, keeping PII redaction a decision the application controls.

How spans nest across an agent run

The value of the schema shows up in the tree structure, not in any single attribute. A production agent run produces a nested trace that reads top to bottom as a description of what happened.

At the outermost level sits the session, grouping everything in one customer interaction across however many turns it takes. Inside it, each agent invocation is its own span covering one turn of reasoning and action. Inside that, model calls appear as child spans carrying model, parameters, and token usage, with tool calls as siblings holding their own timing and outcome.

When an agent delegates, the nesting deepens. In a multi-agent system, a supervisor's span contains the sub-agent invocation spans it triggered, each with its own model and tool children. Because context propagation is standard OpenTelemetry behavior, the tree holds together even when the sub-agent runs in a different service, and a tool calling a downstream API produces an HTTP span underneath it using the ordinary HTTP conventions. The result is a single trace where an agentic workflow can be read end to end, which is also the raw material a trajectory evaluation pass consumes.

Stability and adoption

Honesty about maturity is warranted. The GenAI conventions moved faster than most OpenTelemetry conventions because the domain was moving, and parts of them spent a long time marked experimental, so attribute names could change between releases. By early 2026 the core model-call and tool-call attributes had settled enough that instrumenting against them was a reasonable bet, while agent and multi-agent semantics remained less settled.

Adoption arrived from two directions. Agent frameworks and gateways began emitting conforming spans natively or through instrumentation libraries, so applications inherited compliant telemetry without writing it. Observability vendors added ingestion alongside their proprietary formats, since supporting a standard customers already emitted was cheaper than defending a bespoke one. The practical state for most teams is partial conformance.

Why portability matters when choosing an observability vendor

For a support organization running AI agents, the conventions change the shape of a procurement decision. When instrumentation conforms to a standard, the observability backend becomes a consumer of data the application already produces rather than the reason the data exists. Switching costs drop from a rewrite to a configuration change.

It also enables more than one consumer of the same telemetry, which is the common steady state. The same spans can feed an operational dashboard, a cost model, and an evaluation pipeline that scores sampled conversations, without three instrumentation efforts. The questions a support team asks of its traces are not only engineering questions: cost per resolution, escalation patterns, and quality regressions all compute from the same spans. Portability is also a defense against silent agent drift, since detecting slow behavioral decay requires trace data that stays comparable across months, model changes, and tooling migrations.