How to Trace Claude Managed Agents with OpenTelemetry: Console Destinations, Spans, and Cost Tracking

Introduction

Claude Managed Agents run on Anthropic’s servers, which makes them powerful and hard to observe: the agent can work a task for hours, call tools, and consult MCP servers, while your own logs see only the request you sent and the result that came back. When a run is slow, expensive, or wrong, you need the steps in between. This tutorial sets up OpenTelemetry tracing for Managed Agents, shows you how to read the resulting spans, and turns those spans into token and latency tracking, all without changing your agent code.

Quick answer

Add an OpenTelemetry destination in the Claude Console with your backend’s OTLP endpoint, keep Metadata only mode, press Test, then filter on service.name claude-platform to see every turn, model call, and tool use.

Evidence

Anthropic launched OpenTelemetry trace export for the Claude Platform in public beta on October 14, 2026, covering Claude Managed Agents, the Messages API, and the Claude SDKs. That date marks the point where tracing stopped requiring custom middleware: the platform itself now emits standard spans to any OTLP-compatible backend.

Anthropic’s announcement puts it in one sentence: “Add a destination in the Claude Console, and every agent turn, model call, and tool use arrives in your observability tool as a standard OpenTelemetry trace, with latency, tokens, and IDs.” The key word is standard. Claude traces follow the OpenTelemetry GenAI semantic conventions, so the same dashboard that shows an OpenAI or Gemini call can show a Claude call without per-vendor parsing.

The scale limits are documented, not guessed. Each span holds up to 0.75 MB of content by default in Full content mode, which Anthropic states fits a 200,000-token English context window and stays below the 1 MB request limit of many backends and proxies, while a 1,000,000-token window needs about 4 MB. Twelve partner platforms have dedicated guides: Arize AI, Braintrust, Databricks, Datadog, Grafana Cloud, Honeycomb, Langfuse, LangSmith, New Relic, PostHog, Sentry, and Splunk. Any other OTLP-compatible platform works too.

The OpenTelemetry tracing overview for the Claude API defines the two setup paths and span model used here. The destination setup guide documents the Console form fields, endpoint requirements, and delivery check used below. If your agent runs through the Agent SDK or Claude Code, use the Agent SDK observability guide instead, because that path configures telemetry through CLI environment variables, not a Console destination.

Prerequisites

• A Claude Console organization with a Managed Agents workload, or a Messages API workload you want to trace the same way.
• The admin role in that organization, required to add or change destinations. The developer role can view destinations but cannot create them.
• An observability backend that accepts OTLP over HTTP with protobuf: a hosted platform such as Grafana Cloud, Datadog, or Honeycomb, or a self-hosted Collector behind an HTTPS endpoint.
• The backend’s OTLP details: a base HTTPS URL with a hostname on port 443, plus its credentials, usually an API key header.
• A way to run one Managed Agents session after setup, to confirm spans arrive.

Step-by-step guide

Step 1: Confirm which tracing path your agent needs

There are two tracing paths, and picking the wrong one is the most common setup mistake. API tracing is configured in the Console and covers any client, including Managed Agents sessions and Messages API requests. SDK tracing is configured in code and covers only SDK clients, adding client-side spans such as the tool runner and self-hosted sandbox tools. For a hosted Managed Agents session, API tracing is the path: no code change, one Console destination, and every turn appears in your backend.

Set up both paths only when you want one unified trace covering your code, the SDK’s client-side work, and Anthropic’s server-side work. The SDK writes a W3C traceparent header automatically when the call starts inside one of your own spans, and the API spans nest inside your trace. If the sampled flag on that header is off, the API emits no spans, which is a sampling decision, not an outage.

Step 2: Prepare your OTLP endpoint

Your destination needs an OTLP over HTTP endpoint that accepts protobuf encoding at an HTTPS URL on port 443, with a hostname rather than an IP address. Hosted platforms publish this URL in their ingestion settings, often with a path prefix for your region or dataset. Copy the base URL exactly as published.

