OpenTelemetry’s GenAI semantic conventions give AI applications a shared vocabulary for traces: every model call, embedding lookup, retrieval and tool execution becomes a span with standard names and attributes, so any compatible backend can show what an agent actually did. The conventions are still marked as being in Development status, and they now live in a dedicated repository, open-telemetry/semantic-conventions-genai, so names can still change. This guide explains how to read a trace built on them and how to avoid leaking user data into it.

Why standard traces beat ad hoc logs

A single user request to an agent can trigger several model calls, a retrieval step and a handful of tool calls. Plain logs show each line in isolation. A trace links them into a tree with timings, so you can see that a slow answer came from a slow tool rather than the model. Using a standard schema means the same dashboard works whichever SDK or provider you use. Our broader guide on what to log and monitor covers metrics and alerts; here we focus on the trace itself.

The span types you will see

The spans document describes several operation types. Each span carries gen_ai.operation.name, a required attribute that says what kind of work it represents.

  • Inference. A call to a model. Well-known operation names include chat, generate_content and text_completion.
  • Embeddings. A call that turns text into vectors.
  • Retrievals. A search against a vector store, database or similar source.
  • Fetch response. Retrieving a previously created response by its identifier. Its span name is just the operation name, because the response ID is high cardinality and would flood your backend if put in the name.
  • Memory. Operations such as creating a memory store or searching memory, with the span kind normally CLIENT.
  • Agent operations. The conventions define create_agent and invoke_agent operation names.
  • Execute tool. One span per tool the agent runs.

The attribute gen_ai.provider.name identifies the provider and is required or conditionally required on several of them. It acts as a discriminator, so provider-specific attributes can be interpreted correctly; the specification lists well-known values and allows a custom value otherwise.

Anatomy of a tool-call span

Tool spans are the most useful for debugging agents. According to the specification, the operation name should be execute_tool, the span name should be execute_tool {gen_ai.tool.name}, and the span kind should be INTERNAL, because the tool usually runs inside your own process.

Required and conditional attributes include:

  • gen_ai.tool.name, the tool used, such as a flights lookup.
  • gen_ai.agent.name, when applicable.
  • gen_ai.conversation.id, when available, which groups a session.
  • gen_ai.tool.call.id, which should match the identifier supplied by the model or provider.

The arguments and result of the tool call are separate attributes, gen_ai.tool.call.arguments and gen_ai.tool.call.result, and both are opt-in. That choice is deliberate, as the next section shows.

Content capture: keep prompts out by default

Prompts and completions often contain personal data. The conventions treat content as sensitive: the document notes that message attributes are likely to contain user or personal data, and it gates capture behind an explicit setting. Instrumentations that support capturing content must offer a configuration option, and if it is an environment variable it must be named OTEL_INSTRUMENTATION_GENAI_CAPTURE_CONTENT. The accepted values are:

Value Behavior
NO_CONTENT Do not capture content on spans or events (the default).
SPAN_ONLY Capture content on spans only.
EVENT_ONLY Capture content on events only.
SPAN_AND_EVENT Capture content on both.
Lines of code on a screen
Tracing is added to application code; the photo is illustrative and shows no specific tool. Photo: Artem Sapegin sapegin / Wikimedia Commons, CC0

The gated attributes include input and output messages, system instructions, tool call arguments and results, retrieval query text, prompt template variables and memory records. Tool definitions are not gated, because they describe a schema rather than user or model content. The specification also lets instrumentation truncate individual message contents while keeping the JSON structure.

A worked example: debugging a slow agent answer

Imagine a support agent that answers in nine seconds. You open the trace and see an invoke_agent span containing four children: two chat spans, a retrieval span and one execute_tool span. Sorting by duration shows the tool span took most of the time. Because content capture is off, you cannot see the arguments, but the tool name, conversation ID and tool call ID are enough to find the matching request in the tool service’s own logs. You fix the tool, not the prompt.

Had you turned on content capture in production, you would also have copied customer text into your telemetry store, which brings retention, access and deletion duties. A common compromise, which is our suggestion rather than part of the specification, is to enable content capture in staging and for a small, consented sample in production.

Pairing traces with evaluation

Traces tell you what happened; evaluations tell you whether it was good. Sample traces into a review queue, score them with the methods in our guides on building an evaluation set and LLM-as-a-judge, and attach the score to the trace so regressions are visible next to latency.

What to watch next

  • Whether the GenAI conventions move from Development to a stable status.
  • More coverage of agent and Model Context Protocol operations in the repository.
  • Observability vendors announcing support for the new repository layout.
  • Updates to the content capture options as privacy guidance matures.

Key takeaways

  • Each model call, retrieval or tool run is a span with a standard gen_ai.operation.name.
  • Tool spans are named execute_tool {tool name} and use the INTERNAL span kind.
  • Content capture is off by default and controlled by OTEL_INSTRUMENTATION_GENAI_CAPTURE_CONTENT.
  • The conventions are in Development status, so pin versions and expect changes.
  • Link scores from evaluations to traces to find regressions.

Frequently asked questions

Are the OpenTelemetry GenAI conventions stable?

No. The spans document marks its status as Development, and the conventions have moved to their own repository, so attribute names may change.

Does tracing store my users’ prompts?

Not by default. Content capture defaults to NO_CONTENT, and you must opt in with a configuration option to record prompts, completions or tool arguments.

Do I need OpenTelemetry to observe an LLM app?

No, but a standard schema lets you switch backends or providers without rewriting dashboards.