Use OpenTelemetry with the Claude API

With OpenTelemetry, the Claude API can emit a span for each model request and each tool use that it runs. You can view these spans in your observability platform without changing your code.

The API emits spans for your Messages API requests and Managed Agents sessions. To receive them, add a destination in the Claude Console. A destination tells the API your observability platform's OTLP endpoint and how to authenticate with it.

What you need

• The admin role in a Claude Console organization, to add and change destinations. With the developer role, you can view them. If your organization is on Claude Platform on AWS, sign in to the Console through the AWS Console, as Signing in describes.
• An OTLP/HTTP endpoint that accepts protobuf encoding at an HTTPS URL on port 443. If you run your own OpenTelemetry Collector, its OTLP/HTTP receiver listens on port 4318 by default. Configure the receiver to accept HTTPS on port 443, or put a load balancer or reverse proxy in front of the Collector.
• Credentials for the endpoint, such as an API key.

1. Add a destination

1. In the Console, open your organization's OpenTelemetry settings page and click Add destination.

2. Configure the destination:

   Field	What to enter
   Provider	Your observability platform, or Custom if it isn't listed. If you choose a listed platform, the Console asks for its details, such as an API key, instead of the OTLP endpoint URL, Request headers, and OTLP traces endpoint URL.
   Name	Optional. For example, "Acme's observability platform."
   OTLP endpoint URL	The base HTTPS URL of your observability platform's OTLP/HTTP endpoint, with a hostname, not an IP address. It can have a path prefix, for example https://gateway.example.com/otlp. Don't add /v1/traces, because the API adds it. If you set an OTLP traces endpoint URL, the API uses that URL instead.
   Request headers	The headers that the API sends with each request, for example your observability platform's API key header. Put credentials only in header values. After you save, the Console doesn't show the values again.
   Content mode	Metadata only or Full content. See how the content modes differ.
   Workspaces	The workspaces whose spans the destination receives: All, Selected, or All except. See Choose workspaces for a destination.
   OTLP traces endpoint URL	Optional, under Advanced settings. The full URL of your observability platform's traces endpoint, for example https://gateway.example.com/custom/traces. Set it when the platform receives traces at a URL other than the OTLP endpoint URL plus /v1/traces. It must have the same host as the OTLP endpoint URL.
   Maximum content size in MB	Optional, under Advanced settings when the content mode is Full content. The most content that the API sends in each span. The Console fills it in based on the Provider you choose. Change it to fit what your observability platform accepts. Leave it empty to send as much as the API allows. See Content limits.

3. Click Add destination to save.

4. Click Test in the destination's More actions menu. You will see a message that the test span was delivered to your collector, or how the delivery failed (see Delivery errors).

5. Check that the anthropic.test span arrived in your observability platform.

Admin API and CLI

You can also add a destination with the Admin API instead of the Console. Sign in to the CLI as an admin, or use an Admin API key in ANTHROPIC_API_KEY. On Claude Platform on AWS, send the requests to https://aws-external-anthropic.{region}.api.aws instead, signed with your AWS credentials as in Making requests. There, your IAM policy determines who can manage destinations. A request can include only the workspaces of your AWS account in that Region.

client = anthropic.Anthropic()

destination = client.beta.organization.telemetry_destinations.create(
    endpoint_url="https://gateway.example.com/otlp",
    headers={"authorization": "Bearer YOUR_OBSERVABILITY_API_KEY"},
    traces={"content_mode": "metadata_only"},
    workspaces={"type": "all"},
)

print(destination.id)

A create request takes the Console's settings except Provider, so enter your observability platform's endpoint URL and headers yourself. Set traces.max_content_bytes, in bytes, to fit what your observability platform accepts (see Content limits). To list, change, or delete destinations, or to add or remove one workspace, use the other methods of the telemetry destinations API.

2. Choose workspaces for a destination

A destination receives the spans of the workspaces that it covers. Choose them when you add the destination. For Workspaces, select one of the following:

• All: Every workspace in the organization, including the Default Workspace and workspaces created later.
• Selected: Only the workspaces that you select.
• All except: Like All, but without the workspaces that you select.

For Selected or All except, select the workspaces in the search box that appears under the options. To change a destination's workspaces later, open its More actions menu on the OpenTelemetry settings page while the Workspace filter shows All. Click Edit, then choose another Workspaces option or change the workspaces in the search box.

