The OpenTelemetry GenAI semantic conventions are OpenTelemetry’s standard names for recording generative AI work: gen_ai.* attributes, span shapes and metrics for model calls, tool calls and agent runs, such as which model was called, by which provider and with how many input and output tokens. As of October 2026 every part of them is still marked Development, so names can change, and since June 2026 they live in their own repository. Instrumentation libraries emit them for you; your backend reads them to compute cost and latency.
Key takeaways
- A model-call span needs only
gen_ai.operation.nameandgen_ai.provider.name; the model and token counts are where cost data lives. - All
gen_ai.*names are Development in 2026: use them, but expect renames and pin library versions. - The conventions describe the AI call, not your business. Customer, plan and team labels are yours to add.
What are the OpenTelemetry GenAI semantic conventions?
A shared vocabulary for AI telemetry, so any OpenTelemetry backend can understand AI spans from any instrumentation that follows it. Instead of each library inventing its own name for “model” or “tokens”, the conventions fix one set.
They cover spans for inference, embeddings, retrieval, tool execution, agents and workflows; metrics such as gen_ai.client.token.usage and gen_ai.client.operation.duration; events; and provider pages for Anthropic, Azure AI Inference, AWS Bedrock and OpenAI, plus the Model Context Protocol (model spans). For an engineering manager the point is simple: telemetry that follows them can move between backends without re-instrumenting.
Which gen_ai.* attributes matter most?
The operation, the provider, the model and the token counts. Requirement levels from the model spans page, as of October 2026:
| Attribute | Level | Used for |
|---|---|---|
gen_ai.operation.name | Required | chat, embeddings, execute_tool, invoke_agent and others |
gen_ai.provider.name | Required | Which provider served the call |
gen_ai.request.model | Conditionally required | The model you asked for |
gen_ai.response.model | Recommended | The model that actually answered |
gen_ai.usage.input_tokens, output_tokens | Recommended | Cost and context size |
gen_ai.usage.cache_read.input_tokens, cache_creation.input_tokens | Recommended | Cached tokens, priced differently |
gen_ai.conversation.id | Conditionally required | Grouping turns; never invent one |
Older instrumentation often uses earlier names, such as gen_ai.usage.prompt_tokens, so one backend may receive both spellings from different services.
How are LLM calls, tool calls and agents represented?
Each operation is its own span, and an agent run is a trace where model and tool spans nest under an agent span. Model-call spans are named {gen_ai.operation.name} {gen_ai.request.model} with span kind CLIENT; agent spans are named invoke_agent {gen_ai.agent.name}; tool spans use the execute_tool operation with gen_ai.tool.name (agent spans). One run looks like this:
invoke_agent support-agent
chat claude-sonnet input 2,100 output 180
execute_tool search_orders
chat claude-sonnet input 4,900 output 220Prompts and completions are opt-in: gen_ai.input.messages, gen_ai.output.messages and gen_ai.system_instructions often contain personal data, so capture them deliberately.
Are the GenAI semantic conventions stable in 2026?
No. Every gen_ai.* attribute, span and metric is marked Development as of October 2026, which means names can change without a long deprecation period.
The bigger change this year was the move. Release v1.42.0 of the main semantic-conventions repository, published on 12 June 2026, deprecated all gen_ai.* definitions there and moved them to open-telemetry/semantic-conventions-genai (release notes); the old opentelemetry.io pages now point there (notice). In practice:
- Pin instrumentation library versions and check a trace after every upgrade.
- Prefer a backend that reads both old and new names.
- Keep any attribute names you write yourself in one module.
What should you add yourself?
Business context. The conventions describe the AI operation, not who it was for. Add a customer or user ID to every span (an opaque internal ID), name your agents with gen_ai.agent.name so several agents in one service stay apart, and set service.name and deployment.environment as resource attributes. Labels such as customer.plan or team make cost allocation possible.
How do OTLP backends like Tracium use these attributes?
They read them to decide what each span is, which model it used and what it cost. In Tracium’s collector source:
- Model and tokens:
gen_ai.request.model, falling back togen_ai.response.model, plus input, output and cache tokens under both the current names and OpenLLMetry’s older ones. The collector prices each span from these and ignores any cost the sender reports (cost & usage). - Span kind: OpenInference and OpenLLMetry span kinds first, then
gen_ai.operation.name; a span with a model or tokens counts as an LLM call. - Workflow name:
gen_ai.agent.namefirst, then OpenLLMetry’s workflow and entity names, thenservice.name. - Content: semconv message attributes and OpenLLMetry’s indexed prompts are shown when capture is on and stripped before storage when it is off.
Because Tracium accepts standard OTLP with an ingest key, there is no Tracium SDK to install (OpenTelemetry setup).
[ADD: screenshot of a Tracium trace showing agent, chat and tool spans with token counts]
When is Tracium a good fit, and when is another tool better?
Tracium fits if you want to stay on these conventions, care mostly about cost per agent, model and customer, or need to self-host the open-source version. If you need evaluations, datasets and prompt management alongside tracing, Langfuse, Arize Phoenix or LangSmith go further. Because the conventions are vendor-neutral, the same spans can go to more than one backend.
FAQ
Are the OpenTelemetry GenAI semantic conventions stable?
No. As of October 2026 they are marked Development. They are widely implemented anyway, so use them and pin your instrumentation versions.
Where do the GenAI semantic conventions live now?
In the open-telemetry/semantic-conventions-genai repository. Release v1.42.0 of the main repository moved them there in June 2026.
Do I need to write gen_ai.* attributes myself?
Usually not. Instrumentation libraries such as OpenLLMetry or OpenTelemetry’s own GenAI instrumentations set them on model-call spans; you add business labels such as a customer ID.
The GenAI conventions are still moving, but they already carry what cost and reliability need: model, tokens, operation and agent. To see your own gen_ai.* spans as cost per agent, model and customer, try the open-source Tracium collector on GitHub, or sign up free at app.tracium.ai and point your OTLP exporter at it.