Skip to content
Running AI in production· Guide 7 of 14Advanced9 min readUpdated

Map agent traces to OpenTelemetry GenAI conventions ​

The OpenTelemetry GenAI semantic conventionsGenAI semantic conventions: OpenTelemetry's shared names for the spans, attributes and metrics of model calls, agents and tool calls, such as `chat`, `invoke_agent` and `gen_ai.usage.input_tokens`. are shared names for the spans, attributes and metrics of model calls, agents and tool calls. A model call is a CLIENT span named {gen_ai.operation.name} {gen_ai.request.model}, such as chat gpt-4o. A tool call is an execute_tool {gen_ai.tool.name} span, and an agent run is invoke_agent {gen_ai.agent.name}. Token counts go in gen_ai.usage.input_tokens and gen_ai.usage.output_tokens, and the provider in gen_ai.provider.name, which replaced gen_ai.system in release 1.37.0. Every one of these names is still at Development status, the earliest maturity level, so they can change between releases. To map your own traces, pin one version, emit its names and required attributes, keep everything else under your own prefix, and plan for one rename when the conventions move again.

Where the conventions live now ​

Up to the v1.41 releases, the GenAI and MCP conventions were part of the main open-telemetry/semantic-conventions repository. Release v1.42.0 (12 June 2026) moved them to their own repository, open-telemetry/semantic-conventions-genai. In the main repository, every gen_ai.* attribute, metric, event and span is now marked deprecated, so if your tooling is built on semantic conventions 1.42 or later, it shows the GenAI names as deprecated: they moved, they were not renamed. The GenAI pages on opentelemetry.io say: "This page has moved and is no longer maintained in this repository." When we checked on 16 November 2026, the new repository had no release yet. So the last released GenAI text is v1.41.0 (the v1.41.1 patch carries the same GenAI text), and the newer text exists only on that repository's main branch.

The documents are split by signal:

  • Model spans: inference (chat, text completion), embeddings, retrieval and tool execution.
  • Agent spans: create_agent, invoke_agent and invoke_workflow.
  • Metrics: client metrics such as token usage and operation duration, and server metrics such as time to first token.
  • Events: the opt-in content of a model call (gen_ai.client.inference.operation.details) and evaluation results (gen_ai.evaluation.result).
  • MCP: spans and metrics for Model Context Protocol requests.
  • Provider pages: extra attributes for some providers, such as OpenAI, Anthropic, Azure AI Inference and AWS Bedrock.

Each page is marked "Status: Development". OpenTelemetry's maturity levels describe Development as the stage where "Not all pieces of the component are in place yet", with none of the promises a Stable document makes about keeping names. The GenAI pages add a transition plan for instrumentation built on v1.36.0 or earlier. Such instrumentation "SHOULD NOT change the version of the GenAI conventions that they emit by default", and "SHOULD introduce an environment variable OTEL_SEMCONV_STABILITY_OPT_IN". One of its values, gen_ai_latest_experimental, means: "emit the latest experimental version of GenAI conventions (supported by the instrumentation) and do not emit the old one".

In practice: older instrumentation keeps its old names until you opt in with one setting. Newer instrumentation can change names in any release, so pin its version.

The span names ​

What happenedgen_ai.operation.nameSpan nameKind
A chat or completion call to a modelchat, text_completion, generate_content{operation} {gen_ai.request.model}CLIENT (INTERNAL for a model in the same process)
An embeddings callembeddingsembeddings {gen_ai.request.model}CLIENT
One tool call the model asked forexecute_toolexecute_tool {gen_ai.tool.name}INTERNAL
An agent run, in your own processinvoke_agentinvoke_agent {gen_ai.agent.name}INTERNAL
An agent run on a remote agent serviceinvoke_agentinvoke_agent {gen_ai.agent.name}CLIENT
A process that coordinates several agentsinvoke_workflowinvoke_workflow {gen_ai.workflow.name}INTERNAL
An MCP requestexecute_tool on tools/call (plus mcp.method.name){mcp.method.name} {target}, such as tools/call get_weatherCLIENT, or SERVER on the server side