A self-hosted OpenTelemetry Collector listens on port 4318 by default, which does not satisfy the Console requirement. Configure its receiver for HTTPS on port 443, or put a reverse proxy in front of it that terminates HTTPS on port 443 and forwards to port 4318. The server needs a public address: a collector on localhost or a private address will never show Healthy.

Most backends accept an API key as a request header, and the Console hides header values after saving, so keep the key somewhere safe outside the Console.

Step 3: Add the destination in the Claude Console

In the Console, open your organization’s OpenTelemetry settings page and click Add destination. The form asks for the following:

• Provider: your observability platform, or Custom if it is not listed. A listed platform asks for its own details, such as an API key, instead of the raw endpoint and header fields.
• Name: optional, for example “Production observability”.
• OTLP endpoint URL: the base HTTPS URL from Step 2, with a hostname, not an IP address. It can carry a path prefix, for example https://gateway.example.com/otlp. Do not append /v1/traces, because the API adds that path itself.
• Request headers: the credentials your backend requires, such as an API key header. These values are hidden after saving.
• Content mode: Metadata only or Full content. Leave it on Metadata only for the first destination. That mode records identifiers, timing, status, token counts, and agent, tool, and MCP server names, enough for cost and latency tracking without sending prompt text to a third party.
• Workspaces: which Claude workspaces send traces to this destination: All, Selected, or All except. Start with Selected and pick one workspace for the first test, then widen the scope once delivery is confirmed.

Save the destination. The API sends spans to every enabled destination covering the workspace where the request or session runs, so a session in an uncovered workspace will correctly produce nothing.

Step 4: Test the destination and confirm delivery

Press the Test button on the destination. The API sends an anthropic.test span to your endpoint, confirming connectivity without a real agent session. Then check the Delivery column: it should show Healthy within about a minute. If it shows Failing, hover over it to read the last error before changing anything.

Next, run one real Managed Agents session in a covered workspace and look in your backend. Filter on service.name equal to claude-platform. A session produces a span for each Sessions API request and a turn span for each agent turn, and each turn contains spans for each model request, each tool the API runs, and each outcome evaluation. If you see the session span and its turn children, the pipeline works end to end. If you see only the test span, no session has run in a covered workspace yet.

Step 5: Read a Managed Agents trace

Open one session trace and read it top down. The session span frames the whole run. Under it, each turn span marks one agent turn, so a long run shows up as a sequence of turns rather than one undifferentiated block. Inside a turn, model request spans carry the model name, latency, token counts, and status, while tool spans carry the tool name and its timing. When a turn calls an MCP server, that call appears as its own span type, distinct from the model round trip. That distinction explains why an MCP-heavy run looks slow in the session view but fast in the model view: the time sits in tool spans, not model spans.

The MCP server tutorial explains the protocol behind those MCP spans, and the OpenAI Agents API tutorial shows a browser-driving agent with the same trace, turn, and tool pattern.

Step 6: Build token and latency tracking from spans

Token accounting has one rule: count each token once by summing spans from only one source per request, using the API spans when both SDK and API tracing are active. Summing both sources double counts every token, which inflates cost dashboards and makes a healthy run look twice as expensive as it is.

A practical starting dashboard has three panels. The first sums input and output tokens per session, grouped by model name, which gives cost per run once you multiply by the model’s published price. The second shows turn latency, the duration of each turn span, so slow turns stand out from slow models. The third counts errors by span status, grouped by tool name, so a failing tool surfaces before users report it. All three work on Metadata only spans.

Step 7: Decide about Full content and data handling

Full content mode adds model prompts and responses, tool inputs and outputs, and everything Metadata only already records. That helps reproduce failures, and risks privacy, because prompt text can contain customer data, pasted secrets, or internal documents. Enable it only for workspaces whose data your pipeline is approved to store, and prefer a separate narrow destination over flipping a broad one.