If you have the developer role in the organization and the Workspace Admin role in a workspace, you can add that workspace to a Selected destination or remove it. Set the Workspace filter to that workspace, then open the destination's More actions menu. On Claude Platform on AWS, the Console has no Workspace Admin role. There, your IAM policy determines who can add a workspace to a destination or remove it.

The API sends spans to every enabled destination that covers the workspace where the request or session runs.

3. Check that spans arrive

1. In the Console, select a workspace that the destination covers and send a Messages API request in playground. You can also send a Messages API request from your application or start a Managed Agents session in that workspace. To start a session, you can follow the steps in Get started with Claude Managed Agents.
2. In the Console, on the OpenTelemetry settings page, check that the Delivery column shows Healthy for the destination. This can take about a minute.
3. In your observability platform, filter on service.name = claude-platform to find the request's spans.

If the column shows Failing, hover over it to see the last error. To find the likely cause, see Delivery errors.

4. Connect API spans to your own traces

By default, the API spans for a Messages API request or a Managed Agents session are in their own traces. Connect them to your application's traces, so that they nest under your own spans.

The API reads each request's trace context from the W3C traceparent header. If the sampled flag in the header is off, the API doesn't emit the request's span or the spans under it. Claude Platform on AWS doesn't support this header yet. The spans for requests that you send to it always start their own traces, even when the sampled flag is off.

from opentelemetry import trace

tracer = trace.get_tracer("my-service")

with tracer.start_as_current_span("summarize_issues"):
    client.beta.sessions.events.send(
        session.id,
        events=[
            {
                "type": "user.message",
                "content": [{"type": "text", "text": "Summarize the open issues"}],
            },
        ],
    )

import os
import httpx2
from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator

headers = {
    "x-api-key": os.environ["ANTHROPIC_API_KEY"],
    "anthropic-version": "2023-06-01",
    "anthropic-beta": "managed-agents-2026-04-01",
    "content-type": "application/json",
}
# Copy the active span's trace context into the request headers.
TraceContextTextMapPropagator().inject(headers)

httpx2.post(
    f"https://api.anthropic.com/v1/sessions/{os.environ['SESSION_ID']}/events",
    headers=headers,
    json={
        "events": [
            {
                "type": "user.message",
                "content": [{"type": "text", "text": "Summarize the open issues"}],
            },
        ],
    },
)

The Messages API also passes the trace on to your MCP server when you connect it with the MCP connector, so that it can put its own spans under the API spans. Each request and notification that the API sends to your MCP server has a W3C traceparent in params._meta. In a tools/call request, it references the anthropic.mcp_tool_use span of that tool use. In the other messages, it references the anthropic.messages.create span. For a request that the API doesn't trace, such as one whose traceparent header has the sampled flag off, the API sends no traceparent.

Next steps

Delivery and health

The following rules apply to the spans that the API sends to your destinations.

• At least once: A destination can receive the same span more than once. To remove duplicates, use the trace ID and span ID.
• Best effort: A span can be lost before delivery. The API can't send a lost span again.
• Compression: The API compresses every delivery's first request with gzip and sets the header Content-Encoding: gzip. If your endpoint answers that request with a 400 or 415 response, the API sends the same spans again right away without compression.
• Retries: The API retries a delivery later, a limited number of times, after a timeout, a connection, TLS, or DNS failure, or a 408, 429, or 5xx response. It doesn't retry other failures.
• Timeouts: For each request, your endpoint must complete the TLS handshake within 5 seconds and send the response headers within 5 seconds. Each delivery times out after 10 seconds in total, including the resend without compression.
• User agent: Each request has the header User-Agent: Claude-Platform.

The Delivery column shows each destination's state. The state can be up to a minute late.

The API disables a destination when:

• The endpoint sends a 3xx redirect.
• The endpoint's hostname resolves to an IP address that isn't public.
• All deliveries fail for 24 hours.

The API doesn't send spans to a disabled destination. To resume export, fix the cause. Then, with the Workspace filter on the OpenTelemetry settings page showing All, click Enable in the destination's More actions menu. Export starts again within about a minute.

To change a destination, open its More actions menu while the Workspace filter shows All. Then click Edit, Disable, Enable, or Delete. If you change the host of the OTLP endpoint URL, enter the header values again. If the destination has an OTLP traces endpoint URL, give it the same new host, or clear it.

Limits

Troubleshooting

Delivery errors

When a delivery fails, the Delivery column shows Failing. Hover over it to see the error, then find the likely cause:

Compatibility