On a model span, gen_ai.operation.name and gen_ai.provider.name are Required. gen_ai.request.model is Conditionally Required when it is available. gen_ai.usage.input_tokens, gen_ai.usage.output_tokens and gen_ai.response.finish_reasons are Recommended. error.type, which is already Stable, is Conditionally Required "if the operation ended in an error". On a tool span, gen_ai.tool.name is Required; gen_ai.tool.call.id and gen_ai.tool.type are Recommended. The MCP page says its tool call spans "are compatible with GenAI execute_tool spans". It prefers one span per tool call: if the MCP instrumentation can tell that GenAI instrumentation is already tracing the tool call, it "SHOULD NOT create a separate span" and should add its MCP attributes to the existing execute_tool span. Only when it cannot tell does it create its own tools/call CLIENT span, which then sits under execute_tool, as in the figure.

One agent run as GenAI spansA tree of spans. invoke_agent support-bot at the top. Below it, a chat span for the first model call, an execute_tool span for the tool the model asked for, with a tools/call MCP client span under it, and a second chat span for the model call that writes the answer.invoke_agent support-botINTERNAL · gen_ai.agent.namechat gpt-4oCLIENTexecute_tool lookup_orderINTERNALtools/call lookup_orderCLIENTchat gpt-4oCLIENT
Time runs downwards. The model asks for a tool, the agent runs it through an MCP server, and a second model call writes the answer. Each box is one span; the dashed one follows the MCP conventions.

The names that changed ​

Most confusion comes from guides and dashboards written against older releases. The main renames, all from the main repository's changelog:

Older nameCurrent name (v1.41.0)Changed in
gen_ai.systemgen_ai.provider.name1.37.0
az.ai.openai, az.ai.inference (values)azure.ai.openai, azure.ai.inference1.35.0
gen_ai.usage.prompt_tokensgen_ai.usage.input_tokens1.27.0
gen_ai.usage.completion_tokensgen_ai.usage.output_tokens1.27.0
Per-message events (gen_ai.user.message, gen_ai.choice, ...)gen_ai.input.messages, gen_ai.output.messages, gen_ai.system_instructions attributes, or the gen_ai.client.inference.operation.details event1.37.0
gen_ai.openai.request.seedgen_ai.request.seed1.30.0
Other gen_ai.openai.* attributesopenai.*, without the gen_ai prefix1.37.0

The gen_ai.system change is the one most readers trip over. The registry now lists it as deprecated, with the note "Deprecated, use gen_ai.provider.name instead." Under the transition plan above, instrumentation built on 1.36.0 or earlier keeps emitting gen_ai.system by default, and switches to gen_ai.provider.name only when you set OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental. If a dashboard groups by gen_ai.system and shows nothing, check which version your instrumentation emits before you suspect the export.

gen_ai.provider.name is a best guess by the instrumentation. The registry says it "may differ from the actual model provider". A call to a self-hosted server that speaks the OpenAI API is often reported as openai by OpenAI client instrumentation, and gen_ai.request.model, gen_ai.response.model and server.address tell the real target apart. Well-known values include openai, anthropic, azure.ai.openai, gcp.gemini, gcp.vertex_ai, aws.bedrock, mistral_ai and cohere.

Metrics: two generations ​

In v1.41.0 the two core client histograms are:

  • gen_ai.client.token.usage, unit {token}, with gen_ai.token.type set to input or output. The conventions say an instrumentation that cannot get the counts "MAY allow users to enable offline token counting", and otherwise "MUST NOT report usage metric"; and that when a provider reports both used and billable tokens it "MUST report billable tokens".
  • gen_ai.client.operation.duration, in seconds.

Both carry gen_ai.operation.name, gen_ai.provider.name and, when known, gen_ai.request.model, gen_ai.response.model and server.address. Release 1.41.0 also added streaming histograms for time to first chunk and time per output chunk.

The genai repository's main branch reorganises these. Inference durations move to gen_ai.client.inference.duration, and tokens become counters such as gen_ai.client.inference.usage.input_tokens and gen_ai.client.inference.usage.output_tokens, plus histograms per operation. Embeddings get their own gen_ai.client.embeddings.duration. Nothing from that branch has been released, so build on the v1.41.0 names and treat the new ones as an opt-in to test.

Keep ids off metrics: an execution, session or user id on a metric creates one series per run, session or user. The tracing vs logging guide covers what goes where.

Content is opt-in ​

