Adopting OpenTelemetry GenAI Semantic Conventions Without Breaking Observability

OpenTelemetry’s GenAI semantic conventions give teams a shared vocabulary for model calls, agents, workflows, and tools. The safe way to adopt them in July 2026 is to pin a reviewed revision, map it behind an internal telemetry boundary, and migrate with contract tests. Do not let an instrumentation library’s latest schema silently become your production data contract.

This guide is about schema adoption and change control. For the mechanics of creating spans and propagating context, use our guide to tracing AI agents with OpenTelemetry.

Start with the right source of truth

The GenAI conventions no longer live in the versioned core semantic-conventions specification. The core site directs readers to the separate open-telemetry/semantic-conventions-genai repository. Its human-readable documents are generated from definitions in the repository’s model directory.

That distinction matters operationally. As of July 18, 2026, the separate repository has no published GitHub release and its README still lists the schema URL as a TODO. Its current agent-span document labels the specification Development. Treat the repository revision—not an unqualified moving version—as the artifact you adopted. Record the commit identifier in your observability manifest and dependency-renovation process.

At minimum, review these official documents together:

• GenAI model spans
• GenAI agent spans
• GenAI metrics
• GenAI events

Do not copy definitions from the old core GenAI attribute registry. That page explicitly marks the attributes deprecated because the work moved.

Put a translation layer between your code and the convention

Application code should emit a small, stable internal record. A telemetry adapter should translate that record into the pinned OpenTelemetry names. This limits migration work to one package and prevents provider SDKs from creating incompatible dashboards.

type ModelObservation = {
  operation: "chat" | "text_completion" | "embeddings";
  requestedModel: string;
  responseModel?: string;
  provider?: string;
  inputTokens?: number;
  outputTokens?: number;
  cacheReadTokens?: number;
  cacheWriteTokens?: number;
  timeToFirstTokenMs?: number;
  responseId?: string;
};

type TelemetrySchema = {
  revision: string;
  emitModelSpan(observation: ModelObservation): void;
};

Keep domain facts separate from their exported names. Your record can remain stable while the adapter changes gen_ai.* attributes, span naming, or status rules. Include the pinned convention revision as build metadata or a resource attribute in your own namespace, such as com.example.telemetry.gen_ai_revision; custom attributes should not impersonate standard ones.

Map operations before mapping attributes

The hardest compatibility bugs are usually structural, not spelling errors. Decide which operation each span represents and who owns it.

The current agent convention defines operations including create_agent, invoke_agent, invoke_workflow, plan, and execute_tool. An invoke_agent span is CLIENT for a remote agent and INTERNAL for an in-process agent. An execute_tool span requires the tool name. Follow the documented span-kind and naming rules instead of using every framework class as a span.

Create a reviewable matrix:

This also prevents duplicate spans. If a provider SDK already emits the model request, your framework should enrich that span or suppress its own equivalent—not wrap it in a second span with the same semantic meaning.

Preserve the convention’s precise meanings

Several fields invite plausible but incorrect values:

• gen_ai.conversation.id is an actual conversation identifier. The specification says not to invent one from a trace ID, random UUID, or content hash. Omit it when no conversation exists.
• Requested and response model identifiers are different facts. A provider can route or alias a requested model; retain both when available.
• Input token usage includes cached input tokens. If a provider reports both consumed and billed tokens, the convention says to use the billed count for the main usage value.
• Reasoning output tokens are included in output tokens. Recording them as an additional output category and then summing both double-counts usage.
• Time to first token is measured in seconds by the current semantic attribute. Converting an internal millisecond duration incorrectly creates a thousandfold error.

Turn each rule into a unit test. Semantic correctness cannot be recovered later from a valid-looking OTLP payload.

Default content capture to off

The current specification marks message bodies, system instructions, and tool definitions as opt-in and warns that they can contain sensitive information. That is a privacy boundary, not a dashboard preference. Capture identifiers, sizes, token counts, status, and latency by default; enable content only for an explicitly approved environment and sample.

OpenTelemetry’s sensitive-data guidance recommends data minimization plus filtering, redaction, or transformation. It also warns that hashing low-entropy values may be reversible in practice. Redact before export, restrict collector access, set short retention for diagnostic content, and test that secrets never reach a failed-export buffer.

Do not put prompts, user IDs, or authorization data in W3C Baggage. The W3C Baggage specification notes that baggage can propagate user-identifiable data and recommends removing private entries at trust boundaries. Trace Context should correlate work; it should not become a covert data channel.

Migrate with golden telemetry contracts

Capture representative OTLP data in a test exporter and assert the normalized result. Golden fixtures should cover:

1. A successful model response with streamed time to first token.
2. A provider error and a local timeout.
3. Cached input-token reporting.
4. A remote agent invoking a tool.
5. An absent conversation identifier.
6. Content capture disabled, including on errors.

Validate required attributes, units, enum values, parentage, span kind, and absence rules. Avoid asserting generated trace IDs or timestamps. Then run the same cases against the old and new adapters and produce a semantic diff.

During rollout, dual-write only if the temporary volume and cardinality are acceptable. A safer pattern is often to export one schema to a shadow dataset, rebuild queries there, and compare counts and latency distributions. Do not rename dashboard fields in place before alerts, saved queries, retention policies, and cost controls have moved.

Separate service identity from GenAI identity

Use stable resource attributes such as service.name, service.namespace, and service.version according to the OpenTelemetry service resource convention. Put agent, workflow, model, and operation details on the relevant spans. If a deployment creates a new service.name per prompt or agent instance, service-level dashboards become high-cardinality inventories instead of health views.

Propagate trace context across process boundaries using the W3C Trace Context Recommendation. Preserve a single causal trace, but let each service describe its own resource identity.

Ship only after these checks pass

• A specific GenAI repository revision is pinned and recorded.
• Operation, span kind, and parentage are reviewed before attributes.
• Provider and framework auto-instrumentation do not double-report calls.
• Units and token accounting round-trip through tests.
• Prompt and response content are off by default.
• Custom fields use an organization namespace.
• Shadow dashboards agree on event counts and explain intentional differences.
• Rollback restores the previous adapter without application changes.
• A scheduled owner checks upstream changes and re-runs fixtures before upgrades.

The conventions are most valuable when they make telemetry comparable. Pinning a revision does not reject the standard; it is what lets you adopt an evolving standard without corrupting historical meaning.