api changedmanage-claude/opentelemetry/api
Nearest release: v2.1.312, published under an hour before this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+33added
Lines−33removed
From line
22
where the diff opens
First seen
14 Oct 2026
this site's first read of the page
Recorded edits10to this page, all time
The whole hunk
from line 22, old and new numbered
/
from line 22
2222
2323With 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.
2424
25The 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.
25The 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.
2626
2727## What you need
2828
from line 33
3333## 1. Add a destination
3434
3535<Info>
36 When you add a telemetry destination, Anthropic will send traces of Claude Platform activity in your organization to the third-party provider's OTLP/HTTP endpoint that you specify, in accordance with your provider terms and access controls. After delivery, the data is held by the service that you chose, outside Anthropic, under that service's retention and access controls.
36 When you add a telemetry destination, Anthropic will send traces of Claude Platform activity in your organization to the third-party provider’s OTLP/HTTP endpoint that you specify, in accordance with your provider terms and access controls. After delivery, the data is held by the service that you chose, outside Anthropic, under that service’s retention and access controls.
3737</Info>
3838
391. In the Console, open your organization's [OpenTelemetry settings page](https://platform.claude.com/settings/telemetry-destinations) and click **Add destination**.
391. In the Console, open your organization’s [OpenTelemetry settings page](https://platform.claude.com/settings/telemetry-destinations) and click **Add destination**.
4040
41412. Configure the destination:
4242
4343 | Field | What to enter |
4444 | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
45 | **Provider** | Your observability platform, or **Custom** if it isn't listed. If you select 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**. |
46 | **Name** | Optional. For example, "Acme's observability platform." |
47 | **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. |
48 | **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. |
45 | **Provider** | Your observability platform, or **Custom** if it isn’t listed. If you select 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**. |
46 | **Name** | Optional. For example, “Acme’s observability platform.” |
47 | **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. |
48 | **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. |
4949 | **Content mode** | **Metadata only** or **Full content**. See [how the content modes differ](https://platform.claude.com/docs/en/manage-claude/opentelemetry#choose-a-content-mode). |
5050 | **Workspaces** | The workspaces whose spans the destination receives: **All**, **Selected**, or **All except**. See [Choose workspaces for a destination](https://platform.claude.com/docs/en/manage-claude/opentelemetry/api#choose-workspaces-for-a-destination). |
51 | **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. |
51 | **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. |
5252 | **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 select. Change it to fit what your observability platform accepts. Leave it empty to send as much as the API allows. See [Content limits](https://platform.claude.com/docs/en/manage-claude/opentelemetry#content-limits). |
5353
54543. Click **Add destination** to save.
5555
564. 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](https://platform.claude.com/docs/en/manage-claude/opentelemetry/api#delivery-errors)).
564. 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](https://platform.claude.com/docs/en/manage-claude/opentelemetry/api#delivery-errors)).
5757
58585. Check that the `anthropic.test` span arrived in your observability platform.
5959
from line 211
211211 ```
212212</CodeGroup>
213213
214A 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` (csharp, go: `Traces.MaxContentBytes`; java, php: `traces.maxContentBytes`), in bytes, to fit what your observability platform accepts (see [Content limits](https://platform.claude.com/docs/en/manage-claude/opentelemetry#content-limits)). To list, change, or delete destinations, or to add or remove one workspace, use the other methods of the [telemetry destinations API](https://platform.claude.com/docs/en/api/beta/organization/telemetry_destinations).
214A 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` (csharp, go: `Traces.MaxContentBytes`; java, php: `traces.maxContentBytes`), in bytes, to fit what your observability platform accepts (see [Content limits](https://platform.claude.com/docs/en/manage-claude/opentelemetry#content-limits)). To list, change, or delete destinations, or to add or remove one workspace, use the other methods of the [telemetry destinations API](https://platform.claude.com/docs/en/api/beta/organization/telemetry_destinations).
215215
216216## 2. Choose workspaces for a destination
217217
from line 221
221221* **Selected:** Only the workspaces that you select.
222222* **All except:** Like **All**, but without the workspaces that you select.
223223
224For **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](https://platform.claude.com/settings/telemetry-destinations) in the Console while the **Workspace** filter shows **All**. Click **Edit**, then select another **Workspaces** option or change the workspaces in the search box.
224For **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](https://platform.claude.com/settings/telemetry-destinations) in the Console while the **Workspace** filter shows **All**. Click **Edit**, then select another **Workspaces** option or change the workspaces in the search box.
225225
226If 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](https://platform.claude.com/docs/en/api/claude-platform-on-aws-iam-actions) determines who can add a workspace to a destination or remove it.
226If 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](https://platform.claude.com/docs/en/api/claude-platform-on-aws-iam-actions) determines who can add a workspace to a destination or remove it.
227227
228228The API sends spans to every enabled destination that covers the [workspace where the request or session runs](https://platform.claude.com/docs/en/manage-claude/workspaces#api-keys-and-resource-scoping).
229229
from line 231
231231
2322321. In the Console, select a workspace that the destination covers and send a Messages API request in [playground](https://platform.claude.com/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](https://platform.claude.com/docs/en/managed-agents/quickstart).
2332332. In the Console, on the [OpenTelemetry settings page](https://platform.claude.com/settings/telemetry-destinations), check that the **Delivery** column shows **Healthy** for the destination. This can take about a minute.
2343. In your observability platform, filter on `service.name` = `claude-platform` to find the request's spans.
2343. In your observability platform, filter on `service.name` = `claude-platform` to find the request’s spans.
235235
236236If the column shows **Failing**, hover over it to see the last error. To find the likely cause, see [Delivery errors](https://platform.claude.com/docs/en/manage-claude/opentelemetry/api#delivery-errors).
237237
238238## 4. Connect API spans to your own traces
239239
240By 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.
240By 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.
241241
242The API reads each request's trace context from the W3C [`traceparent` header](https://www.w3.org/TR/trace-context/). If the sampled flag in the header is off, the API doesn't emit the request's span or the spans under it.
242The API reads each request’s trace context from the W3C [`traceparent` header](https://www.w3.org/TR/trace-context/). If the sampled flag in the header is off, the API doesn’t emit the request’s span or the spans under it.
243243
244244<Tabs>
245245 <Tab title="With the Claude SDK">
from line 363
363363 ```
364364 </CodeGroup>
365365
366 The SDK writes the `traceparent` header with your application's propagator, and the sampled flag in it follows your sampler. If your application uses a propagator other than W3C trace context, such as B3, also add the W3C trace context propagator.
366 The SDK writes the `traceparent` header with your application’s propagator, and the sampled flag in it follows your sampler. If your application uses a propagator other than W3C trace context, such as B3, also add the W3C trace context propagator.
367367 </Tab>
368368
369369 <Tab title="With other clients">
370 Copy the current span's trace context into the request headers, for example when you create a Managed Agents session or send a user message:
370 Copy the current span’s trace context into the request headers, for example when you create a Managed Agents session or send a user message:
371371
372372 <CodeGroup exclude="shell:CLI">
373373 ```bash cURL
from line 620
620620 </Tab>
621621</Tabs>
622622
623When you connect your MCP server with the [Messages API's MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector) or the [Managed Agents MCP connector](https://platform.claude.com/docs/en/managed-agents/mcp-connector), the API also passes the trace on to your server. The server can then put its own spans under the API spans. In `params._meta` of a `tools/call` request, the API sends a W3C `traceparent` that references the [`anthropic.mcp_tool_use`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-tool-use-anthropic-mcp-tool-use-and-anthropic-custom-tool-use) span for that tool use. With the Messages API's MCP connector, the other requests and notifications to your MCP server have a `traceparent` too, which references the [`anthropic.messages.create`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-messages-create) span. If the API doesn't trace your Messages API request, such as when its `traceparent` header has the sampled flag off, your MCP server gets no `traceparent`.
623When you connect your MCP server with the [Messages API’s MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector) or the [Managed Agents MCP connector](https://platform.claude.com/docs/en/managed-agents/mcp-connector), the API also passes the trace on to your server. The server can then put its own spans under the API spans. In `params._meta` of a `tools/call` request, the API sends a W3C `traceparent` that references the [`anthropic.mcp_tool_use`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-tool-use-anthropic-mcp-tool-use-and-anthropic-custom-tool-use) span for that tool use. With the Messages API’s MCP connector, the other requests and notifications to your MCP server have a `traceparent` too, which references the [`anthropic.messages.create`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-messages-create) span. If the API doesn’t trace your Messages API request, such as when its `traceparent` header has the sampled flag off, your MCP server gets no `traceparent`.
624624
625625## Next steps
626626
from line 639
639639The following rules apply to the spans that the API sends to your destinations.
640640
641641* **At least once:** A destination can receive the same span more than once. To remove duplicates, use the trace ID and span ID.
642* **Best effort:** A span can be lost before delivery. The API can't send a lost span again.
643* **Compression:** The API compresses requests with gzip and sets the header `Content-Encoding: gzip`. If your endpoint answers a compressed request with a `400`, `406`, `415`, or `422` response, the API sends the same spans again right away without compression. It then usually sends that destination's later requests without compression for about a day.
644* **Retries:** The API retries a delivery later, a limited number of times, after a timeout, a connection, TLS, or DNS failure, an invalid address, or a `408`, `429`, or `5xx` response. It doesn't retry other failures.
642* **Best effort:** A span can be lost before delivery. The API can’t send a lost span again.
643* **Compression:** The API compresses requests with gzip and sets the header `Content-Encoding: gzip`. If your endpoint answers a compressed request with a `400`, `406`, `415`, or `422` response, the API sends the same spans again right away without compression. It then usually sends that destination’s later requests without compression for about a day.
644* **Retries:** The API retries a delivery later, a limited number of times, after a timeout, a connection, TLS, or DNS failure, an invalid address, or a `408`, `429`, or `5xx` response. It doesn’t retry other failures.
645645* **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 any resend.
646646* **User agent:** Each request has the header `User-Agent: Claude-Platform`.
647647
648The **Delivery** column shows each destination's state. The state can be up to a minute late.
648The **Delivery** column shows each destination’s state. The state can be up to a minute late.
649649
650650| Delivery state | Meaning |
651651| -------------- | --------------------------------------------------------------------------- |
652652| **Healthy** | The last delivery succeeded. |
653653| **Failing** | The last delivery failed. To see the error, hover over **Failing**. |
654| **No data** | The API hasn't tried a delivery yet. |
655| **Disabled** | The destination doesn't receive spans. To see why, hover over **Disabled**. |
654| **No data** | The API hasn’t tried a delivery yet. |
655| **Disabled** | The destination doesn’t receive spans. To see why, hover over **Disabled**. |
656656
657657The API disables a destination when:
658658
from line 659
659659* The endpoint sends a `3xx` redirect.
660660* All deliveries fail for 24 hours.
661661
662While a destination is disabled, the API drops the spans for it, and they aren't sent after you enable it again. To resume export, fix the cause and check the fix with **Test** in the destination's **More actions** menu. Then, on the [OpenTelemetry settings page](https://platform.claude.com/settings/telemetry-destinations) in the Console, click **Enable** in the same menu while the **Workspace** filter shows **All**. Export starts again within about a minute. Until the next delivery, the **Delivery** column can still show **Failing** with the old error.
662While a destination is disabled, the API drops the spans for it, and they aren’t sent after you enable it again. To resume export, fix the cause and check the fix with **Test** in the destination’s **More actions** menu. Then, on the [OpenTelemetry settings page](https://platform.claude.com/settings/telemetry-destinations) in the Console, click **Enable** in the same menu while the **Workspace** filter shows **All**. Export starts again within about a minute. Until the next delivery, the **Delivery** column can still show **Failing** with the old error.
663663
664664To 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.
665665
from line 692
692692| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
693693| HTTP error (status 401) or HTTP error (status 403) | A wrong authentication header |
694694| HTTP error (status 404) | A wrong path in the **OTLP endpoint URL** or the **OTLP traces endpoint URL** |
695| Invalid address | The endpoint's hostname doesn't exist or doesn't resolve to a public IP address |
696| Temporary DNS failure | The DNS lookup of the endpoint's hostname failed, for example because its DNS server returned an error |
697| TLS failure | A TLS problem, for example with the endpoint's certificate |
698| Timeout | The endpoint didn't respond in time. See [the delivery timeouts](https://platform.claude.com/docs/en/manage-claude/opentelemetry/api#delivery-and-health) |
699| Connection failure | The API couldn't connect to the endpoint |
700| Redirect (status 3xx) | The endpoint redirected the request. The API doesn't follow redirects, so use the URL it redirects to |
695| Invalid address | The endpoint’s hostname doesn’t exist or doesn’t resolve to a public IP address |
696| Temporary DNS failure | The DNS lookup of the endpoint’s hostname failed, for example because its DNS server returned an error |
697| TLS failure | A TLS problem, for example with the endpoint’s certificate |
698| Timeout | The endpoint didn’t respond in time. See [the delivery timeouts](https://platform.claude.com/docs/en/manage-claude/opentelemetry/api#delivery-and-health) |
699| Connection failure | The API couldn’t connect to the endpoint |
700| Redirect (status 3xx) | The endpoint redirected the request. The API doesn’t follow redirects, so use the URL it redirects to |
701701| HTTP error (status 408, 429, or 5xx) | The endpoint was overloaded, limited the rate of requests, or had an error |
702702| HTTP error (another 4xx status) | The endpoint refused the request, for example because of its size or format |
703703
No line in this hunk matches that.