Prompts and answers are not part of the default telemetry. Release 1.37.0 moved them to opt-in attributes (gen_ai.input.messages, gen_ai.output.messages, gen_ai.system_instructions) and said they "are not recorded by default when content capturing is disabled". Release 1.38.0 added gen_ai.tool.definitions and the opt-in tool arguments and results (gen_ai.tool.call.arguments, gen_ai.tool.call.result). Since 1.41.0, tool definitions may be recorded in a simplified form even with content capture off. If you turn content on, prompts with customer data leave your service for the tracing backend. Mask them first: keeping personal data out of prompts, logs and traces covers how.

How to map your own traces ​

Say your agent code already writes spans named llm_request, agent_step and call_tool, with attributes such as model, vendor and prompt_tokens. A mapping in five steps:

  1. Pin a version. Choose v1.41.0 (the last release) and set the instrumentation scope's schema URL to https://opentelemetry.io/schemas/1.41.0, so a backend knows which names to expect.
  2. Rename spans and set the kind. llm_request becomes chat {model} as a CLIENT span. Each tool call becomes execute_tool {tool}, INTERNAL. The loop around them becomes invoke_agent {agent}.
  3. Set the Required attributes. gen_ai.operation.name on every span; gen_ai.provider.name on model spans; gen_ai.tool.name on tool spans; error.type on failures.
  4. Rename the rest, and keep your own under a prefix. prompt_tokens becomes gen_ai.usage.input_tokens; vendor becomes gen_ai.provider.name. Fields the conventions do not define, such as a tenant id or a retry count, go under your own namespace (acme.tenant.id), never under gen_ai.*, where a later release might define the same name with another meaning.
  5. Put the switch in one place. Keep every name in one module, as constants. When the genai repository releases, the move is one diff, and an opt-in setting lets you emit the new names in staging first.

For dashboards built on the old names, rename in the collector or in the backend's query for one release, then drop the alias.

Two cautions. Do not run a GenAI auto-instrumentation library over a client that you instrument yourself: every model call would be recorded twice. And use OpenTelemetry's span links, not parent and child, for work that resumes later, such as a run continued after a person approves a step. Tracing vs logging for LLM apps covers what belongs on a span and what belongs in a log line.

In L2M ​

L2M's OpenTelemetry export is optional and off by default. With an OTLP endpoint for traces set, it emits these conventions itself, pinned at v1.41.0, with spans under the scope l2m and the schema URL https://opentelemetry.io/schemas/1.41.0. All the names live in one module of its otel package. What it emits (OpenTelemetry):

  • Model calls: chat {model} and embeddings {model} CLIENT spans, from one place in front of the provider adapters. The provider goes in gen_ai.provider.name, never gen_ai.system: openai (also for OpenAI-compatible servers, whose L2M id stays in l2m.provider.id), azure.ai.openai, anthropic, gcp.gemini and ollama; other providers use their L2M id (model spans).
  • Agents and tools: invoke_workflow per run, invoke_agent per agent loop and execute_tool per tool call, with gen_ai.tool.type set to extension for an MCP server's tool and function for one that runs inside L2M. The workflow's name goes in l2m.workflow.name; L2M does not set gen_ai.workflow.name. MCP requests get a separate tools/call {tool} CLIENT span as a child of the execute_tool span (the conventions' fallback layout, not the single merged span they prefer), and the MCP gateway gets SERVER spans.
  • Metrics: with OTEL_METRICS_ENABLED=true and a metrics endpoint (tracing need not be on), gen_ai.client.operation.duration and gen_ai.client.token.usage; an endpoint alone exports no metrics. OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental switches the metric names, not the span names, to the main-branch names, such as gen_ai.client.inference.duration. Spend goes in L2M's own l2m.gen_ai.cost counter (GenAI and cost metrics).
  • Content: none by default. OTEL_INSTRUMENTATION_GENAI_CAPTURE_CONTENT turns on the opt-in content attributes, masked and cut to size before export (content capture).

L2M's own steps that the conventions do not cover, such as workflow nodes and queue jobs, use l2m.* names. The OpenTelemetry tracing post explains why the spans are cut this way.

Try it. Follow the quick start with a local collector: start the collector, run the zero-key MCP Agent Quickstart template, and read the span names in ops/otel/otel-data/traces.jsonl and, with OTEL_METRICS_ENABLED=true, the metric names in ops/otel/otel-data/metrics.jsonl. Its echo model makes no tool calls, so you will see invoke_agent, chat and the MCP tools/list span, but no execute_tool.

Further reading ​

Last updated:

This website (not the L2M product) uses Google Analytics, only after you accept cookies. Cookie settings