How do I instrument an AI agent with OpenTelemetry?

Install the OpenTelemetry SDK with an OTLP exporter, add a GenAI instrumentation library (OpenLLMetry or OpenInference) to capture model calls automatically, then add your own spans for the agent run (operation invoke_agent), each tool call (execute_tool) and retrieval (retrieval), using the gen_ai.* attributes from the OpenTelemetry GenAI semantic conventions. Send traces to any OTLP backend, such as Langfuse, Jaeger, Grafana Tempo or your APM vendor. Keep prompt and response content off by default; it is opt-in in the conventions.

Are the OpenTelemetry GenAI semantic conventions stable?

No. As of October 30, 2026 the GenAI conventions are marked Development and have moved to their own repository, open-telemetry/semantic-conventions-genai. Attribute names can still change, so pin instrumentation versions and check the changelog when you upgrade.

What should I measure for an AI agent in production?

Per run: latency, token usage (gen_ai.usage.input_tokens, gen_ai.usage.output_tokens and cache reads), cost, number of model calls and tool calls, loop depth, tool error rate and finish reason. Per tool: success rate and duration. Then attach evaluation scores, such as task success or groundedness, to the same trace so failures can be traced back to the step that caused them.

Should I log prompts and responses in traces?

Only deliberately. The conventions put gen_ai.input.messages, gen_ai.output.messages, gen_ai.system_instructions and gen_ai.tool.definitions behind opt-in because they can contain personal or secret data. Enable content capture in staging, redact before export in production, or store content in a separate system with its own retention and link it by reference.

Quick Answer

How to Instrument AI Agents with OpenTelemetry (2026 Guide)

Published: October 30, 2026

The short answer

Trace the agent as a tree: one span per agent run, child spans per model call, tool call and retrieval, all named and tagged with the OpenTelemetry GenAI semantic conventions. Then export over OTLP to whatever backend you already use. The steps below work with any agent framework in Python or TypeScript. As of October 30, 2026 the GenAI conventions are still marked Development and live in their own repository, open-telemetry/semantic-conventions-genai, so pin your versions.

The span model

Operation (`gen_ai.operation.name`)	Span	What it covers
`invoke_agent`	One per agent run (client or internal)	The whole task, from request to final answer
`invoke_workflow` / `plan`	Optional	Multi-agent workflows and planning steps
`chat` (inference)	One per model call	Model, tokens, finish reason, latency
`execute_tool`	One per tool call	Tool name, call ID, arguments, result
`retrieval`	One per vector or search lookup	Data source, top-k, (opt-in) query and documents
`search_memory`, `create_memory` …	Memory reads and writes	Memory store and record IDs
`create_agent`	Remote agent creation	Hosted agent services

The attributes that matter most: gen_ai.provider.name, gen_ai.request.model, gen_ai.agent.name, gen_ai.conversation.id, gen_ai.tool.name, gen_ai.tool.call.id, gen_ai.usage.input_tokens, gen_ai.usage.output_tokens, gen_ai.usage.cache_read.input_tokens, gen_ai.response.finish_reasons and error.type.

Step 1: Set up the SDK and exporter

Install the OpenTelemetry SDK for your language with the OTLP exporter, set OTEL_SERVICE_NAME, and point OTEL_EXPORTER_OTLP_ENDPOINT at your collector or backend. Run an OpenTelemetry Collector between your app and vendors if you want to redact, sample or fan out to several backends without changing code.

Step 2: Auto-instrument model calls

Add one GenAI instrumentation library instead of writing model spans by hand:

OpenLLMetry (Traceloop, Apache 2.0, v0.62.4 on September 29, 2026) instruments the major model SDKs, vector databases and frameworks.
OpenInference (Arize, Apache 2.0) provides instrumentors per framework and SDK, with releases on October 29, 2026.

Check which convention version each one emits. Some still default to older attribute names and switch with an opt-in flag.

Step 3: Add agent and tool spans yourself

Frameworks differ in what they emit, so wrap the parts only you know about:

from opentelemetry import trace
tracer = trace.get_tracer("support-agent")

with tracer.start_as_current_span("invoke_agent support-agent") as run:
    run.set_attribute("gen_ai.operation.name", "invoke_agent")
    run.set_attribute("gen_ai.agent.name", "support-agent")
    run.set_attribute("gen_ai.conversation.id", conversation_id)
    for step in agent.steps():
        if step.is_tool_call:
            with tracer.start_as_current_span(f"execute_tool {step.tool}") as t:
                t.set_attribute("gen_ai.operation.name", "execute_tool")
                t.set_attribute("gen_ai.tool.name", step.tool)
                t.set_attribute("gen_ai.tool.call.id", step.call_id)
                step.run()

Add your own attributes for what the conventions do not cover yet, such as app.agent.loop_depth, app.agent.cost_usd and the user’s tenant, under your own namespace.

Step 4: Decide on content capture

gen_ai.input.messages, gen_ai.output.messages, gen_ai.system_instructions, gen_ai.tool.definitions, retrieved documents and the retrieval query text are opt-in in the conventions because they may hold sensitive data. Turn them on in development and staging. In production, either redact in the Collector, sample content on a small share of traces, or upload content to separate storage and keep only a reference on the span (the conventions define *_ref attributes for that).

Step 5: Metrics and alerts

Use the convention metrics where your library emits them, for example gen_ai.client.operation.duration, gen_ai.server.time_to_first_token and gen_ai.server.time_per_output_token, and derive the agent-specific ones from spans:

tokens and cost per completed task, not per call;
tool error rate per tool;
runs that hit the step limit (loop depth);
share of runs that end in a refusal or a timeout.

Alert on changes in those numbers after a model or prompt change. They catch problems that uptime checks miss.

Step 6: Pick a backend

Any OTLP backend works: Jaeger or Grafana Tempo for raw traces, your APM vendor, or an LLM-specific tool. Langfuse, for example, accepts OpenTelemetry traces at its /api/public/otel endpoint, so you can keep vendor-neutral instrumentation and still get LLM views and evals. Compare tools in best LLM observability tools, and add online evaluation on top with how to monitor and evaluate AI agents in production.

Last verified: October 30, 2026.