OpenTelemetry GenAI Semantic Conventions: What's Stable

If you are instrumenting AI agents with OpenTelemetry and asking which gen_ai.* attributes are safe to build dashboards, alerts, or long-term storage schemas against: none of them, as of mid-2026. Every gen_ai.* attribute, span, metric, and event in the OpenTelemetry semantic-conventions registry is marked stability "Development," not "Stable" — and the conventions were recently moved to a new, separately versioned repository that had not yet shipped a tagged release at the time of writing. This instability is not a minor caveat; it is the central fact a team building agent observability right now needs to plan around.

What "Development" stability actually means

OpenTelemetry's semantic conventions use a maturity ladder, and "Development" sits well below "Stable." A convention at Development stability can change shape, be renamed, or be removed entirely between releases without the deprecation cycle that stable conventions get. Concretely, that means a gen_ai.request.model or gen_ai.usage.input_tokens attribute you instrument against today could have a different name, a different type, or a different semantic meaning in a future release — and OpenTelemetry gives no contractual guarantee otherwise while it carries this status. This is a materially different risk than, say, HTTP semantic conventions, which reached stability years ago and change rarely and predictably.

For teams used to treating OpenTelemetry as "the vendor-neutral standard, therefore safe to build on long-term," the GenAI conventions specifically break that assumption for now. The protocol (OTLP) is stable; the specific field names for LLM and agent telemetry are not.

This distinction between transport stability and semantic stability is not unique to GenAI — OpenTelemetry has shipped Development-stability conventions for other domains before they matured, database and messaging semantics among them. What is unusual here is how load-bearing the GenAI conventions have already become for a fast-growing category of tooling: cost dashboards, guardrail-trigger alerting, and even some vendors' compliance exports are already being built against gen_ai.* fields, well ahead of those fields reaching a stability guarantee. That gap between adoption speed and specification maturity is the practical risk, more than the instability itself.

Why agent telemetry specifically is exposed to this

Traditional service telemetry (HTTP status codes, database query spans, message-queue metrics) has had years to converge on stable OpenTelemetry conventions, largely because the underlying concepts — a request, a query, a message — have not changed shape much in that time. LLM and agent telemetry is being specified while the underlying systems it describes are still changing: new agent frameworks emerge, multi-step tool-calling patterns evolve, and providers keep adding response shapes (reasoning traces, structured tool-call formats) that did not exist when earlier attribute proposals were drafted. Specification work is racing a moving target, which is a reasonable explanation for why GenAI conventions remain unstable years after service-level conventions matured, but it does not reduce the practical risk for teams instrumenting today.

The June 2026 repository move

In June 2026, with semantic-conventions release v1.42.0, the GenAI conventions were deprecated out of the main open-telemetry/semantic-conventions repository and moved to a new, dedicated repository, open-telemetry/semantic-conventions-genai. As of mid-July 2026, that new repository had not produced a tagged release. Repository moves of this kind typically happen when a working group wants room to iterate faster than the main repo's release cadence allows — a reasonable engineering decision — but the practical effect for adopters is that the conventions are, for a period, in a less discoverable, less versioned state than before the move, on top of already carrying Development stability.

If your instrumentation currently references the old location or pins to a specific main-repo release for GenAI attribute definitions, that reference needs to be revisited once the dedicated repository starts tagging releases — the attribute set it ships may not be identical to what shipped from the main repo before the move.

The stability opt-in mechanism

OpenTelemetry ships an OTEL_SEMCONV_STABILITY_OPT_IN environment variable specifically to manage transitions like this one across the ecosystem — it lets instrumentation and collectors choose between emitting old and new attribute shapes during a convention's transition period. Its existence for GenAI conventions specifically is itself evidence that the working group expects the attribute shapes to keep shifting; teams instrumenting now should treat this variable as a live control they will need to revisit, not a one-time setting.

What this means for teams instrumenting agents now

None of this is a reason to avoid OpenTelemetry for agent observability — OTLP as a transport and the overall tracing model (spans, parent-child relationships, resource attributes) are stable and well-established, and using them is still the right default over inventing a proprietary schema. The caution applies narrowly and specifically to the gen_ai.* attribute names and shapes.

Practical implications:

