OpenTelemetry GenAI conventions: one trace format for models and agents

OpenTelemetry's GenAI semantic conventions are the agreed names for what happens inside an LLM application: which model was called, how many tokens it used, which tool an agent ran, how long each step took. Instrument once with these names and Langfuse, Datadog, Phoenix or your own Grafana can all read the same traces. This page covers what the conventions define, how settled they are on 2026-10-13, which libraries emit them, and a collector pipeline that keeps prompts and personal data out of your trace store.

A semantic convention is a contract for telemetry: span names, attribute keys, value formats, metric names and units. The GenAI conventions cover:

• Model calls. Inference (chat, generate_content, text_completion), embeddings and retrieval, with attributes such as gen_ai.provider.name, gen_ai.request.model, gen_ai.response.model, gen_ai.usage.input_tokens and gen_ai.usage.output_tokens.
• Agents and tools. create_agent, invoke_agent, invoke_workflow and execute_tool spans, with gen_ai.agent.name, gen_ai.tool.name, gen_ai.tool.call.id and, when you opt in, the tool call arguments and results.
• Content. Prompts, system instructions and outputs as gen_ai.input.messages, gen_ai.system_instructions and gen_ai.output.messages, off by default.
• Metrics. Client operation duration and token usage histograms, plus server-side metrics such as time to first token for model servers.
• MCP. Client and server spans for Model Context Protocol calls, named {mcp.method.name} {target}, with trace context carried inside the request's params._meta.
• Provider extras for OpenAI, Anthropic, AWS Bedrock and Azure AI Inference.

It sits at the bottom of the observability stack. It is not a product and stores nothing. The instrumentation libraries emit it, the OpenTelemetry Collector moves and filters it, and backends such as Langfuse, Arize Phoenix, Laminar or Datadog store and display it. Pick it as your wire format and the backend becomes a choice you can revisit.

Pick the GenAI conventions when:

• You run more than one backend or expect to switch. Traces in a standard shape go to a second destination with one more exporter line in the collector, not a re-instrumentation project.
• You already run OpenTelemetry. Your HTTP, database and queue spans gain LLM and agent spans in the same trace, so a slow answer can be traced to a slow vector search, not just "the model".
• You need to control where prompts go. Content capture is off by default, and the collector can drop or mask it before anything leaves your network.
• Your agents call tools and MCP servers. Standard agent, tool and MCP spans make a multi-step run readable in any trace viewer.

Be careful when:

• You need a frozen schema. Every GenAI attribute is still at Development status, and names have changed in the past year. Pin your instrumentation versions and expect to update dashboards.
• A vendor SDK already does everything you need. Langfuse's or Braintrust's own SDKs capture richer, product-specific data with less setup. Many teams run both: the vendor SDK for evaluation features, OpenTelemetry for the shared trace.
• Your language lags. Python has the broadest official coverage. The JavaScript OpenAI instrumentation still implements an older version of the conventions, so the same call produces different attribute names in each language today.

The nearest alternatives are OpenLLMetry from Traceloop and OpenInference from Arize. Both are open-source instrumentation sets built on OpenTelemetry. OpenLLMetry now emits most gen_ai.* names; OpenInference uses its own llm.* and input.value attributes and can emit gen_ai.* alongside them when you turn that on.

An instrumentation library wraps your model client. Each call becomes a span named {gen_ai.operation.name} {gen_ai.request.model}, such as chat gpt-4o-mini, with span kind CLIENT. The official Python OpenAI instrumentation (version 1.2b0) produces this for one chat completion:

Alongside the span it records two histograms: gen_ai.client.operation.duration in seconds and gen_ai.client.token.usage in tokens, split by gen_ai.token.type (input or output).

Agent frameworks add structure above the model calls. An agent run is an invoke_agent {gen_ai.agent.name} span; each tool call inside it is an execute_tool {gen_ai.tool.name} span of kind INTERNAL; each model call is a chat span. Your own spans (an HTTP handler, a retrieval step) wrap all of it, so one trace shows the full path from request to answer.

Content is opt-in. Since v1.37, chat history is no longer one event per message. It is recorded either as span attributes or as a single gen_ai.client.inference.operation.details event (a log record). The specification recommends three levels: record nothing (the default), record content on spans where privacy rules allow it, or upload content to separate storage and keep only a reference on the span.

Where the conventions stand. All GenAI conventions are at Development status, so names can still change. In semantic conventions v1.42.0 (June 2026) the GenAI, OpenAI and MCP definitions moved to their own repository, semantic-conventions-genai, which had not cut a tagged release by 2026-10-13. The last release that carries them is v1.41.0 (April 2026). The working draft is still moving: in September and October 2026 it renamed client metrics in the draft (for example gen_ai.client.inference.duration and per-type token counters), while today's released instrumentations still emit gen_ai.client.operation.duration and gen_ai.client.token.usage.