OpenTelemetry GenAI Semantic Conventions
by OpenTelemetry (CNCF)
The vendor-neutral schema for tracing LLM calls, agents, and MCP tools.
Overview
This is the dedicated home of OpenTelemetry's GenAI semantic conventions, split out from the core semantic-conventions repository (the old opentelemetry.io/docs/specs/semconv/gen-ai/ and registry pages are now deprecation notices pointing here). It specifies, per the repo's own description, "Semantic Conventions for Generative AI (GenAI), including spans, metrics, and events for GenAI clients, MCP (Model Context Protocol), and provider-specific conventions." Concretely that covers GenAI client spans, agent spans, GenAI metrics, events, exceptions, MCP conventions, and provider-specific conventions for OpenAI, Anthropic, AWS Bedrock, and Azure AI Inference, plus non-normative worked examples of instrumented LLM calls. Human-readable conventions live in /docs, machine-readable YAML definitions in /model (managed with Weaver as an extension of the core conventions), and reference implementations under /reference, which also carries a Python compliance matrix and per-signal support reports. The conventions are Apache-2.0 licensed and adopted broadly across observability vendors and cloud providers, which is what makes them the interoperability layer: instrument once and your token counts, latencies, tool calls, and agent steps are readable by any conforming backend. Most GenAI conventions remain experimental, so expect attribute churn and use the documented stability opt-in when running in production.
At a Glance
- Topic
- Frameworks
- Level
- Intermediate
- Format
- Documentation
- Cost
- Free
- Duration
- ~1-2 hours to read the core span/metric conventions
- Provider
- OpenTelemetry (CNCF)
- Hands-on
- Yes — code/exercises
- Certificate
- None
What You’ll Learn
- ✓Which attributes belong on a GenAI span: model, provider, token usage, temperature, finish reason, and cost-relevant fields
- ✓How to trace multi-step agents — agent spans, tool invocations, and MCP client/server calls
- ✓The standard GenAI metrics for token consumption, request duration, and error rates
- ✓How to instrument for portability across Langfuse, Phoenix, Datadog, and cloud-native backends
- ✓Provider-specific conventions for OpenAI, Anthropic, AWS Bedrock, and Azure AI Inference
- ✓How to manage attribute churn while the conventions are still experimental
Highlights
- •Vendor-neutral and CNCF-backed — the closest thing to a standard for LLM observability
- •First-class MCP conventions, so tool-calling agents are traceable end to end
- •Machine-readable YAML models plus reference implementations, not just prose
- •Supersedes the older semconv gen-ai pages, which now redirect here
Who It’s For
Best For
- ✓AI engineers adding tracing and evals to LLM or agent applications
- ✓Platform teams standardizing observability across multiple model providers
- ✓Anyone building an LLM observability tool or instrumentation library
- ✓SREs who need token cost and latency attribution in production
Prerequisites
- •Familiarity with OpenTelemetry traces, spans, and metrics
- •Experience calling LLM APIs or building agents
- •Basic YAML and instrumentation-library concepts
FAQ
What is OpenTelemetry GenAI Semantic Conventions?
The official OpenTelemetry repository defining standard telemetry conventions for generative AI systems — spans, metrics, and events for LLM clients, MCP, and specific providers. For AI engineers who need portable observability instead of one vendor's proprietary trace format.
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 intermediate audience. Recommended background: Familiarity with OpenTelemetry traces, spans, and metrics, Experience calling LLM APIs or building agents, Basic YAML and instrumentation-library concepts.
How long does OpenTelemetry GenAI Semantic Conventions take?
Expect roughly ~1-2 hours to read the core span/metric conventions. Most learners work through it at their own pace.
What will I learn from OpenTelemetry GenAI Semantic Conventions?
You'll learn: Which attributes belong on a GenAI span: model, provider, token usage, temperature, finish reason, and cost-relevant fields; How to trace multi-step agents — agent spans, tool invocations, and MCP client/server calls; The standard GenAI metrics for token consumption, request duration, and error rates; How to instrument for portability across Langfuse, Phoenix, Datadog, and cloud-native backends; Provider-specific conventions for OpenAI, Anthropic, AWS Bedrock, and Azure AI Inference; How to manage attribute churn while the conventions are still experimental.