1. Do not hard-code gen_ai.* attribute names into long-lived alerting rules or dashboards without a migration plan. Treat them the way you would treat any interface still under active change — abstracted behind a mapping layer if the cost of doing so is reasonable.
2. Watch the dedicated repository's first tagged release, not the main repo, going forward. The move means the source of truth has changed location.
3. Don't assume vendor tools that advertise "OpenTelemetry-native" or "OpenInference" support are pinned to a frozen schema. They are aligned with a moving target, and different vendors may track different points in that evolution — worth confirming directly with each vendor rather than assuming parity. See LLM observability tools for security teams for how this shows up across specific named tools, several of which describe themselves as OpenTelemetry-native.
4. Keep audit-grade records independent of the attribute names, not dependent on them. If a compliance-relevant record (which agent called what, when, with what outcome) is built on top of gen_ai.* fields that could rename between releases, the record's durability is coupled to a convention that explicitly does not promise durability yet. See tamper-evident audit logs and cryptographic proofs and audit trails that hold up for why audit records generally need a stability guarantee independent of any single telemetry schema.
5. Export to a backend and storage layer you control. Whichever way the conventions eventually settle, having the raw data in infrastructure you operate — Prometheus, a data warehouse, a SIEM — means a future attribute rename is a re-mapping exercise, not a data-loss event. The general pattern for keeping metrics portable this way is covered in Prometheus metrics and observability.

A stability snapshot

This table is a snapshot, not a permanent reference — semantic conventions are explicitly in flux, and this post should be re-checked against the live OpenTelemetry registry before being cited as current beyond its publication date.

How to build for change without waiting

Waiting for stability before instrumenting agents at all is not a realistic option — the operational need for telemetry now (cost attribution, behavioral traces, policy events) does not pause for a spec to mature. The practical middle path most teams take: instrument with the current gen_ai.* conventions where they exist (better a moving target than nothing, and OpenTelemetry's own tooling is built to help manage the migration), export to a backend you control rather than one that hard-codes vendor-specific field names, and keep the interpretation layer — dashboards, alert rules, compliance mappings — decoupled enough from raw attribute names that a rename is a config change, not a rewrite. The general pattern for keeping cost and behavioral telemetry portable across backends is discussed in observability for AI agents and OTLP telemetry ingest and agent discovery.

Praesidia is an AI agent security and governance control plane — agent identity and access, guardrails, audit evidence, and cost controls in one place. The caution above applies regardless of which control plane or observability stack you pair with your agents: verify current gen_ai.* field names against the live registry, not against any point-in-time documentation, including this post's.

The general reasoning for treating telemetry and policy signals as first-class, portable data is covered in the AI control plane guide.

Common questions

Is it safe to use gen_ai. attributes at all right now?* Yes, with the caveat that they may change. Using them is still better than inventing a proprietary schema, because you inherit whatever tooling and migration support the OpenTelemetry ecosystem builds around the eventual stable version. Just do not treat today's field names as a permanent contract.

When will the GenAI conventions become stable? There is no published timeline as of the 2026 roadmap discussion. Repository moves like the June 2026 shift to a dedicated repo are sometimes a precursor to faster iteration toward stability and sometimes simply a reorganization — the move alone does not signal an imminent stable release.

Does this affect the OTLP protocol itself? No. OTLP as a transport protocol and the general tracing data model (spans, resources, parent-child relationships) are mature and stable. The instability is specific to the GenAI semantic conventions — the agreed-upon names and shapes for LLM- and agent-specific attributes layered on top of that stable transport.

Should we wait for stability before instrumenting our agents? No — the operational value of instrumenting now outweighs the migration cost of a future rename, provided you build with the decoupling practices above. Waiting means going without cost attribution, behavioral traces, and policy signals for however long stabilization takes, which is currently undated.

How do I find the current status myself rather than trusting this post? Check the OpenTelemetry semantic-conventions registry and the open-telemetry/semantic-conventions-genai repository directly — stability levels and release tags are the two facts to look for, and both are the kind of detail that changes between when this was written and when you are reading it.

What should I do if my dashboards already depend on gen_ai. attribute names?* Add a thin mapping layer between the raw attribute names and whatever consumes them — dashboards, alert rules, compliance exports — so that a future rename in the source data is a one-line change to the mapping rather than a rewrite across every consumer. This is the same decoupling practice teams already use for any external schema they do not control, applied here because the GenAI conventions are explicitly still in that category.