Two restrictions override your choice. If your organization has a HIPAA, FERPA, or K-12 data-handling restriction with Anthropic, destinations export only metadata regardless of content mode, while SDK spans are unaffected. And Managed Agents is not eligible for zero data retention, so its retention terms stay the same when OpenTelemetry is in use, even though Messages API requests under zero data retention can still use Full content because the API holds exported content only in memory until delivery. Check both points with your compliance owner before using Full content for a regulated workload.

Step 8: If your agent runs through the Agent SDK instead

The Console destination does not cover agents that run through the Agent SDK or Claude Code, because those agents run the Claude Code CLI as a child process on your own machine. For that path, telemetry is configured with environment variables that the SDK passes through to the CLI process, and the CLI exports directly to your collector:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=https://collector.example.com

Traces are in beta on this path and need CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 plus OTEL_TRACES_EXPORTER=otlp. Each turn becomes a claude_code.interaction span, with claude_code.llm_request and claude_code.tool children, and spans carry a session.id attribute. The CLI fails silently on export errors by default, so set CLAUDE_CODE_OTEL_DIAG_STDERR=1 while debugging.

Troubleshooting

Delivery shows Failing and no spans arrive

Hover over the Failing indicator to read the last error, because it names the failing part. The two most common causes are an endpoint URL that includes /v1/traces, which the API already appends, and missing or wrong credentials. Fix the URL to the base endpoint, re-enter the headers, press Test again, and wait about a minute for Delivery to update. For a self-hosted collector, confirm it listens on HTTPS port 443 at a public hostname.

Spans arrive for the test but not for real sessions

This almost always means a workspace scope mismatch: the destination is healthy, but the session ran in a workspace it does not cover. Check the destination’s Workspaces setting. The second possibility is sampling: when a request carries a W3C traceparent header with the sampled flag off, the API emits no spans for that request. Confirm the sampled flag is on for the requests you expect to trace. On Claude Platform on AWS, traceparent support is not yet available, so API spans there start their own traces.

Model spans show an empty preview for Managed Agents sessions

An empty preview on the internal model prompt and response spans inside a Managed Agents session does not mean export failed. Third-party integration guides note that the platform does not export the internal model prompt and response on those spans, so the preview stays empty even when the trace is complete. If the turn and tool spans around it carry token counts, timing, and tool names, the export works.

FAQ

Do I need to change my agent code to trace Claude Managed Agents?

No. Managed Agents sessions are traced from Anthropic’s side once an admin adds a destination in the Console. Code changes are only needed for SDK tracing, where you register a tracer provider in your own application.

Do traces include my prompts and responses by default?

No. Destinations start in Metadata only mode, which records identifiers, timing, status, token counts, and agent, tool, and MCP server names. Prompts and responses appear only after an admin switches the destination to Full content mode.

Which permission do I need to add a tracing destination?

You need the admin role in your Claude Console organization to add or change destinations. The developer role can view destinations but cannot create or edit them. SDK tracing needs no admin role.

Can I send Claude traces to a self-hosted collector?

Yes, if the collector is reachable over OTLP over HTTP with protobuf at an HTTPS URL on port 443 with a hostname, not an IP address. A stock Collector listens on port 4318 by default, so configure its receiver for HTTPS on port 443 or put a reverse proxy in front of it.

Why do my API spans and SDK spans show different token totals?

Because the same request is counted twice when both sources are enabled. Count each token once by summing spans from only one source per request, using the API spans when both are active.

Is Claude Managed Agents tracing production ready?

It is in public beta as of October 2026, so span names and attributes can still change. Pin your SDK version and build dashboards on stable attributes such as service name and token counts.

Conclusion

Tracing Claude Managed Agents takes one Console destination, not an instrumentation project: an admin adds the OTLP endpoint, the platform emits standard GenAI spans for every turn, model call, and tool use, and your existing backend does the rest. Start on Metadata only, confirm delivery with the test span, build token and latency panels from API spans alone, and enable Full content only where prompt text is approved to live. Next, trace the tools your agents call, starting with the MCP server tutorial and the complete n8n guide.

Frequently asked questions