OpenTelemetry GenAI Semantic Conventions
by OpenTelemetry
The vendor-neutral schema for tracing LLM calls, agents, tools and MCP — and an honest account of how unstable it still is.
Overview
These conventions define the attribute, span, metric and event names that instrumentation libraries emit for generative AI workloads, so telemetry from LangChain, Pydantic AI or the Vercel AI SDK lands in a shape any OpenTelemetry backend can query. As of the v1.42.0 release of the core semantic-conventions repository (June 2026) all gen_ai content was deprecated there and moved into the dedicated open-telemetry/semantic-conventions-genai repository, which uses Weaver to depend on core conventions rather than duplicate them. The docs directory carries gen-ai-spans.md, gen-ai-agent-spans.md, gen-ai-metrics.md, gen-ai-events.md and gen-ai-exceptions.md for the general signals, mcp.md for Model Context Protocol operations, and provider-specific files anthropic.md, openai.md, azure-ai-inference.md and aws-bedrock.md; an auto-generated registry documents the gen_ai.*, mcp.* and openai.* attribute namespaces. Concretely you learn spans such as chat, invoke_agent and execute_tool, and attributes including gen_ai.provider.name (which replaced gen_ai.system), gen_ai.usage.input_tokens and gen_ai.usage.output_tokens, plus the gen_ai.evaluation.result event added in v1.38.0. The critical caveat, and the reason to read the spec rather than trust a library: as of mid-2026 no GenAI-specific span, event, metric or attribute is marked Stable — the whole surface is Development, the new repository has no releases or tags yet, and its schema URL is still a TODO. Frameworks consequently emit several attribute generations at once, so pin versions and query both old and new names.
At a Glance
- Topic
- Frameworks
- Level
- Advanced
- Format
- Documentation
- Cost
- Free
- Duration
- ~2-3 hours to read the spec docs; ~1 day to instrument a service against them
- Provider
- OpenTelemetry
- Hands-on
- Yes — code/exercises
- Certificate
- None
What You’ll Learn
- ✓Name spans and attributes so traces are portable across observability backends
- ✓Instrument chat, invoke_agent and execute_tool spans correctly for agent workloads
- ✓Record token usage with gen_ai.usage.input_tokens and gen_ai.usage.output_tokens consistently
- ✓Trace Model Context Protocol operations using the dedicated mcp.* attribute namespace
- ✓Handle the gen_ai.system to gen_ai.provider.name rename without breaking existing dashboards
- ✓Emit evaluation results as gen_ai.evaluation.result events correlated to the run
- ✓Judge which frameworks emit current conventions and which still emit older generations
Highlights
- •Vendor-neutral: the only cross-framework schema an LLM observability stack can standardise on
- •Splitting out of the core repo means GenAI conventions can move faster than the OTel release train
- •Provider-specific files for OpenAI, Anthropic, Bedrock and Azure sit alongside the general spec
- •MCP gets first-class conventions, which almost no proprietary tracing product covers yet
- •The Development-not-Stable status is documented plainly, so you can plan around the churn instead of discovering it
Who It’s For
Best For
- ✓Platform engineers building LLM observability they intend to maintain for years
- ✓Framework and SDK authors adding tracing to an agent library
- ✓SRE and reliability teams standardising telemetry across several AI services
Prerequisites
- •Working knowledge of OpenTelemetry traces, metrics and the core semantic conventions
- •Experience instrumenting a production service with an OTel SDK
- •Familiarity with LLM application shapes — tool calls, agent loops, retrieval
FAQ
What is OpenTelemetry GenAI Semantic Conventions?
The specification that defines how spans, metrics, events and attributes for generative AI workloads should be named, so traces from one framework are readable by any backend. Covers model inference, agent invocation, tool execution, evaluation results and Model Context Protocol operations, plus provider-specific conventions for OpenAI, Anthropic, Azure AI Inference and AWS Bedrock. Essential reading before you build LLM observability you intend to keep.
Is OpenTelemetry GenAI Semantic Conventions free?
OpenTelemetry GenAI Semantic Conventions is free to access.
What level is OpenTelemetry GenAI Semantic Conventions for?
OpenTelemetry GenAI Semantic Conventions is aimed at a advanced audience. Recommended background: Working knowledge of OpenTelemetry traces, metrics and the core semantic conventions, Experience instrumenting a production service with an OTel SDK, Familiarity with LLM application shapes — tool calls, agent loops, retrieval.
How long does OpenTelemetry GenAI Semantic Conventions take?
Expect roughly ~2-3 hours to read the spec docs; ~1 day to instrument a service against them. Most learners work through it at their own pace.
What will I learn from OpenTelemetry GenAI Semantic Conventions?
You'll learn: Name spans and attributes so traces are portable across observability backends; Instrument chat, invoke_agent and execute_tool spans correctly for agent workloads; Record token usage with gen_ai.usage.input_tokens and gen_ai.usage.output_tokens consistently; Trace Model Context Protocol operations using the dedicated mcp.* attribute namespace; Handle the gen_ai.system to gen_ai.provider.name rename without breaking existing dashboards; Emit evaluation results as gen_ai.evaluation.result events correlated to the run; Judge which frameworks emit current conventions and which still emit older generations.
Topics
Sources
This page was written from 3 sources, 2 on domains other than github.com.