One read of Claude Developer Platformapi-20261014T183711Z
7 pages moved out of 767 read.
Pages moved
7
significant first
Pages read
767
in this capture
Captured
18:37 UTC
Corpus hash
78a3f873b223
index-hash
What this read moved
1-7 of 7api/opentelemetry/spans New page · 452 lines, new page
## Span names and kinds ## Span status ## Attributes ### Common attributes ### Session attributes ### Content attributes ### Token usage ## Spans ### `anthropic.messages.create` ### `anthropic.messages.count_tokens` ### `anthropic.sessions.create` ### `anthropic.sessions.events.send` ### `anthropic.sessions.update` ### `anthropic.session.turn` ### `anthropic.model_request` ### `anthropic.tool_use`, `anthropic.mcp_tool_use`, and `anthropic.custom_tool_use` ### `anthropic.compaction` ### `anthropic.session.outcome_evaluation` ### `anthropic.messages.tool_runner` ### `anthropic.messages.batches.<method>` ### `anthropic.sessions.<method>` ### `anthropic.environment.work` ### `anthropic.<resources>.<method>`
A whole new page. There's nothing to diff it against, so here is what it says.
---
title: OpenTelemetry span reference
url: https://platform.claude.com/docs/en/api/opentelemetry/spans
description: The OpenTelemetry spans and span attributes that the Claude API and the Claude SDK emit.
featureMetadata:
topic:
title: OpenTelemetry
url: https://platform.claude.com/docs/en/manage-claude/opentelemetry
status: beta
---
<Note>
OpenTelemetry export is in beta. It's provided under your agreement with Anthropic, including the Beta Services section of the [Service Specific Terms](https://www.anthropic.com/legal/service-specific-terms). Span names and attributes can change during the beta.
</Note>
To set up export, see [Use OpenTelemetry with the Claude SDK](https://platform.claude.com/docs/en/manage-claude/opentelemetry/sdk) and [Use OpenTelemetry with the Claude API](https://platform.claude.com/docs/en/manage-claude/opentelemetry/api).
## Span names and kinds
| Property | SDK spans | API spans |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| `service.name` | The application's `service.name` | `claude-platform` |
| Instrumentation scope | `com.anthropic.sdk.<language>` or `com.anthropic.sdk.cli`, plus `.<platform>` on a cloud platform's client, with the package's version | `com.anthropic.claude-platform` |
| Span kind | `CLIENT` on the span for a request, `INTERNAL` otherwise | `SERVER` on the span for a request, `INTERNAL` otherwise |
* **Spans for requests** have the name of the request's API method: `anthropic.` followed by the method's path in the API reference, with dots instead of slashes and without `beta`. For example, `client.beta.sessions.events.send()` (csharp, go: `client.Beta.Sessions.Events.Send()`; java: `client.beta().sessions().events().send()`; php: `$client->beta->sessions->events->send()`; ruby: `client.beta.sessions.events.send_()`) sends a request to [send session events](https://platform.claude.com/docs/en/api/beta/sessions/events/send), and its spans have the name [`anthropic.sessions.events.send`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-sessions-events-send).
* **Tool spans** have a fixed name, a space, and the tool name, for example [`anthropic.tool_use bash`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-tool-use-anthropic-mcp-tool-use-and-anthropic-custom-tool-use).
## Span status
* **`OK`:** The step completed.
* **`ERROR`:** The step failed.
* **Unset:** The application canceled the step, for example when it sent a [`user.interrupt`](https://platform.claude.com/docs/en/api/beta/sessions/events#beta_managed_agents_user_interrupt_event) event.
A stream's span ends when the stream ends. If the application closes the stream early, the SDK span has the status unset, so the SDK span for a stream that never completes, such as [`anthropic.sessions.events.stream`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-sessions-method), has the status unset or `ERROR`.
## Attributes
Attributes use the [OpenTelemetry semantic conventions for generative AI](https://github.com/open-telemetry/semantic-conventions-genai) (`gen_ai.*`) where one exists. Anthropic attributes start with `anthropic.`. The spans follow the conventions at commit [`e57c543b`](https://github.com/open-telemetry/semantic-conventions-genai/tree/e57c543b4889619eb2a05702471937db5119165d) of September 24, 2026. The conventions are still in development.
### Common attributes
Every span for a request has the following attributes, except where a description says otherwise. Other spans can have only the first three:
| Attribute | Type | Description |
| --------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `gen_ai.provider.name` | `string` | `anthropic`. On every span.<br />**SDK:** `aws.bedrock` on the Amazon Bedrock clients (Mantle included), and `gcp.vertex_ai` on the client for Google Cloud's Agent Platform. |
| `anthropic.organization.id` | `string` | The organization ID. |
| `anthropic.workspace.id` | `string` | The ID of the workspace that the work runs in. |
| `anthropic.request.id` | `string` | The value of the `request-id` response header. |
| `http.request.method` | `string` | The request's HTTP method, for example `POST`. |
| `http.route` | `string` | The endpoint's path, with placeholders for its path parameters, for example `/v1/sessions/{session_id}`. |
| `http.response.status_code` | `int` | The final response's HTTP status code. For a stream, the status code sent with the headers. Absent when there was no response. |
| `server.address` | `string` | The host that the request was sent to, for example `api.anthropic.com`. |
| `server.port` | `int` | The request URL's port, or the default port of its scheme when the URL doesn't have one. |
| `url.scheme` | `string` | The URL's scheme, for example `https`. |
| `url.path` | `string` | The URL's path, for example `/v1/messages`. |
| `url.query` | `string` | The URL's query string, with only the query parameters that the endpoint defines. Absent when there are none. |
| `url.full` | `string` | The request's URL. |
On Claude Platform on AWS, API spans don't have `server.address`, `server.port`, or `url.full`.
### Session attributes
In a Managed Agents session, spans have the following attributes. A session's spans can be in more than one trace, so to assemble a view of the session, such as a transcript, [group its spans by these IDs](https://platform.claude.com/docs/en/manage-claude/opentelemetry#a-managed-agents-session).
| Attribute | Type | Description |
| ------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `anthropic.session.id` | `string` | The session ID. Absent on the spans for methods that don't act on one session, such as [`anthropic.sessions.list`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-sessions-method). |
| `gen_ai.conversation.id` | `string` | The ID of the session thread that the span belongs to. The SDK's [`conversation_id` (typescript, java, php: `conversationId`; csharp: `ConversationId`; go: `option.WithOpenTelemetryConversationID()`) option](https://platform.claude.com/docs/en/manage-claude/opentelemetry/sdk#configure-the-sdk) replaces it with your own conversation ID. Absent on SDK spans with no thread unless you set the option, and on API spans for Sessions API requests other than requests to one thread. |
### Content attributes
Attributes tagged with <Badge>Content</Badge> are only on spans in content mode, from the SDK and the API alike. See [how the content modes differ in the guide](https://platform.claude.com/docs/en/manage-claude/opentelemetry#choose-a-content-mode). When this content is too large, the SDK and the API [shorten it](https://platform.claude.com/docs/en/manage-claude/opentelemetry#content-limits) and set `anthropic.content.truncated` to `true`. If Anthropic's safeguards withhold content from a response, the API's spans don't include that content either.
The message attributes are JSON strings in the message format of the OpenTelemetry GenAI conventions. Each Anthropic content block becomes one GenAI conventions message part, on the Messages API and in Managed Agents message events such as `agent.message`:
| Anthropic content block | GenAI conventions message part |
| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `text` | `text` |
| `tool_use`, `server_tool_use` | `tool_call`, with `anthropic_toolset_name` for a `tool_use` block that has a `toolset_name`, such as `computer` |
| `mcp_tool_use` | `tool_call` with `anthropic_mcp_server_name` |
| `tool_result`, `mcp_tool_result`, a server tool's result block such as `web_search_tool_result` | `tool_call_response` |
| `thinking` | `reasoning`, without the `thinking` block's signature. Not in Managed Agents spans, because the `agent.thinking` event doesn't include the thinking content. |
| Any other block, such as `image` | The block's `type` with the prefix `anthropic_`, such as `anthropic_image`. The part has no other fields. |
Each Managed Agents tool use or tool result event also becomes one GenAI conventions message part:
| Managed Agents event | GenAI conventions message part |
| ------------------------------------------------------------------------------------------- | -------------------------------------------- |
| `agent.tool_use`, `agent.custom_tool_use` | `tool_call` |
| `agent.mcp_tool_use` | `tool_call` with `anthropic_mcp_server_name` |
| `user.tool_result`, `user.custom_tool_result`, `agent.tool_result`, `agent.mcp_tool_result` | `tool_call_response` |
### Token usage
The following spans have token usage attributes: [`anthropic.messages.create`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-messages-create), [`anthropic.model_request`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-model-request), [`anthropic.compaction`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-compaction), and [`anthropic.session.outcome_evaluation`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-session-outcome-evaluation). The values are for each span's step, for example the request, the model request, or the compaction. To count each token once, see [how to count tokens in the guide](https://platform.claude.com/docs/en/manage-claude/opentelemetry#count-tokens).
| Attribute | Type | Description |
| ---------------------------------------------------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `gen_ai.usage.input_tokens` | `int` | The input tokens, cache reads and writes included. |
| `gen_ai.usage.output_tokens` | `int` | The output tokens. |
| `gen_ai.usage.cache_write.input_tokens` | `int` | The tokens written to the prompt cache. Absent on [`anthropic.session.outcome_evaluation`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-session-outcome-evaluation) spans. |
| `anthropic.usage.cache_creation.ephemeral_5m_input_tokens` | `int` | The tokens written to the 5-minute cache. Only on the spans for Messages API requests. On a streaming response's SDK span, only the tokens written before the first output token. |
| `anthropic.usage.cache_creation.ephemeral_1h_input_tokens` | `int` | The tokens written to the 1-hour cache. Only on the spans for Messages API requests. On a streaming response's SDK span, only the tokens written before the first output token. |
| `gen_ai.usage.cache_read.input_tokens` | `int` | The tokens read from the prompt cache. Absent on [`anthropic.session.outcome_evaluation`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-session-outcome-evaluation) spans. |
## Spans
A span can come from the SDK in the application or from the API, so each span in this reference lists its sources. Descriptions that start with **Messages API:** or **Managed Agents:** are for that product's spans. Attribute descriptions that start with a source, such as **SDK:** or **API:**, are for that source's spans.
### `anthropic.messages.create`
* **Source:** The SDK and the API.
* **Kind:** `CLIENT` from the SDK, `SERVER` from the API.
* **Parent of the SDK span:** The span that is current in the application when it calls the method. If no span is current, there's no parent.
* **Parent of the API span:** The span in the request's `traceparent` header, which is the SDK span when the request comes from the SDK. Without the header, the API span has no parent. See [how to send the `traceparent` header](https://platform.claude.com/docs/en/manage-claude/opentelemetry/api#connect-api-spans-to-your-own-traces).
* **Children of the SDK span:** The API span for that request.
* **Children of the API span:** An [`anthropic.model_request`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-model-request) span for each model request, a [tool span](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-tool-use-anthropic-mcp-tool-use-and-anthropic-custom-tool-use) for each use of a server tool or an MCP connector tool that the API runs in the request, and an [`anthropic.compaction`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-compaction) span for each compaction.
The SDK emits this span for each Messages request, streamed or not.
The API emits this span for each [`POST /v1/messages`](https://platform.claude.com/docs/en/api/messages/create) request that it authenticates. It doesn't emit the span for a request to the [OpenAI-compatible endpoint](https://platform.claude.com/docs/en/cli-sdks-libraries/libraries/openai-sdk), `POST /v1/chat/completions`.
The API emits one span for a request, even when a [fallback model](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback) serves it.
The span has the [token usage attributes](https://platform.claude.com/docs/en/api/opentelemetry/spans#token-usage). The SDK span also has the attributes of every [SDK span for a request](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-resources-method).
| Attribute | Type | Description |
| ------------------------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `gen_ai.operation.name` | `string` | `chat` |
| `gen_ai.request.model` | `string` | The request's [`model`](https://platform.claude.com/docs/en/api/messages/create#create.model). |
| `gen_ai.response.id` | `string` | The response's [`id`](https://platform.claude.com/docs/en/api/messages/create#message). |
| `gen_ai.response.model` | `string` | The model that served the request. It differs from the requested model when the request uses a model alias, or when a [fallback model](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback) served the request. |
| `anthropic.message.stop_reason` | `string` | The response's [`stop_reason`](https://platform.claude.com/docs/en/api/messages#stop_reason), for example `end_turn`. |
| `anthropic.response.service_tier` | `string` | The service tier that served the request: the response's [`usage.service_tier`](https://platform.claude.com/docs/en/api/messages#usage). See [how requests get assigned tiers](https://platform.claude.com/docs/en/api/service-tiers#how-requests-get-assigned-tiers). |
| `error.type` | `string` | A failed request's [error type](https://platform.claude.com/docs/en/api/errors#http-errors), for example `rate_limit_error`.<br />**SDK:** Also the other values in [SDK spans for requests](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-resources-method).<br />**API:** `api_error` when the API ends the request without an error response. |
| `gen_ai.response.time_to_first_chunk` | `double` | Only on a streaming response's SDK span. The seconds from when the SDK first sent the request to the stream's first `content_block_delta` event, if it has one. |
| `gen_ai.usage.reasoning.output_tokens` | `int` | The response's thinking tokens. They are part of the output tokens. Absent when the response's usage doesn't have details for the output tokens. |
| `anthropic.usage.compaction.input_tokens` | `int` | Input tokens of the request's [compactions](https://platform.claude.com/docs/en/build-with-claude/compaction), including cache reads and writes. Not part of `gen_ai.usage.input_tokens`. Absent when the response has no compaction. |
| `anthropic.usage.compaction.output_tokens` | `int` | Output tokens of the request's compactions. Not part of `gen_ai.usage.output_tokens`. Absent when the response has no compaction. |
| `gen_ai.request.max_tokens` | `int` | The request's [`max_tokens`](https://platform.claude.com/docs/en/api/messages/create#create.max_tokens). |
| `gen_ai.request.temperature` | `double` | The request's [`temperature`](https://platform.claude.com/docs/en/api/messages/create#create.temperature). Absent when the request doesn't set it. |
| `gen_ai.request.top_p` | `double` | The request's [`top_p`](https://platform.claude.com/docs/en/api/messages/create#create.top_p). Absent when the request doesn't set it. |
| `gen_ai.request.top_k` | `int` | The request's [`top_k`](https://platform.claude.com/docs/en/api/messages/create#create.top_k). Absent when the request doesn't set it. |
| `gen_ai.request.stream` | `boolean` | `true` when the request sets [`stream: true`](https://platform.claude.com/docs/en/api/messages/create#create.stream). Absent otherwise. |
| `gen_ai.request.reasoning.level` | `string` | The [`effort`](https://platform.claude.com/docs/en/api/messages/create#create.output_config.effort) in the request's [`output_config`](https://platform.claude.com/docs/en/api/messages/create#create.output_config). Absent when the request doesn't set it. |
| `gen_ai.output.type` | `string` | `json` when the request sets the output format to JSON. Absent otherwise. |
| `anthropic.request.service_tier` | `string` | The request's [`service_tier`](https://platform.claude.com/docs/en/api/messages/create#create.service_tier). Absent when the request doesn't set it. |
| `anthropic.thinking.type` | `string` | The request's [`thinking.type`](https://platform.claude.com/docs/en/api/messages/create#create.thinking). Absent when the request doesn't set it. |
| `anthropic.thinking.budget_tokens` | `int` | The [`budget_tokens`](https://platform.claude.com/docs/en/api/messages#thinking_config_enabled.budget_tokens) in the request's [`thinking`](https://platform.claude.com/docs/en/api/messages/create#create.thinking) object. Absent when the request doesn't set it. |
| `anthropic.beta` | `string[]` | Only on the SDK span. The beta names in the request's [`anthropic-beta`](https://platform.claude.com/docs/en/api/beta/messages/create#create.betas) header. |
| `gen_ai.system_instructions` | `string` | <Badge>Content</Badge> A JSON string that follows the OpenTelemetry [`SystemInstructions`](https://github.com/open-telemetry/semantic-conventions-genai/blob/e57c543b4889619eb2a05702471937db5119165d/model/gen-ai/gen-ai-system-instructions.json) schema. The request's [`system`](https://platform.claude.com/docs/en/api/messages/create#create.system) prompt. |
| `gen_ai.input.messages` | `string` | <Badge>Content</Badge> A JSON string that follows the OpenTelemetry [`InputMessages`](https://github.com/open-telemetry/semantic-conventions-genai/blob/e57c543b4889619eb2a05702471937db5119165d/model/gen-ai/gen-ai-input-messages.json) schema. The request's [`messages`](https://platform.claude.com/docs/en/api/messages/create#create.messages). |
| `gen_ai.output.messages` | `string` | <Badge>Content</Badge> A JSON string that follows the OpenTelemetry [`OutputMessages`](https://github.com/open-telemetry/semantic-conventions-genai/blob/e57c543b4889619eb2a05702471937db5119165d/model/gen-ai/gen-ai-output-messages.json) schema. The response's [`content`](https://platform.claude.com/docs/en/api/messages/create#message), as one `assistant` message.<br />**SDK:** On a stream, only when the application reads the stream as [Tracing a stream](https://platform.claude.com/docs/en/manage-claude/opentelemetry/sdk#trace-a-stream) describes. |
| `gen_ai.request.stop_sequences` | `string[]` | <Badge>Content</Badge> The request's [`stop_sequences`](https://platform.claude.com/docs/en/api/messages/create#create.stop_sequences). |
A request's spans don't have the response's server tool usage counts, such as `web_search_requests`. Instead, the API emits a [tool span](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-tool-use-anthropic-mcp-tool-use-and-anthropic-custom-tool-use) for each use of a server tool.
### `anthropic.messages.count_tokens`
* **Source:** The SDK. The API doesn't emit a span for [`POST /v1/messages/count_tokens`](https://platform.claude.com/docs/en/api/messages/count_tokens).
* **Kind:** `CLIENT`.
* **Parent:** The span that is current in the application when it calls the method, or none if no span is current.
* **Children:** None.
| Attribute | Type | Description |
| --------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------- |
| `gen_ai.request.model` | `string` | The request's model. |
| `anthropic.message.count_tokens.input_tokens` | `int` | The token count in the response. This count isn't usage. Don't include it when you sum token usage. |
### `anthropic.sessions.create`
The same as [`anthropic.sessions.<method>`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-sessions-method), except for the following children and attributes:
* **Children of the SDK span:** The API span for that request.
* **Children of the API span:** The first turn's [`anthropic.session.turn`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-session-turn) span, when the request has non-empty [`initial_events`](https://platform.claude.com/docs/en/api/beta/sessions/create#create.initial_events).
| Attribute | Type | Description |
| ---------------------------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `gen_ai.agent.id` | `string` | The ID of the agent that the session was created from. |
| `gen_ai.agent.name` | `string` | That agent's name.<br />**SDK:** Absent when the request failed. |
| `gen_ai.request.model` | `string` | The model of that agent, which runs the primary thread.<br />**SDK:** Absent when the request failed. |
| `anthropic.session.environment.id` | `string` | The ID of the session's environment. |
### `anthropic.sessions.events.send`
The same as [`anthropic.sessions.<method>`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-sessions-method), except for the API span's children.
* **Children of the SDK span:** The API span for that request.
* **Children of the API span:** The [`anthropic.session.turn`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-session-turn) span for each turn that starts because of the request's events.
### `anthropic.sessions.update`
The same as [`anthropic.sessions.<method>`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-sessions-method), except for the API span's children.
* **Children of the SDK span:** The API span for that request.
* **Children of the API span:** The [`anthropic.session.turn`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-session-turn) span for each turn that resumes because the request raises or removes the [session budget](https://platform.claude.com/docs/en/managed-agents/budgets#resume-a-session-at-its-budget).
### `anthropic.session.turn`
* **Source:** The API, for Managed Agents sessions.
* **Kind:** `INTERNAL`.
* **Parent:** It depends on why the turn started:
* The [`anthropic.sessions.create`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-sessions-create) span, for the first turn of a session that was created with non-empty [`initial_events`](https://platform.claude.com/docs/en/api/beta/sessions/create#create.initial_events).
* The [`anthropic.sessions.events.send`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-sessions-events-send) span for the request in which the event was sent, for a turn that started because of an event, for example a [`user.message`](https://platform.claude.com/docs/en/api/beta/sessions/events#beta_managed_agents_user_message_event) event.
* The [`anthropic.sessions.update`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-sessions-update) span, for a turn that resumes because the session budget was raised or removed through the request.
* The `anthropic.session.turn` span for the turn of [the agent that the session runs](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration) during which that agent started this turn, for a turn on another thread.
* None, for a turn that starts because an agent on another thread replied or finished its turn, such as an agent that the primary agent called.
* **Children:**
* An [`anthropic.model_request`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-model-request) span for each model request in the turn.
* A tool span each time the API runs a tool in the turn, except in the [cases listed in the tool span section](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-tool-use-anthropic-mcp-tool-use-and-anthropic-custom-tool-use).
* An `anthropic.session.turn` span for each turn that the agent that the session runs started on another thread during this turn.
* An [`anthropic.session.outcome_evaluation`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-session-outcome-evaluation) span for each iteration of an outcome evaluation that this turn starts.
A turn starts when its thread enters the `running` state and ends when the thread leaves it.
| Attribute | Type | Description |
| ------------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `gen_ai.operation.name` | `string` | `invoke_agent` |
| `gen_ai.agent.id` | `string` | The ID of the agent that runs the turn's thread. Absent on an [advisor](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#advisor-threads) thread. |
| `gen_ai.agent.name` | `string` | That agent's name. `anthropic.advisor` on an advisor thread. |
| `gen_ai.request.model` | `string` | That agent's model. On an advisor thread, the advisor's model. |
| `anthropic.session.turn.stop_reason` | `string` | Why the turn ended: the [`session.thread_status_idle`](https://platform.claude.com/docs/en/api/beta/sessions/events#beta_managed_agents_session_thread_status_idle_event) event's [`stop_reason.type`](https://platform.claude.com/docs/en/api/beta/sessions/events#beta_managed_agents_session_thread_status_idle_event), for example `requires_action`. Absent when the thread didn't go idle. |
| `error.type` | `string` | The [`error.type`](https://platform.claude.com/docs/en/api/beta/sessions/events#beta_managed_agents_session_error_event) of the [`session.error`](https://platform.claude.com/docs/en/api/beta/sessions/events#beta_managed_agents_session_error_event) event that ended the turn, if the turn failed. |
| `gen_ai.agent.description` | `string` | That agent's description. Absent on an advisor thread or when the agent doesn't have one. |
| `gen_ai.system_instructions` | `string` | <Badge>Content</Badge> A JSON string that follows the OpenTelemetry [`SystemInstructions`](https://github.com/open-telemetry/semantic-conventions-genai/blob/e57c543b4889619eb2a05702471937db5119165d/model/gen-ai/gen-ai-system-instructions.json) schema. The system prompt in effect for the turn. Only on a thread's first turn. Absent on an advisor thread. |
| `gen_ai.input.messages` | `string` | <Badge>Content</Badge> A JSON string that follows the OpenTelemetry [`InputMessages`](https://github.com/open-telemetry/semantic-conventions-genai/blob/e57c543b4889619eb2a05702471937db5119165d/model/gen-ai/gen-ai-input-messages.json) schema. The turn's input events: user messages and tool results, [`system.message`](https://platform.claude.com/docs/en/api/beta/sessions/events#beta_managed_agents_system_message_event_params) events, and messages from other threads. Absent on an advisor thread. |
| `gen_ai.output.messages` | `string` | <Badge>Content</Badge> A JSON string that follows the OpenTelemetry [`OutputMessages`](https://github.com/open-telemetry/semantic-conventions-genai/blob/e57c543b4889619eb2a05702471937db5119165d/model/gen-ai/gen-ai-output-messages.json) schema. The turn's output events: the agent's messages, tool uses, and tool results. |
### `anthropic.model_request`
* **Source:** The API, for Messages API requests and Managed Agents sessions.
* **Kind:** `INTERNAL`.
* **Parent:**
* **Messages API:** The [`anthropic.messages.create`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-messages-create) span for the request.
* **Managed Agents:** The [`anthropic.session.turn`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-session-turn) span for the turn that makes the request.
* **Children:** None.
On the Messages API, each span is one model request within the API request.
The span has the [token usage attributes](https://platform.claude.com/docs/en/api/opentelemetry/spans#token-usage).
| Attribute | Type | Description |
| ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `gen_ai.operation.name` | `string` | Only on the spans for Managed Agents sessions, where it's `chat`. On the Messages API, the [`anthropic.messages.create`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-messages-create) span for the request is the `chat` operation. |
| `gen_ai.request.model` | `string` | The request's model. |
| `gen_ai.response.model` | `string` | Only on the spans for Messages API requests. The model that ran the model request. |
| `error.type` | `string` | **Messages API:** The [`anthropic.messages.create`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-messages-create) span's `error.type`, if the request failed during this model request.<br />**Managed Agents:** If the model request failed, its [error type](https://platform.claude.com/docs/en/api/errors#http-errors), for example `rate_limit_error`. `api_error` if the model request failed without a response. |
### `anthropic.tool_use`, `anthropic.mcp_tool_use`, and `anthropic.custom_tool_use`
* **Source:** The SDK and the API.
* **Name:** `anthropic.tool_use <tool>`, `anthropic.mcp_tool_use <tool>`, or `anthropic.custom_tool_use <tool>`, where `<tool>` is the tool's name.
* **Kind:** `INTERNAL`.
* **Parent of the SDK span:** The span that is current in the application when the tool starts, which in the Messages tool runner is the [`anthropic.messages.tool_runner`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-messages-tool-runner) span. If no span is current, there's no parent.
* **Parent of the API span:**
* **Messages API:** The [`anthropic.messages.create`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-messages-create) span for the request in which the API runs the tool.
* **Managed Agents:** The [`anthropic.session.turn`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-session-turn) span for the turn in which the tool runs. For a tool use that waits for a [`user.tool_confirmation`](https://platform.claude.com/docs/en/api/beta/sessions/events#beta_managed_agents_user_tool_confirmation_event) event, that is the turn that starts because of the confirmation.
* For a tool use from code that another tool runs, the tool span for that tool. On the Messages API, that tool is the [code execution tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool).
* **Children of the SDK span:** The spans that the tool's code starts.
* **Children of the API span:** A tool span for each tool use from the code that this tool runs. For example, code that the code execution tool runs might use `web_search`.
The span name prefix depends on the type of tool:
* `anthropic.tool_use <tool>` is the span for each use of a [server tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools) on the Messages API or of a tool from the agent toolset of Managed Agents. The API runs the agent toolset tools, except in a [self-hosted sandbox](https://platform.claude.com/docs/en/manage-claude/opentelemetry/sdk#trace-a-self-hosted-sandbox), where the environment worker runs them.
* `anthropic.mcp_tool_use <tool>` is the span for each use of an MCP tool, in the SDK, on the Messages API, and on Managed Agents. In the SDK, it's a tool from an MCP helper that the [Messages tool runner](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-runner) or the [session tool runner](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-reference#session-tool-runner) runs. On the Messages API, the tool comes from the [MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector). On Managed Agents, if the [connection to the MCP server fails](https://platform.claude.com/docs/en/managed-agents/mcp-connector#handle-connection-and-authentication-failures), the span name doesn't include the tool name.
* `anthropic.custom_tool_use <tool>` is the span for each use of a tool that the application defines and a tool runner runs. Only the SDK emits this span.
The API doesn't emit a tool span in the following cases:
* The model asks to use a tool that the application runs, such as a [custom tool](https://platform.claude.com/docs/en/managed-agents/tools). If a tool runner in the SDK runs the tool, the tool runner emits its span.
* **Managed Agents:** The agent uses a tool that runs in a self-hosted sandbox. The worker in the SDK, which runs the tool, emits its span. See [how to trace a self-hosted sandbox](https://platform.claude.com/docs/en/manage-claude/opentelemetry/sdk#trace-a-self-hosted-sandbox).
* **Managed Agents:** The agent uses a [multiagent](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration) tool or the [advisor tool](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#give-the-session-an-advisor).
* **Managed Agents:** The agent asks to use a tool, but the server denies the use under the [`auto` permission policy](https://platform.claude.com/docs/en/managed-agents/permission-policies#let-the-server-evaluate-each-call-with-auto), or the application denies it in a [`user.tool_confirmation`](https://platform.claude.com/docs/en/api/beta/sessions/events#beta_managed_agents_user_tool_confirmation_event) event.
| Attribute | Type | Description |
| ------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `gen_ai.operation.name` | `string` | `execute_tool` |
| `gen_ai.tool.name` | `string` | The tool's name, for example `bash`. On API spans, an MCP tool's name doesn't have the server name. On Managed Agents, if the connection to the MCP server failed, it's the name that the model generated and is only on spans in content mode. |
| `gen_ai.tool.call.id` | `string` | **Messages API:** The `id` of the block in which the model asked to use the tool: a [`tool_use`](https://platform.claude.com/docs/en/api/messages#tool_use_block), [`server_tool_use`](https://platform.claude.com/docs/en/api/messages#server_tool_use_block), or [`mcp_tool_use`](https://platform.claude.com/docs/en/api/beta/messages#beta_mcp_tool_use_block) block.<br />**Managed Agents:** The ID of the event in which the agent asked to use the tool: an [`agent.tool_use`](https://platform.claude.com/docs/en/api/beta/sessions/events#beta_managed_agents_agent_tool_use_event), [`agent.mcp_tool_use`](https://platform.claude.com/docs/en/api/beta/sessions/events#beta_managed_agents_agent_mcp_tool_use_event), or [`agent.custom_tool_use`](https://platform.claude.com/docs/en/api/beta/sessions/events#beta_managed_agents_agent_custom_tool_use_event) event. |
| `anthropic.mcp.server.name` | `string` | Only on the API spans for MCP tools. The name of the tool's MCP server. On the Messages API, the [`mcp_tool_use`](https://platform.claude.com/docs/en/api/beta/messages#beta_mcp_tool_use_block) block's [`server_name`](https://platform.claude.com/docs/en/api/beta/messages#beta_mcp_tool_use_block.server_name). |
| `gen_ai.conversation.id` | `string` | The session thread ID, as [Session attributes](https://platform.claude.com/docs/en/api/opentelemetry/spans#session-attributes) describes. In the Messages tool runner, the conversation ID passed with the [`conversation_id` (typescript, java, php: `conversationId`; csharp: `ConversationId`; go: `option.WithOpenTelemetryConversationID()`) option](https://platform.claude.com/docs/en/manage-claude/opentelemetry/sdk#configure-the-sdk), and absent without one. Absent on the API spans for a Messages API request. |
| `anthropic.session.id` | `string` | The session ID. Absent for a tool use outside a Managed Agents session, such as on the Messages API or in the Messages tool runner. |
Cut at 300 lines. The page has the rest.
build-with-claude/claude-in-microsoft-foundry Changed · +4 / -4 lines
from line 80
8080 <Tabs>
8181 <Tab title="Gradle">
8282 ```kotlin
83 implementation("com.anthropic:anthropic-java:2.71.0")
84 implementation("com.anthropic:anthropic-java-foundry:2.71.0")
83 implementation("com.anthropic:anthropic-java:2.72.0")
84 implementation("com.anthropic:anthropic-java-foundry:2.72.0")
8585
8686 // For Entra ID authentication, also add the Azure Identity library
8787 implementation("com.azure:azure-identity:1.18.3")
from line 93
9393 <dependency>
9494 <groupId>com.anthropic</groupId>
9595 <artifactId>anthropic-java</artifactId>
96 <version>2.71.0</version>
96 <version>2.72.0</version>
9797 </dependency>
9898 <dependency>
9999 <groupId>com.anthropic</groupId>
100100 <artifactId>anthropic-java-foundry</artifactId>
101 <version>2.71.0</version>
101 <version>2.72.0</version>
102102 </dependency>
103103 <!-- For Entra ID authentication, also add the Azure Identity library -->
104104 <dependency>
build-with-claude/claude-on-amazon-bedrock-legacy Changed · +4 / -4 lines
from line 54
5454 <Tab title="Java">
5555 <CodeGroup>
5656 ```groovy Gradle
57 implementation("com.anthropic:anthropic-java:2.71.0")
58 implementation("com.anthropic:anthropic-java-bedrock:2.71.0")
57 implementation("com.anthropic:anthropic-java:2.72.0")
58 implementation("com.anthropic:anthropic-java-bedrock:2.72.0")
5959 ```
6060
6161 ```xml Maven
from line 62
6262 <dependency>
6363 <groupId>com.anthropic</groupId>
6464 <artifactId>anthropic-java</artifactId>
65 <version>2.71.0</version>
65 <version>2.72.0</version>
6666 </dependency>
6767 <dependency>
6868 <groupId>com.anthropic</groupId>
6969 <artifactId>anthropic-java-bedrock</artifactId>
70 <version>2.71.0</version>
70 <version>2.72.0</version>
7171 </dependency>
7272 ```
7373
manage-claude/opentelemetry New page · 211 lines, new page
## Get started ## Send traces to a partner platform ## Content modes ### Content limits ## Example traces and how to read them ### A Messages API request ### A Managed Agents session ## Counting tokens
A whole new page. There's nothing to diff it against, so here is what it says.
---
title: OpenTelemetry for the Claude API
url: https://platform.claude.com/docs/en/manage-claude/opentelemetry
description: Trace your Messages API requests, tool uses, and Managed Agents sessions with OpenTelemetry spans from the Claude SDK and the Claude API.
featureMetadata:
topic:
title: OpenTelemetry
url: https://platform.claude.com/docs/en/manage-claude/opentelemetry
status: beta
---
<Note>
OpenTelemetry export is in beta. It's provided under your agreement with Anthropic, including the Beta Services section of the [Service Specific Terms](https://www.anthropic.com/legal/service-specific-terms).
</Note>
The Claude API and the SDK can trace your Messages API requests, tool uses, and Managed Agents sessions with [OpenTelemetry](https://opentelemetry.io/). You can view these traces in the observability platform you already have. Use them to debug failed or slow requests, track token spend and latency, and build evals from real traffic. You can also see each request inside your application's own traces, linked to the user or feature that sent it.
OpenTelemetry is a vendor-neutral standard that most observability platforms support. A *trace* is the full record of one request through your system. A *span* is one step in a trace, such as a model request or a tool use. The API and the SDK use attributes from the [GenAI semantic conventions](https://github.com/open-telemetry/semantic-conventions-genai), so platforms that support the conventions can recognize the spans without extra setup.
## Get started
You can set up SDK tracing, API tracing, or both. Set up both to see a request's SDK and API spans in one trace, as in the [example traces](https://platform.claude.com/docs/en/manage-claude/opentelemetry#example-traces-and-how-to-read-them). For requests to Claude Platform on AWS, the API spans are in their own traces instead.
<CardGroup cols={3}>
<Card title="Set up SDK tracing" icon="code-brackets" href="https://platform.claude.com/docs/en/manage-claude/opentelemetry/sdk" layout="horizontal">
Install the SDK and register a tracer provider.
</Card>
<Card title="Set up API tracing" icon="cloud" href="https://platform.claude.com/docs/en/manage-claude/opentelemetry/api" layout="horizontal">
Add a destination in the Claude Console.
</Card>
<Card title="Span reference" icon="book" href="https://platform.claude.com/docs/en/api/opentelemetry/spans" layout="horizontal">
Look up spans and their attributes.
</Card>
</CardGroup>
| What you get | SDK tracing | API tracing | Both together |
| --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| [Messages API](https://platform.claude.com/docs/en/api/messages/create) requests | ✅ | ✅ | ✅ |
| [Sessions API](https://platform.claude.com/docs/en/managed-agents/sessions) requests | ✅ | ✅ | ✅ |
| [Token usage](https://platform.claude.com/docs/en/manage-claude/opentelemetry#count-tokens) | ✅ | ✅ | ✅ |
| Each model run within a request | — | ✅ | ✅ |
| [Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) turns | — | ✅ | ✅ |
| [Server tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools), run by the API | — | ✅ | ✅ |
| Client tools, run by the [tool runner](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-runner) | ✅ | — | ✅ |
| Tools in a [self-hosted sandbox](https://platform.claude.com/docs/en/manage-claude/opentelemetry/sdk#trace-a-self-hosted-sandbox) | ✅ | — | ✅ |
| Other API requests, such as uploading files | ✅ | — | ✅ |
| Setup | [Code](https://platform.claude.com/docs/en/manage-claude/opentelemetry/sdk) | [Console](https://platform.claude.com/docs/en/manage-claude/opentelemetry/api) | Both |
| Required permission | None | [Admin](https://platform.claude.com/docs/en/manage-claude/opentelemetry/api#what-you-need) | [Admin](https://platform.claude.com/docs/en/manage-claude/opentelemetry/api#what-you-need) |
| Coverage | Clients using the SDK | Any client | Any client |
| Cloud platform support | Any | Claude Platform<br />Claude Platform on AWS | Claude Platform<br />Claude Platform on AWS |
For Claude Code, the Agent SDK, or Cowork, see [Claude Code monitoring](https://code.claude.com/docs/en/monitoring-usage), [Agent SDK observability](https://code.claude.com/docs/en/agent-sdk/observability), or [Cowork activity monitoring](https://support.claude.com/en/articles/14477985-monitor-claude-cowork-activity-with-opentelemetry).
## Send traces to a partner platform
Send traces to any observability platform that accepts OTLP, including these partners:
<CardGroup cols={3}>
<Card title="Arize AI" image="https://platform.claude.com/docs/images/partner-logos/arize.svg" imageDark="https://platform.claude.com/docs/images/partner-logos/arize-dark.svg" imageOffsetLeft={2} href="https://arize.com/docs/ax/integrations/platforms/claude-managed-agents/claude-managed-agents-tracing">
Unified observability and evaluation platform for AI.
</Card>
<Card title="Braintrust" image="https://platform.claude.com/docs/images/partner-logos/braintrust.svg" imageDark="https://platform.claude.com/docs/images/partner-logos/braintrust-dark.svg" imageHeight={25} imageOffsetLeft={1} href="https://www.braintrust.dev/docs/integrations/ai-providers/anthropic#export-opentelemetry-traces-from-the-claude-api">
Active observability platform for agents.
</Card>
<Card title="Databricks" image="https://platform.claude.com/docs/images/partner-logos/databricks.svg" imageDark="https://platform.claude.com/docs/images/partner-logos/databricks-dark.svg" imageHeight={26} imageOffsetLeft={1} href="https://docs.databricks.com/aws/en/ai-gateway/unified-trace-table">
Unified AI control plane for observability and evaluation.
</Card>
<Card title="Datadog" image="https://platform.claude.com/docs/images/partner-logos/datadog.svg" imageDark="https://platform.claude.com/docs/images/partner-logos/datadog-dark.svg" imageHeight={28} imageOffsetLeft={2} href="https://docs.datadoghq.com/llm_observability/instrument/otel_instrumentation/?tab=python#using-claude-managed-agents">
AI-powered observability and security.
</Card>
<Card title="Grafana Cloud" image="https://platform.claude.com/docs/images/partner-logos/grafana.svg" imageDark="https://platform.claude.com/docs/images/partner-logos/grafana-dark.svg" imageHeight={34} imageOffsetLeft={2} href="https://grafana.com/docs/grafana-cloud/observe-and-act/agent-observability/guides/send-claude-platform-traces/">
Fully managed open observability platform.
</Card>
<Card title="Honeycomb" image="https://platform.claude.com/docs/images/partner-logos/honeycomb.svg" imageDark="https://platform.claude.com/docs/images/partner-logos/honeycomb-dark.svg" imageHeight={36} imageOffsetLeft={4} href="https://docs.honeycomb.io/send-data/use-cases/claude-platform">
Observability platform for the new shape of software.
</Card>
<Card title="Langfuse" image="https://platform.claude.com/docs/images/partner-logos/langfuse.svg" imageDark="https://platform.claude.com/docs/images/partner-logos/langfuse-dark.svg" imageHeight={26} imageOffsetLeft={1} href="https://langfuse.com/integrations/model-providers/claude-platform">
Open-source agent observability and evaluation platform.
</Card>
<Card title="LangSmith" image="https://platform.claude.com/docs/images/partner-logos/langchain.svg" imageDark="https://platform.claude.com/docs/images/partner-logos/langchain-dark.svg" imageHeight={29} href="https://docs.langchain.com/langsmith/trace-anthropic">
LangSmith agent engineering platform.
</Card>
<Card title="New Relic" image="https://platform.claude.com/docs/images/partner-logos/new-relic.svg" imageHeight={27} imageOffsetLeft={1} href="https://docs.newrelic.com/docs/ai-monitoring/opentelemetry-ai-monitoring/#anthropic">
Intelligent observability platform.
</Card>
<Card title="PostHog" image="https://platform.claude.com/docs/images/partner-logos/posthog.svg" imageDark="https://platform.claude.com/docs/images/partner-logos/posthog-dark.svg" imageHeight={29} href="https://posthog.com/docs/ai-observability/installation/anthropic?tab=Claude+Platform&utm_source=anthropic&utm_campaign=anthropic-otel">
All-in-one platform for building successful products.
</Card>
<Card title="Sentry" image="https://platform.claude.com/docs/images/partner-logos/sentry.svg" imageDark="https://platform.claude.com/docs/images/partner-logos/sentry-dark.svg" imageHeight={25} href="https://sentry.io/cookbook/trace-claude-platform-with-opentelemetry/">
Debug your broken code and misbehaving agents.
</Card>
<Card title="Splunk" image="https://platform.claude.com/docs/images/partner-logos/splunk.svg" imageDark="https://platform.claude.com/docs/images/partner-logos/splunk-dark.svg" imageHeight={27} imageOffsetLeft={1} href="https://agent-observability-docs.splunk.com/sdk-api/third-party-integrations/claude">
Observe, evaluate, and secure agents.
</Card>
</CardGroup>
## Content modes
Each destination and each SDK client has a content mode, which sets whether spans include model prompts and responses. Set it when you [add a destination](https://platform.claude.com/docs/en/manage-claude/opentelemetry/api#add-a-destination) or [configure the SDK](https://platform.claude.com/docs/en/manage-claude/opentelemetry/sdk#configure-the-sdk).
* **Metadata only** (`metadata_only` in the SDK): The default. Spans include identifiers, timing, status, token counts, and text that you choose, such as the names and descriptions of your agents and tools and the names of your MCP servers.
* **Full content** (`content` in the SDK): Most visibility. Spans include model prompts and responses, and everything in Metadata only.
With Full content, you can also see why a run failed or was slow, read full conversations, and build evals from real traces. In the [OpenTelemetry span reference](https://platform.claude.com/docs/en/api/opentelemetry/spans), attributes that hold prompts and responses are tagged <Badge>Content</Badge>.
<Info>
Your observability platform stores this content under its own access and retention settings, so check that they meet your organization's requirements.
</Info>
If your organization has a HIPAA, FERPA, or K-12 data-handling restriction with Anthropic, destinations export only metadata regardless of their content mode. SDK spans aren't affected.
With [zero data retention](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention), you can still use Full content. For Messages API requests, the API holds the exported content only in memory until it delivers it to the destination. [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) isn't eligible for zero data retention, and its data retention stays the same when you use OpenTelemetry.
### Content limits
With Full content, each span holds up to 0.75 MB of content by default. That fits a 200k-token context window of English text and stays below the 1 MB request limit of many observability platforms and proxies. If you choose a partner platform as the **Provider**, the Console sets a limit that the platform accepts.
When content is over the limit, the SDK or the API shortens it and sets `anthropic.content.truncated` to `true`. Request spans drop the system prompt and the earliest messages first, and tool spans drop blocks from the end of the result. Images and documents appear only as their type.
Change the limit in these cases:
* **Your observability platform accepts larger payloads:** Raise or remove the limit to keep long prompts and responses whole. A full 1M-token context window needs about 4 MB.
* **Your observability platform or a proxy in front of it rejects large requests:** Lower the limit.
In the SDK, set `traces.max_content_bytes` (typescript, java, php: `traces.maxContentBytes`; csharp: `Traces.MaxContentBytes`; go: `option.WithOpenTelemetryTracesMaxContentBytes()`). In the Console, set **Content mode** to **Full content** when you [add a destination](https://platform.claude.com/docs/en/manage-claude/opentelemetry/api#add-a-destination), then set **Maximum content size in MB** under **Advanced settings**.
## Example traces and how to read them
### A Messages API request
Under the API span for a request that [creates a message](https://platform.claude.com/docs/en/api/messages/create), the API adds a span for each model request and a tool span for each use of a server tool or an MCP connector tool that the API runs.
In this example, your application calls the [tool runner](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-runner), the SDK helper that runs your tools and sends their results back to Claude. Each request that the tool runner sends has a client span from the SDK and a server span from the API. The spans appear in the following order:
1. Your application starts the `answer_question` span and calls the Messages tool runner inside it (shown as the [`anthropic.messages.tool_runner`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-messages-tool-runner) span).
2. The tool runner sends the first request (shown as the first [`anthropic.messages.create`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-messages-create) client span and the spans under it). In this request, the API runs the web search tool between two model requests.
3. In the second model request, the model asks to use the custom `get_weather` tool, so the first request ends.
4. The tool runner runs `get_weather` (shown as the `anthropic.custom_tool_use get_weather` span).
5. The tool runner sends the second request with the tool result (shown as the second `anthropic.messages.create` client span and the spans under it).
6. In the second request, the model gives the final answer.
The SDK in your application emits the [`anthropic.messages.tool_runner`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-messages-tool-runner) span, the [`anthropic.custom_tool_use`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-tool-use-anthropic-mcp-tool-use-and-anthropic-custom-tool-use) span, and each request's client span. To get these spans, [set up SDK tracing](https://platform.claude.com/docs/en/manage-claude/opentelemetry/sdk).
Each request has its token usage on several of its spans. To count each token once, see [Counting tokens](https://platform.claude.com/docs/en/manage-claude/opentelemetry#count-tokens).
With [Full content](https://platform.claude.com/docs/en/manage-claude/opentelemetry#choose-a-content-mode), the `anthropic.messages.create` server span has the prompt and the response. The system prompt is in `gen_ai.system_instructions`, the request's messages in `gen_ai.input.messages`, and the response in `gen_ai.output.messages`.
For each span and its attributes, see the [OpenTelemetry span reference](https://platform.claude.com/docs/en/api/opentelemetry/spans).
### A Managed Agents session
A session has a span for each Sessions API request and a turn span for each agent turn. A turn that a request starts is a child of that request's span. A turn contains a span for each model request and each tool that the API runs, except in the [cases listed in the tool span reference](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-tool-use-anthropic-mcp-tool-use-and-anthropic-custom-tool-use). It also contains a span for each outcome evaluation.
This example follows one chat request, in which your application sends a message to a session and runs a custom tool. The trace has spans from both your application and the API, in the following order:
1. Your application receives a `POST /chat` request from a user.
2. Your application starts the SDK's session tool runner, which lists and streams the session's events (shown as the `anthropic.sessions.events.stream` and `anthropic.sessions.events.list` spans).
3. Your application sends the user's message to the session by calling `sessions.events.send`.
4. A turn starts and includes model requests, a `bash` tool use, and a turn on another thread (shown as the first `anthropic.session.turn` span and the spans under it).
5. The model asks to use the [custom tool](https://platform.claude.com/docs/en/managed-agents/tools) `list_issues`, so the turn ends with the stop reason `requires_action`.
6. The session tool runner runs `list_issues` (shown as the `anthropic.custom_tool_use list_issues` span) and sends its result by calling `sessions.events.send`.
7. A second turn starts with the tool result (shown as the last `anthropic.session.turn` span).
The SDK in your application emits the [`anthropic.custom_tool_use`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-tool-use-anthropic-mcp-tool-use-and-anthropic-custom-tool-use) span and each request's client span. To get these spans, [set up SDK tracing](https://platform.claude.com/docs/en/manage-claude/opentelemetry/sdk).
A session's spans can be in several traces, for example when you send a later request from a new root trace. With [multiagent](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration) on, a session can also have several threads. To find the spans you need, group them by an ID.
* **One thread:** Group spans by `gen_ai.conversation.id`, which holds the session thread ID. Sort them by start time to read the thread as a transcript.
* **A whole session, with all its threads:** Group spans by `anthropic.session.id`, across traces.
With [Full content](https://platform.claude.com/docs/en/manage-claude/opentelemetry#choose-a-content-mode), you can read a session's content from its spans.
* To read a turn's content, use its [turn span](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-session-turn). The system prompt is in `gen_ai.system_instructions` on a thread's first turn span, the input in `gen_ai.input.messages` (your messages and tool results, `system.message` events, and messages from other threads), and the output in `gen_ai.output.messages` (the agent's messages, tool uses, and tool results).
* To see the arguments and result of a tool use, read its [tool span](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-tool-use-anthropic-mcp-tool-use-and-anthropic-custom-tool-use). The arguments are in `gen_ai.tool.call.arguments`, and the result is in `anthropic.tool_result.content`.
For each span and its attributes, see the [OpenTelemetry span reference](https://platform.claude.com/docs/en/api/opentelemetry/spans).
## Counting tokens
To count each token once, sum the spans of only one source for each request. When a Messages API request has both an SDK span and an API span, sum its API spans. Both are named `anthropic.messages.create`, so tell them apart by kind: the SDK span is `CLIENT` and its child, the API span, is `SERVER`.
For each source, sum only the following spans, because some usage attributes repeat on more than one level of the API spans:
* **SDK spans:** Sum the [`anthropic.messages.create`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-messages-create) spans. If a request has [compactions](https://platform.claude.com/docs/en/build-with-claude/compaction), also add the span's `anthropic.usage.compaction.input_tokens` and `anthropic.usage.compaction.output_tokens`, because the `gen_ai.usage.*` attributes don't include compaction tokens. If a [fallback model](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback) served a request, its span has the usage of only the model that served the response.
* **API spans for a Messages API request:** Sum either the [`anthropic.messages.create`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-messages-create) spans or their [`anthropic.model_request`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-model-request) spans, not both. If a request has compactions, also add its [`anthropic.compaction`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-compaction) spans. Don't add the `anthropic.usage.compaction.*` attributes of the `anthropic.messages.create` span as well, because they hold the same tokens.
* **API spans for a Managed Agents session:** Sum the `anthropic.model_request` and [`anthropic.session.outcome_evaluation`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-session-outcome-evaluation) spans.
Spans can arrive more than once, for example when a delivery is retried. If your observability platform doesn't remove duplicates, count each span once by its trace ID and span ID.
`gen_ai.usage.input_tokens` already includes the tokens read from and written to the prompt cache, so don't add the cache attributes to it. For all usage attributes, see [Token usage](https://platform.claude.com/docs/en/api/opentelemetry/spans#token-usage).
<Note>
Exported spans aren't guaranteed to be a complete record of your API usage. Their delivery is [best effort](https://platform.claude.com/docs/en/manage-claude/opentelemetry/api#delivery-and-health), so a span can be lost. A caller can also leave out a request's spans by turning off the sampled flag in the request's [`traceparent` header](https://platform.claude.com/docs/en/manage-claude/opentelemetry/api#connect-api-spans-to-your-own-traces). To track each API key's usage, for example to spot a leaked key, use the [Usage API](https://platform.claude.com/docs/en/manage-claude/usage-cost-api#usage-api), which also counts the usage of requests without spans.
</Note>
manage-claude/opentelemetry/api New page · 698 lines, new page
## What you need ## 1. Add a destination ### Admin API and CLI ## 2. Choose workspaces for a destination ## 3. Check that spans arrive ## 4. Connect API spans to your own traces ## Next steps ## Delivery and health ## Limits ## Troubleshooting ### Delivery errors
A whole new page. There's nothing to diff it against, so here is what it says.
---
title: Use OpenTelemetry with the Claude API
url: https://platform.claude.com/docs/en/manage-claude/opentelemetry/api
description: Add a destination in the Claude Console to send OpenTelemetry traces of your Messages API requests and Managed Agents sessions to your observability platform.
featureMetadata:
topic:
title: OpenTelemetry
url: https://platform.claude.com/docs/en/manage-claude/opentelemetry
status: beta
zdr:
eligibility: eligible
note: Excludes [Covered Models](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements). Only for features that are themselves ZDR eligible, such as the Messages API. Claude Managed Agents isn't ZDR eligible.
supportedPlatforms:
Claude API: beta
Claude Platform on AWS: beta
rows:
- label: Works with
value: Messages API, Claude Managed Agents
details:
- After delivery, the data is held by the service that you chose, outside Anthropic, under that service's retention and access controls.
---
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](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#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](https://opentelemetry.io/docs/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
<Info>
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.
</Info>
1. In the Console, open your organization's [OpenTelemetry settings page](https://platform.claude.com/settings/telemetry-destinations) 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](https://platform.claude.com/docs/en/manage-claude/opentelemetry#choose-a-content-mode). |
| **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). |
| **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](https://platform.claude.com/docs/en/manage-claude/opentelemetry#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](https://platform.claude.com/docs/en/manage-claude/opentelemetry/api#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](https://platform.claude.com/docs/en/manage-claude/admin-api) instead of the Console. Sign in to the CLI as an admin, or use an [Admin API key](https://platform.claude.com/docs/en/manage-claude/admin-api-keys) 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](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#making-requests). There, your [IAM policy](https://platform.claude.com/docs/en/api/claude-platform-on-aws-iam-actions) determines who can manage destinations. A request can include only the workspaces of your AWS account in that Region.
<CodeGroup>
```bash CLI
# Sign in once as an admin, which opens a browser. Leave ANTHROPIC_API_KEY unset, because it overrides the profile.
ant auth login --profile admin --scope "org:admin"
ant --profile admin 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
```
```bash cURL
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/telemetry_destinations" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: telemetry-destinations-2026-08-11" \
-H "content-type: application/json" \
-d '{
"endpoint_url": "https://gateway.example.com/otlp",
"headers": {"authorization": "Bearer YOUR_OBSERVABILITY_API_KEY"},
"traces": {"content_mode": "metadata_only"},
"workspaces": {"type": "all"}
}'
```
```python Python
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)
```
```typescript TypeScript
const client = new Anthropic();
const destination = await client.beta.organization.telemetryDestinations.create({
endpoint_url: "https://gateway.example.com/otlp",
headers: { authorization: "Bearer YOUR_OBSERVABILITY_API_KEY" },
traces: { content_mode: "metadata_only" },
workspaces: { type: "all" }
});
console.log(destination.id);
```
```csharp C#
using Anthropic.Models.Beta.Organization.TelemetryDestinations;
AnthropicClient client = new();
var destination = await client.Beta.Organization.TelemetryDestinations.Create(
new()
{
EndpointUrl = "https://gateway.example.com/otlp",
Headers = new Dictionary<string, string>
{
["authorization"] = "Bearer YOUR_OBSERVABILITY_API_KEY",
},
Traces = new() { ContentMode = BetaTelemetryDestinationContentMode.MetadataOnly },
Workspaces = new BetaTelemetryDestinationWorkspacesAllParams(),
}
);
Console.WriteLine(destination.ID);
```
```go Go
client := anthropic.NewClient()
destination, err := client.Beta.Organization.TelemetryDestinations.New(
context.Background(),
anthropic.BetaOrganizationTelemetryDestinationNewParams{
EndpointURL: "https://gateway.example.com/otlp",
Headers: map[string]string{
"authorization": "Bearer YOUR_OBSERVABILITY_API_KEY",
},
Traces: anthropic.BetaTelemetryDestinationTracesParams{
ContentMode: anthropic.BetaTelemetryDestinationContentModeMetadataOnly,
},
Workspaces: anthropic.BetaTelemetryDestinationWorkspacesParamsUnion{
OfAll: &anthropic.BetaTelemetryDestinationWorkspacesAllParams{},
},
},
)
if err != nil {
log.Fatal(err)
}
fmt.Println(destination.ID)
```
```java Java
import com.anthropic.core.JsonValue;
import com.anthropic.models.beta.organization.telemetrydestinations.BetaTelemetryDestinationContentMode;
import com.anthropic.models.beta.organization.telemetrydestinations.BetaTelemetryDestinationTracesParams;
import com.anthropic.models.beta.organization.telemetrydestinations.BetaTelemetryDestinationWorkspacesAllParams;
import com.anthropic.models.beta.organization.telemetrydestinations.TelemetryDestinationCreateParams;
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
var params = TelemetryDestinationCreateParams.builder()
.endpointUrl("https://gateway.example.com/otlp")
.headers(TelemetryDestinationCreateParams.Headers.builder()
.putAdditionalProperty("authorization", JsonValue.from("Bearer YOUR_OBSERVABILITY_API_KEY"))
.build())
.traces(BetaTelemetryDestinationTracesParams.builder()
.contentMode(BetaTelemetryDestinationContentMode.METADATA_ONLY)
.build())
.workspaces(BetaTelemetryDestinationWorkspacesAllParams.builder().build())
.build();
var destination = client.beta().organization().telemetryDestinations().create(params);
IO.println(destination.id());
}
```
```php PHP
$client = new Client();
$destination = $client->beta->organization->telemetryDestinations->create(
endpointURL: 'https://gateway.example.com/otlp',
headers: ['authorization' => 'Bearer YOUR_OBSERVABILITY_API_KEY'],
traces: ['contentMode' => 'metadata_only'],
workspaces: ['type' => 'all'],
);
echo "{$destination->id}\n";
```
```ruby Ruby
client = Anthropic::Client.new
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}
)
puts destination.id
```
</CodeGroup>
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` (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.
## 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](https://platform.claude.com/docs/en/manage-claude/workspaces#how-workspaces-work) 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](https://platform.claude.com/settings/telemetry-destinations) 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](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.
The 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).
## 3. Check that spans arrive
1. 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).
2. 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.
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](https://platform.claude.com/docs/en/manage-claude/opentelemetry/api#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](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. 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.
<Tabs>
<Tab title="With the Claude SDK">
To connect the API spans, [set up SDK tracing](https://platform.claude.com/docs/en/manage-claude/opentelemetry/sdk) in your application and call the SDK from inside one of your own spans. Your span then contains the SDK span, which contains the API span. Send all of these spans to the same observability platform, so that it can show them as one trace. See the example traces of [a Messages API request](https://platform.claude.com/docs/en/manage-claude/opentelemetry#a-messages-api-request) and [a Managed Agents session](https://platform.claude.com/docs/en/manage-claude/opentelemetry#a-managed-agents-session).
The following example sends a user message to a session inside your own span:
<CodeGroup exclude="shell">
```python Python
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"}],
},
],
)
```
```typescript TypeScript
import { trace } from "@opentelemetry/api";
const tracer = trace.getTracer("my-service");
await tracer.startActiveSpan("summarize_issues", async (span) => {
try {
await client.beta.sessions.events.send(session.id, {
events: [
{
type: "user.message",
content: [{ type: "text", text: "Summarize the open issues" }]
}
]
});
} finally {
span.end();
}
});
```
```csharp C#
using System.Diagnostics;
// Add this source to your tracer provider, next to com.anthropic.sdk.csharp.
var source = new ActivitySource("MyService");
using (source.StartActivity("summarize_issues"))
{
// parameters holds a user.message event.
await client.Beta.Sessions.Events.Send(session.ID, parameters);
}
```
Cut at 300 lines. The page has the rest.
manage-claude/opentelemetry/sdk New page · 647 lines, new page
## 1. Install the SDK ## 2. Register a tracer provider ## 3. Send spans to your observability platform ## 4. Configure the SDK ## Next steps ## Tracing a stream ## Tracing a Managed Agents self-hosted sandbox ## Trace context and baggage ## Troubleshooting
A whole new page. There's nothing to diff it against, so here is what it says.
---
title: Use OpenTelemetry with the Claude SDK
url: https://platform.claude.com/docs/en/manage-claude/opentelemetry/sdk
description: Trace each request that the Claude SDK sends and each tool that its tool runner runs, and send the spans to your observability platform.
featureMetadata:
topic:
title: OpenTelemetry
url: https://platform.claude.com/docs/en/manage-claude/opentelemetry
status: beta
supportedPlatforms:
Claude API: beta
Claude Platform on AWS: beta
Amazon Bedrock: beta
Google Cloud: beta
Microsoft Foundry: beta
rows:
- label: Works with
value: Messages API, Claude Managed Agents
---
With OpenTelemetry, the Claude SDK can emit a span for each request that it sends and each tool use that the [tool runner](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-runner) runs. You can view these spans in your observability platform, nested in your own traces.
The SDK emits spans in your application. Your application's OpenTelemetry exporter sends them to your observability platform.
<Note>
During the beta, the SDK options and the span schema can change in ways that break your code, your queries, or your dashboards. For example, a new version of the SDK can rename a span, an attribute, an option, or an environment variable. Pin the SDK version in your dependencies to choose when you adopt the changes.
</Note>
## 1. Install the SDK
Install or upgrade to the latest version of the Claude SDK:
<Tabs>
<Tab title="Python">
```bash
pip install --upgrade anthropic
```
If your application doesn't use the OpenTelemetry SDK yet, install it with a console exporter, which you use in the next step to print spans:
```bash
pip install opentelemetry-sdk
```
</Tab>
<Tab title="TypeScript">
```bash
npm install @anthropic-ai/sdk@latest
```
If your application doesn't use the OpenTelemetry SDK yet, install it with a console exporter, which you use in the next step to print spans:
```bash
npm install @opentelemetry/sdk-trace-node
```
</Tab>
<Tab title="C#">
```bash
dotnet add package Anthropic
```
If your application doesn't use the OpenTelemetry SDK yet, install it with a console exporter, which you use in the next step to print spans:
```bash
dotnet add package OpenTelemetry.Exporter.Console
```
</Tab>
<Tab title="Go">
```bash
go get github.com/anthropics/anthropic-sdk-go@latest
```
If your application doesn't use the OpenTelemetry SDK yet, install it with a console exporter, which you use in the next step to print spans:
```bash
go get go.opentelemetry.io/otel/sdk go.opentelemetry.io/otel/exporters/stdout/stdouttrace
```
</Tab>
<Tab title="Java">
Add the Claude SDK to your dependencies, or update it to at least the following version if your build file already declares it:
<CodeGroup exclude="shell, python, typescript, csharp, go, php, ruby">
```kotlin Gradle
implementation("com.anthropic:anthropic-java:2.72.0")
```
```xml Maven
<dependency>
<groupId>com.anthropic</groupId>
<artifactId>anthropic-java</artifactId>
<version>2.72.0</version>
</dependency>
```
</CodeGroup>
If your application doesn't use the OpenTelemetry SDK yet, install it with a console exporter, which you use in the next step to print spans. Add `io.opentelemetry:opentelemetry-sdk` and `io.opentelemetry:opentelemetry-exporter-logging` to your build, both at the latest version on [Maven Central](https://central.sonatype.com/artifact/io.opentelemetry/opentelemetry-sdk).
</Tab>
<Tab title="PHP">
```bash
composer require "anthropic-ai/sdk" "guzzlehttp/guzzle:^7"
```
If your application doesn't use the OpenTelemetry SDK yet, install it with a console exporter, which you use in the next step to print spans:
```bash
composer require open-telemetry/sdk
```
</Tab>
<Tab title="Ruby">
If your `Gemfile` doesn't list `anthropic` yet, add the gem:
```bash
bundle add anthropic
```
If your `Gemfile` already lists `anthropic`, update the gem:
```bash
bundle update anthropic
```
If your application doesn't use the OpenTelemetry SDK yet, install it with a console exporter, which you use in the next step to print spans:
```bash
bundle add opentelemetry-sdk
```
</Tab>
</Tabs>
## 2. Register a tracer provider
A *tracer provider* is the OpenTelemetry object that creates spans and passes them to your exporter. The SDK uses the tracer provider that your application registers, so your SDK calls stay the same. Register it before the first call that you want to trace.
The following example registers a tracer provider that prints each span to the console and then makes one call. Use it to see spans before you connect an observability platform:
<CodeGroup exclude="shell">
```python Python
from anthropic import Anthropic
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
# Register a tracer provider that prints each span to the console.
provider = TracerProvider()
provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
trace.set_tracer_provider(provider)
client = Anthropic()
message = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message.content)
```
```typescript TypeScript
import Anthropic from "@anthropic-ai/sdk";
import {
ConsoleSpanExporter,
NodeTracerProvider,
SimpleSpanProcessor
} from "@opentelemetry/sdk-trace-node";
// Register a tracer provider that prints each span to the console.
const provider = new NodeTracerProvider({
spanProcessors: [new SimpleSpanProcessor(new ConsoleSpanExporter())]
});
// register() also installs the context manager, which lets the SDK spans nest under your spans.
provider.register();
const client = new Anthropic();
const message = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello, Claude" }]
});
console.log(message.content);
```
```csharp C#
using Anthropic;
using Anthropic.Models.Messages;
using OpenTelemetry;
using OpenTelemetry.Trace;
// Register a tracer provider that prints each span to the console.
// The SDK emits its spans from the source com.anthropic.sdk.csharp. Add com.anthropic.sdk.csharp*
// instead to include the SDK's clients for cloud platforms.
using var tracerProvider = Sdk.CreateTracerProviderBuilder()
.AddSource("com.anthropic.sdk.csharp")
.AddConsoleExporter()
.Build();
AnthropicClient client = new();
var message = await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages = [new() { Role = Role.User, Content = "Hello, Claude" }],
});
Console.WriteLine(message);
```
```go Go
package main
import (
"context"
"fmt"
"github.com/anthropics/anthropic-sdk-go"
"go.opentelemetry.io/otel"
"go.opentelemetry.io/otel/exporters/stdout/stdouttrace"
"go.opentelemetry.io/otel/propagation"
sdktrace "go.opentelemetry.io/otel/sdk/trace"
)
func main() {
ctx := context.Background()
// Register a tracer provider that prints each span to the console.
exporter, err := stdouttrace.New(stdouttrace.WithPrettyPrint())
if err != nil {
panic(err)
}
provider := sdktrace.NewTracerProvider(sdktrace.WithSyncer(exporter))
defer provider.Shutdown(ctx)
otel.SetTracerProvider(provider)
// OpenTelemetry for Go doesn't register a propagator by default, so
// register the W3C trace context propagator.
otel.SetTextMapPropagator(propagation.TraceContext{})
client := anthropic.NewClient()
message, err := client.Messages.New(ctx, anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Hello, Claude")),
},
})
if err != nil {
panic(err)
}
fmt.Println(message.Content)
}
```
```java Java
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
import io.opentelemetry.api.trace.propagation.W3CTraceContextPropagator;
import io.opentelemetry.context.propagation.ContextPropagators;
import io.opentelemetry.exporter.logging.LoggingSpanExporter;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.trace.SdkTracerProvider;
import io.opentelemetry.sdk.trace.export.SimpleSpanProcessor;
void main() {
// Register a tracer provider that writes each span to the log.
var tracerProvider = SdkTracerProvider.builder()
.addSpanProcessor(SimpleSpanProcessor.create(LoggingSpanExporter.create()))
.build();
OpenTelemetrySdk.builder()
.setTracerProvider(tracerProvider)
// OpenTelemetry for Java doesn't register a propagator when you build
// it in code, so register the W3C trace context propagator.
.setPropagators(ContextPropagators.create(W3CTraceContextPropagator.getInstance()))
.buildAndRegisterGlobal();
var client = AnthropicOkHttpClient.fromEnv();
var message = client.messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.addUserMessage("Hello, Claude")
.build());
IO.println(message.content());
tracerProvider.close();
}
```
```php PHP
use Anthropic\Client;
use Anthropic\Messages\Model;
use OpenTelemetry\API\Trace\Propagation\TraceContextPropagator;
use OpenTelemetry\SDK\Sdk;
use OpenTelemetry\SDK\Trace\SpanExporter\ConsoleSpanExporterFactory;
use OpenTelemetry\SDK\Trace\SpanProcessor\SimpleSpanProcessor;
Cut at 300 lines. The page has the rest.
managed-agents/quickstart Changed · +2 / -2 lines
from line 43
4343 For Linux environments, download the release binary directly.
4444
4545 ```bash
46 VERSION=1.40.0
46 VERSION=1.41.0
4747 OS=$(uname -s | tr '[:upper:]' '[:lower:]')
4848 case $(uname -m) in
4949 x86_64) ARCH=amd64 ;;
from line 94
9494
9595 <Tab title="Java">
9696 ```groovy Gradle
97 implementation("com.anthropic:anthropic-java:2.71.0")
97 implementation("com.anthropic:anthropic-java:2.72.0")
9898 ```
9999 </Tab>
100100