Claude API OpenTelemetry Tracing: A Step-by-Step Configuration Guide

Anthropic has released a Beta version of OpenTelemetry tracing for the Claude API. This means developers can now connect the trace information of model calls directly into their existing observability systems. The entire configuration process can be broken down into three steps: enabling SDK spans in code, adding a Console destination for API spans, and counting token usage only once. Below, we break down the specific steps and the design intent behind them in that order.

Why Claude API Natively Supports OpenTelemetry

In LLM applications, a single user request often involves multiple rounds of model calls, tool executions, and retrieval steps. If tracing data is scattered across proprietary formats from different vendors, troubleshooting requires switching back and forth between multiple dashboards. OpenTelemetry, as the de facto standard of the cloud-native community, unifies the semantics of traces and spans. By having the Claude API export OTel traces directly, model calls become just another ordinary node in a distributed trace.

For teams already using Jaeger, Tempo, or commercial APM tools, this change reduces the workload of building custom instrumentation. Previously, you had to manually record request latency and token counts by wrapping the SDK; now this information is produced directly by the API side, and the format conforms to the OTel specification, significantly lowering integration costs. During the Beta phase, the feature scope may still change, but the direction is clear: model calls should be observable by standard toolchains.

OpenTelemetry's core data model consists of three parts: traces, spans, and context propagation. A complete request chain is a trace, each operation node in the chain is a span, and spans form a tree structure through parent-child relationships. Context propagation is responsible for passing trace IDs and span IDs across service boundaries, enabling cross-process calls to be linked together. When the Claude API exports OTel traces, it represents each model call as a span and accepts context passed in by the caller, thereby attaching the API call to the application-side trace tree. Understanding this model helps determine whether the span hierarchy is designed reasonably: parent spans should represent business steps, and child spans should represent specific model or tool calls.

OTLP (OpenTelemetry Protocol) is the standard data transmission protocol defined by OTel, supporting both gRPC and HTTP transports. Various tracing backends (Jaeger, Tempo, commercial APM) and the OpenTelemetry Collector all implement OTLP receivers. The Console destination mentioned in the article can be seen as a debugging alternative to an OTLP exporter: it does not send network requests but prints span data to standard output. In production environments, the Collector typically receives OTLP data and then routes it to different backends according to configuration, so the application side only needs to program against OTLP and does not have to bind to a specific vendor.

Step 1: Create SDK spans in code

The starting point of configuration is to establish SDK spans in the application code. SDK spans describe logical units in your own code, such as a business process, a round of conversation orchestration, or a tool call chain. By attaching Claude API calls under these spans, you can clearly see in the tracing view "which piece of business logic triggered the model request and how long it took."

In practice, you first need to initialize the OpenTelemetry TracerProvider and exporter, and then create spans with the tracer at the location where the Claude API is called. It is recommended to align span naming with business semantics, for example using task names instead of a generic claude-call, so that problems are easier to locate in the trace list. Span attributes and events can record context such as input length and model name, making it easier to filter by dimension later.

The relationship between TracerProvider and exporter deserves further explanation. TracerProvider is the entry object of the OpenTelemetry SDK, responsible for managing tracer instances, sampling strategies, and resource attributes (such as service.name). Exporter is responsible for sending ended spans to a destination; common implementations include OTLP exporter, Console exporter, and various vendor exporters. During initialization, first create the exporter, then register it with the TracerProvider's span processor, and finally have the provider generate the tracer. Span processors fall into two categories: simple processing and batch processing. Batch mode buffers spans and exports them in batches, which is suitable for reducing network overhead in production environments. At the location where the Claude API is called, create a span via tracer.start_as_current_span() and set it as the current context; the SDK will then automatically inject the trace context into the request to the Claude API.

Step 2: Add a Console destination for API spans

SDK spans address application-side observability, while API spans come from the tracing data returned by the Claude API server. The Beta version allows configuring a Console destination for API spans, that is, outputting the tracing information generated by the server to the console. This step is particularly useful during debugging: without first setting up a complete backend collector, you can intuitively see which spans the API side reports and which fields they contain.

The Console destination is more of a verification method. After confirming that the data structure meets expectations, you typically replace the destination with a real OTLP exporter to send data to the production tracing backend. The original text's emphasis on "add a Console destination for API spans" is exactly this transitional step: see the data first, then decide where to send it.

Step 3: Count tokens only once

Duplicate counting in tracing data is an easy pitfall to fall into. If the SDK side records token usage once and the API side reports it again, the aggregated total will double. The original text's "count tokens once" points to this consistency issue: there should be only one trusted source for token statistics, avoiding the application layer and the server side each calculating separately.

During configuration, you need to clarify which side owns the token metrics. A safer approach is to let API spans carry authoritative usage data, with the application side only referencing it rather than accumulating it again. This way, the numbers match up during cost analysis and quota monitoring. The specific field names may change during the Beta phase, so refer to the official documentation when integrating, but the principle of a "single source of truth" will not change.

Why token usage is prone to duplicate counting is related to the retry and streaming response mechanisms of LLM calls. When a request is retried due to rate limiting or timeout, the failed attempt may already have consumed some tokens, while the application-side wrapper often accumulates usage each time a call returns, causing the same logical request to be counted multiple times. On the other hand, with streaming responses, usage information is usually only fully returned at the end of the stream; if the application side estimates in advance and the server side also reports the actual value, the two combined can likewise cause discrepancies. Therefore, token metrics should be based on the authoritative usage field returned in the API response. The application side should only perform fallback estimation when that value is missing, and should distinguish between "actual usage" and "estimated usage" in metric naming to avoid mixing them in cost dashboards.

A few practical recommendations for integration

Decide on a sampling strategy in advance. When model call volume is high, exporting all traces can put pressure on the backend. You can configure the sampling rate at the TracerProvider level, or perform targeted sampling for high-value requests, balancing cost and observability.

Don't make spans too granular. Splitting every HTTP request into a separate span makes the trace graph noisy. Dividing granularity by business steps is actually more efficient when troubleshooting.

Keep a fallback for Beta features. Configuration can be made into a toggle so that if fields or behavior change, you can quickly roll back to the original instrumentation approach.

Summary

The Claude API's OpenTelemetry tracing Beta brings model calls into the standard observability system. The three-step configuration corresponds to three concerns: SDK spans establish application-side context, the Console destination verifies the data shape of API spans, and single token counting ensures metric consistency. For teams already using OTel, this is a low-cost integration opportunity; for teams that have not yet established a tracing system, it is also a chance to bring LLM calls into unified observability.

One-line Summary

Claude API launches OpenTelemetry tracing Beta, integrating with the standard observability system in three steps.

Paragraph Summary

Anthropic has released a Beta version of OpenTelemetry tracing for the Claude API, allowing developers to connect model call traces into existing observability systems. Configuration is divided into three steps: creating SDK spans in code to establish application-side context, adding a Console destination for API spans to verify the shape of server-side tracing data, and ensuring token usage is counted only once to avoid duplicate counting. The article explains the value of native OTel support—unifying trace semantics and reducing the cost of custom instrumentation—and offers practical recommendations on sampling strategies, span granularity, and Beta feature toggles. For teams already using OTel, it is a low-cost integration opportunity; for teams that have not yet established a tracing system, it is an opportunity to bring LLM calls into unified observability.