Nothing in OpenTelemetry's GenAI semantic conventions is Stable yet — should you instrument agents now?
Every definition in OpenTelemetry's GenAI semantic conventions is still at Development stability. Should you instrument your agents now?
On this page
Once an agent is in production, you need to see what happened. OpenTelemetry's GenAI semantic conventions are the agreement
that lets different tools record the same thing under the same name.
But on June 12, 2026, the entire GenAI section was marked “deprecated” in its original repository and moved to a separate repository,
and as of September 8, 2026, the new repository has no release tags at all.
Every stability level in the convention definition files is Development (development), and OpenTelemetry's own rules
advise against taking long-term dependencies on anything in Development.
1. Executive summary
Instrumentation means adding code that records what happened while a program runs.
Semantic conventions are an agreement to “call the same thing by the same name” in those records.
If every tool agrees to call token usage gen_ai.usage.input_tokens, you can keep reading your existing records
even after you switch observability tools. Without that agreement, each tool uses different names, and moving between them comes with conversion work.
All 10 convention definition files checked
Since it was created on 2026-05-05
gen_ai.* attributes currently defined2. What moved where
OpenTelemetry's semantic conventions used to live together in one repository, open-telemetry/semantic-conventions.
The GenAI conventions have been split out of it into a separate repository. Below, the original repository means that one, and the new repository means the one the conventions moved to.
| Date | What happened |
|---|---|
| 2026-05-05 | open-telemetry/semantic-conventions-genai repository created |
| 2026-06-12 | Original repository v1.42.0 released — gen_ai.* attributes, metrics, events and spans all marked “deprecated” and moved to the new repository |
| 2026-08-04 | Latest release of the original repository, v1.44.0 |
| 2026-09-08 | New repository has 0 releases · 0 tags. Commits were still landing that day |
Source · release and tag lists for both repositories and the v1.42.0 release notes, queried directly through the GitHub API on 2026-09-08.
The v1.42.0 release notes put it this way —
“All gen_ai.* attributes, metrics, events, and spans have been deprecated and moved to
the dedicated OpenTelemetry GenAI Semantic Conventions Repository”.
gen_ai.system, gen_ai.prompt, gen_ai.completion and gen_ai.usage.prompt_tokens, which were common in 2025 examples, do not exist in the current registry under those exact names (checked 2026-09-08). Similar but different keys do exist — gen_ai.prompt.name, for example. The role of gen_ai.system is now filled by gen_ai.provider.name.
And because the new repository has no tags, there is no official version to pin as your baseline.
You have to use a commit hash, a framework release or a dated snapshot as the baseline.
3. What Development status means
OpenTelemetry assigns a maturity level to each specification. The GenAI convention definition files record a level for every attribute
and every allowed value, and in all 10 files we checked, every level was Development (development).
Not one was Stable (stable).
Spans do, however, also use attributes from other repositories — error.type, for example, belongs to the main conventions and is Stable.
Development — the current stage
From the OpenTelemetry specification:
“While signals are in development, breaking changes and performance issues MAY occur. Components SHOULD NOT be expected to be feature-complete. In some cases, the signal in Development MAY be discarded and removed entirely. Long-term dependencies SHOULD NOT be taken against signals in Development.”
A signal here is OpenTelemetry's word for a kind of telemetry data, such as traces, metrics and logs.
The original says SHOULD NOT: a strong recommendation, not a prohibition.
Stable — the stage not yet reached
“Once a signal in Development has gone through rigorous testing, it MAY transition to Stable. Long-term dependencies MAY now be taken against this signal.”
In other words, what separates the two levels is exactly “can you rely on it for the long term?”
Source · OpenTelemetry specification, versioning-and-stability.md. The Korean original quoted these passages in Korean translation; this edition quotes the English original verbatim.
4. What is defined today
Not being final does not mean nothing is defined. The attribute registry, the list that collects attribute names and their meanings, defines 72 attributes, and topics this blog has covered separately also appear in it as entries.
| Group | Count | What it holds |
|---|---|---|
gen_ai.request.* | 15 | Request parameters — model, temperature, max tokens and so on |
gen_ai.usage.* | 14 | Token usage, broken down further into audio, cache reads and so on |
gen_ai.tool.* | 7 | Tool calls — arguments, call ID, result |
gen_ai.memory.* | 5 | Memory lookups — query text, record count and IDs, store ID |
gen_ai.response.* | 5 | Responses — finish reason, response ID, actual model name |
gen_ai.agent.* | 4 | Agents — name, ID, description, version |
gen_ai.evaluation.* | 4 | Evaluation — evaluation name, score, label, explanation |
gen_ai.prompt.* | 3 | Prompts — name, version, variables |
gen_ai.retrieval.* | 3 | Retrieval — query text, documents, top-k |
gen_ai.conversation.* | 2 | Conversation ID, whether the conversation was compacted |
Source · we counted the - key: entries in the model/gen-ai/registry.yaml source. The table shows the top 10 groups by count; the total is 72.
What you must include
A span is the unit of record that represents one stretch of work. The generated documentation has six tables, one per span type.
gen_ai.operation.name is Required in all six, and
gen_ai.provider.name is Required in three and Conditionally Required in two.
gen_ai.request.model is Conditionally Required, recorded when the value is known, and error.type is Conditionally Required, recorded when the operation ended in an error;
the remaining attributes are Recommended.
gen_ai.operation.name currently has 18 possible values. This one attribute distinguishes not only model calls but also
agent, tool, workflow and memory operations —
chat, generate_content, text_completion, embeddings,
retrieval, fetch_response, create_agent, invoke_agent,
execute_tool, invoke_workflow, plan, and seven memory-related values.
model/mcp/ is being worked out
so that the tool-call layer is recorded in the same scheme. That part, too, is of course development.
5. Should you instrument now anyway?
“Let's wait until the conventions are final” is not a realistic answer, because everything this blog has covered so far is a problem you can judge only if you have records.
| Problem covered earlier | Without records | Matching attributes |
|---|---|---|
| Is the cache actually being hit? | You cannot tell whether cost went down | The cache-read entries in gen_ai.usage.* |
| Is it repeating the same step? | The repetition goes unnoticed | gen_ai.operation.name + conversation ID |
| Does it act differently from what it said? | You cannot see the reasoning and the tool calls side by side | gen_ai.tool.call.* (arguments and results are Opt-In, recorded only when enabled) |
| Where do evaluation scores go? | Run records and scores live in separate places | gen_ai.evaluation.* |
The links in this table are not proposed by the convention documents; we matched this blog's earlier articles to the attribute names.
Conversely, avoid hard-coding attribute names into dashboard queries, alert rules and storage schemas. Those are much more tedious to fix, and you end up quietly looking at empty graphs without realizing a name changed.
6. What you can do today
| No. | Task | Why |
|---|---|---|
| 1 | Check whether the attribute names you currently emit are deprecated | If you instrumented from 2025 examples, they may be the names from before the move |
| 2 | Collect the code that defines attribute names in one file | The next time the names move, there is only one place to fix |
| 3 | Start with gen_ai.operation.name | It is the only attribute that is Required in all six span tables. gen_ai.provider.name is also Required in most of them, so add it too |
| 4 | Record token usage with cache reads broken out separately | gen_ai.usage.* is already broken down that way |
| 5 | Decide deliberately whether to keep tool call arguments and results | The kind of failure where reasoning and execution diverge only shows up when you look at the two side by side. But the conventions record arguments and results only when you explicitly choose to (Opt-In), so they are not recorded by default, and they can contain user input, personal data and credentials as-is. If you turn them on, add masking and an allowlist at the same time |
| 6 | Do not put attribute names directly into dashboard queries and alert rules | If the names change, you quietly get empty graphs |
| 7 | Check the new repository now and then for a release tag | The moment a tag appears is the moment you can pin a version |
7. What this is not yet
- This is the state as of 2026-09-08. Commits were still landing in the new repository that day. If a release tag appears or some entries move up to Stable, this article's premise changes.
- We looked only at the 10 convention definition files. We counted the
stabilitydeclarations in the YAML files undermodel/, and all of them weredevelopment. We did not go through the repository's other documents or branches. - The 72 attributes are counted from the registry. The number is the count of
- key:entries inmodel/gen-ai/registry.yaml, and it does not include the provider-specific files (openai·aws-bedrock) or the MCP attributes. - The spec quotations were translations in the Korean original. There, the stability-level descriptions were rendered from the English original into Korean; this edition quotes the English original, and the original wording takes precedence.
- The required attributes are based on the generated span documents. We confirmed that
gen_ai.operation.nameandgen_ai.provider.nameare markedRequired, but we did not check exhaustively whether the requirement level can differ by span type. - We could not check the state of implementations. This article did not investigate how far each language SDK and observability tool has caught up with these conventions. The convention documents and the actual instrumentation libraries may be at different stages.
- The links in section 5 are our judgment. We matched the problems from earlier articles to attribute names; the convention documents do not suggest these uses.
8. Sources
| Source | What we used it for | Link |
|---|---|---|
| OpenTelemetry GenAI semantic conventions repository | Created 2026-05-05; 0 releases and tags (queried 2026-09-08); every stability value in the model files; 72 attributes; 18 values of gen_ai.operation.name; the MCP conventions included |
github.com/open-telemetry/semantic-conventions-genai |
| OpenTelemetry semantic conventions main repository — v1.42.0 release notes | Deprecation and move of all gen_ai.*, dated 2026-06-12 |
github.com/open-telemetry/semantic-conventions — v1.42.0 |
| OpenTelemetry specification — Versioning and stability | Definitions of the Development and Stable levels. The sentence “Long-term dependencies SHOULD NOT be taken against signals in Development.” | opentelemetry-specification — versioning-and-stability.md |
We checked repository status through the GitHub API, the convention content from the YAML source in the repository, and the level definitions from the original specification text, all on 2026-09-08. We did not cite secondary write-ups. This area changes from month to month, so recheck the repository before you start instrumenting.