OpenTelemetry GenAI Semantic Conventions 2026: End-to-End Implementation Guide for LLM & Agent Observability

Understanding GenAI Semantic Conventions

The OpenTelemetry Generative AI Special Interest Group (GenAI SIG) was formed in April 2024 to standardize how LLM and AI agent operations are observed. These semantic conventions provide a vendor-neutral schema for describing AI operations—so your telemetry data stays consistent whether you use OpenAI, Anthropic, Google Gemini, or any other provider.

As of early 2026, the GenAI conventions cover four primary areas: LLM client spans for direct API calls, agent spans for multi-step workflows, events for capturing prompt/completion content, and metrics for aggregated measurements. Version 1.37+ became the stable baseline, with the transition to version 1.41.0 introducing reasoning tokens and enhanced agent attributes.

Core gen_ai.* Attributes

Token Metrics and Cost Monitoring

Token monitoring is the foundation of LLM cost observability. Since LLMs price by token—differently for input and output—tracking these separately is essential. OpenTelemetry captures token usage through gen_ai.usage.input_tokens and gen_ai.usage.output_tokens, enabling trace-level cost transparency.

To calculate cost, multiply token counts by your model pricing rates. For example, OpenAI GPT-4o pricing (as of May 2026) is approximately $2.50/1M input tokens and $10/1M output tokens. Emit a custom gen_ai.usage.cost_usd metric using a pricing table you control.

Latency Metrics: TTFT and TPS

For streaming responses, Time to First Token (TTFT) and Tokens Per Second (TPS) matter more than total latency. TTFT measures perceived responsiveness—users see the first output faster with lower TTFT. TPS measures generation speed once streaming begins.

The standard GenAI metric instruments include gen_ai.client.operation.duration for end-to-end latency and gen_ai.client.time_per_output_token for TPS. Recommended SLO dimensions: P50 latency under 500ms, P99 under 5s for chat; P99 total generation under 30s.

AI Agent Distributed Tracing

Agentic AI introduces complexity that traditional APM cannot handle. A single user request may spawn multiple model calls, tool executions, and retrieval steps. OpenTelemetry handles this via W3C TraceContext headers (traceparent, tracestate), which propagate across HTTP calls automatically.

For queue-based communication, you must serialize the context into the message. The agent spans use gen_ai.agent.* attributes including gen_ai.agent.name, gen_ai.agent.type, and gen_ai.tool.name for tool invocations. This enables full trace visualization across the agent workflow.

OTel Collector Pipeline for GenAI

The OpenTelemetry Collector provides a vendor-neutral telemetry pipeline that receives, processes, and exports data. For GenAI workloads, the collector normalizes attributes from different instrumentation libraries (OpenInference, OpenLLMetry) to the standard gen_ai.* conventions.

Collector Configuration

Configure the OTel Collector with the genainormalizer processor to transform attributes from popular frameworks to GenAI semantic conventions:

processors:
  genainormalizer:
    semconv_version: "1.41.0"
    profiles: [openinference, openllmetry]
    remove_originals: true

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [genainormalizer, batch]
      exporters: [otlp/backend]

The genainormalizer processor maps attributes from OpenInference and OpenLLMetry libraries (covering 60+ frameworks including LangChain, CrewAI, PydanticAI, Strands) to the OTel GenAI semantic conventions. It supports custom mappings and optional overwrite behavior.

Integration: Datadog and Grafana

Datadog LLM Observability natively supports OpenTelemetry GenAI Semantic Conventions (v1.37+). This allows you to instrument once with OTel, export via your existing collector pipeline, and analyze GenAI spans directly in Datadog—no code changes required.

Similarly, Grafana Cloud Traces (powered by Tempo) provides full distributed tracing visualization. You can correlate agent traces with metrics and logs for faster root cause analysis. The OpenTelemetry Python instrumentation for OpenAI Agents SDK automatically emits GenAI-compliant spans.

Implementation Checklist

Last Updated: May 06, 2026 | Source: OpenTelemetry Official Documentation (opentelemetry.io)