Claude Platform OpenTelemetry

The 14 October release notes announce OTel export in beta for Messages API requests and Managed Agents sessions. SDK spans are emitted by your application; API spans are emitted by the service. A trace groups related work; each span describes one timed step.

• SDK only: see SDK requests and tools executed by its tool runner. Register a tracer provider in application code. Console administrator access is not required for instrumentation, but you still need permission to use the application, API credentials and your observability backend.
• API only: see individual model runs, Managed Agents turns and API-executed tools, even when the caller is not the Claude SDK. An administrator configures a Console destination.
• Combined: connect the client request to the service's work for diagnosis. Do not count the same usage at both layers. These capabilities and cloud boundaries are listed in the official coverage matrix.

SDK tracing supports the documented cloud platforms. API tracing supports Claude Platform and Claude Platform on AWS; do not assume the same API export on Bedrock, Google Cloud or Foundry. On Claude Platform on AWS, API spans appear in separate traces rather than joined SDK/API traces. Platform support.

Different products: Claude Code CLI monitoring configures the coding client, not a Platform destination. Agent SDK observability and Cowork activity monitoring have their own documentation. Do not paste a CLI monitoring environment block into an API tracing tutorial and call the setup complete.

API path: an administrator-owned destination

The API setup prerequisites are a Console organization admin, endpoint credentials and an HTTPS port 443 OTLP/HTTP endpoint accepting protobuf. A developer can view destinations but cannot add or change them. A default local collector on port 4318 is not a directly eligible API destination.

When authorized to connect a backend, open the Console's OpenTelemetry settings and add a destination. Choose the intended workspace scope and Metadata only. For a custom base endpoint, omit /v1/traces because the API appends it; an explicit traces endpoint is a separate advanced field and must use the same host. Put credentials in the configured header values, never in a public example or URL. Save, then use Test and look for an anthropic.test span in the backend. A saved destination is not proof of delivery. Destination fields and test.

These are instructions for a future authorized setup. No destination or backend was connected for this guide.

SDK path: register before the first request

Install a compatible Claude SDK and OpenTelemetry SDK in your application, pin the versions you validate, and register the tracer provider before the first request you want traced. Start with a console exporter to distinguish instrumentation from remote delivery. SDK setup.

Configuration example — TypeScript, unexecuted, no model request:

import Anthropic from "@anthropic-ai/sdk";
import {
  ConsoleSpanExporter,
  NodeTracerProvider,
  SimpleSpanProcessor
} from "@opentelemetry/sdk-trace-node";

const provider = new NodeTracerProvider({
  spanProcessors: [
    new SimpleSpanProcessor(new ConsoleSpanExporter())
  ]
});
provider.register();

const client = new Anthropic({
  openTelemetry: {
    tracerProvider: provider,
    traces: { contentMode: "metadata_only" }
  }
});
// This only configures a client. It does not send a request.
// Keep credentials in your application's secret mechanism.

This adapts the documented provider and client options while keeping metadata-only mode explicit. It is not a complete application and does not demonstrate that spans were emitted. Request authentication remains your application's responsibility. Only after that application has approval should you run a small synthetic request and inspect its spans. See SDK configuration options.

Synthetic illustration — no captured prompt, token measurement or customer data:

application operation [your span]
  anthropic.messages.create [CLIENT: SDK]
    anthropic.messages.create [SERVER: API]
      anthropic.model_request [API]
      anthropic.tool_use [API server tool]
      anthropic.model_request [API]
  anthropic.custom_tool_use [SDK client tool]
  anthropic.messages.create [CLIENT: next request]
    anthropic.messages.create [SERVER: next request]

The tool runner can make another request after a client tool returns; not every tool runs on the server. A Managed Agents turn can be a child of the request that starts it, with model/tool spans below it. A whole session can span several traces. Use gen_ai.conversation.id for a thread and anthropic.session.id for the session across traces. See the official example traces and span reference.

For a combined path, preserve trace context through the request. Check the documented traceparent handling, sampling and platform support if client/server spans are disconnected; a name match alone does not establish parentage. AWS API spans are intentionally separate. Connecting API spans.

Use timing, status and error attributes to locate a slow or failing step. They explain the recorded operation; they do not prove that an end user received a correct answer.

The default Metadata only mode omits prompt/response content, but metadata can still contain custom tool names and descriptions, agent names and MCP server names. Full content can export prompts, responses and tool content. Review those fields before sending traces outside your application. The chosen backend controls access and retention after delivery; Anthropic settings do not set the destination's retention policy. Content modes.

Keep metadata-only separately on the API destination and each SDK client. Do not enable full content merely because a troubleshooting screen is missing a prompt. Some organization restrictions force API metadata-only; they do not automatically constrain SDK spans. Full-content truncation and anthropic.content.truncated also mean a span is not a lossless record. Privacy and content limits.

One usage total per request

Use the official token-counting rules:

• When both SDK and API spans exist, choose the API layer. anthropic.messages.create appears at both layers: distinguish CLIENT from SERVER.
• For a Messages API request, sum either its API request span or its model-request spans, not both. Add the separate compaction spans when present; do not also add the request's repeated compaction totals.
• With SDK spans only, use the Messages create spans and their separate compaction usage attributes when applicable.
• For Managed Agents API traces, use model-request and outcome-evaluation spans. Do not sum the enclosing turn as another copy of the same usage.
• Input-token usage already includes cached input; don't add cache-read/write token attributes again.

Trace delivery is best effort, and sampling can omit spans. Use the official usage reporting path for complete API-key usage accounting; a trace sum is not an invoice or proof of zero usage when no span arrives. Accounting limitations.

• No SDK spans: check SDK version, tracer-provider registration before the call, sampling and exporter shutdown/flush behavior. A configured client with no request emits no request span. Follow SDK setup.
• No API spans: check destination enabled state and workspace coverage. After coverage changes, allow the documented delivery delay; inspect Console delivery health. A successful test span proves the destination path, not that the application request was traced.
• 401/403 delivery: verify the destination authentication header in the secret/configuration interface.
• 404 delivery: check the endpoint path, especially duplicate /v1/traces.
• DNS/TLS/timeout: verify reachability, hostname/certificate and receiver protocol; do not “fix” it by switching on full content. The API troubleshooting table distinguishes these errors.
• Duplicate costs: compare span kind and selected aggregation level before changing the model or blaming billing.
• Beta upgrade breaks a dashboard: compare SDK lockfile versions and span/attribute names. The beta can introduce breaking option or schema changes. SDK beta warning.

For rollback, disable the affected destination or revert the SDK instrumentation change through your usual review process. Data already delivered remains subject to the backend's retention and deletion controls. Record which layer was disabled and verify that the other layer is not still exporting.

This guide cannot establish endpoint acceptance, latency overhead, complete trace delivery or permission availability in your account. Those require a separately authorized integration test. For connected-tool boundaries, continue with the MCP server security checklist.