搭配 Claude SDK 設定 OpenTelemetry

透過 OpenTelemetry，Claude SDK 可以為其傳送的每個請求，以及 tool runner 執行的每次工具使用，發出一個「span」（跨度）。您可以在您的可觀測性平台中檢視這些 span，它們會巢狀於您自己的追蹤之中。

SDK 會在您的應用程式中發出 span。您應用程式的 OpenTelemetry「exporter」（匯出器）會將它們傳送至您的可觀測性平台。

1. 安裝 SDK

安裝或升級至最新版本的 Claude SDK：

pip install --upgrade anthropic

pip install opentelemetry-sdk

2. 註冊 tracer provider

「Tracer provider」（追蹤器提供者）是建立 span 並將其傳遞給您匯出器的 OpenTelemetry 物件。SDK 會使用您應用程式所註冊的 tracer provider，因此您的 SDK 呼叫維持不變。請在您想要追蹤的第一個呼叫之前註冊它。

以下範例註冊一個將每個 span 列印至主控台的 tracer provider，然後發出一個呼叫。在連接可觀測性平台之前，您可以使用它來查看 span：

from anthropic import Anthropic
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor

# 註冊一個 tracer provider，將每個 span 輸出至主控台。
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)

主控台會顯示一個 anthropic.messages.create span。

3. 將 span 傳送至您的可觀測性平台

將主控台匯出器替換為指向您的可觀測性平台的 OTLP 匯出器。關於您所用語言的設定方式，請參閱 OpenTelemetry 文件中的 Python 匯出器、TypeScript 匯出器、.NET 匯出器、Go 匯出器、Java SDK 設定、PHP 匯出器或 Ruby 匯出器。

4. 設定 SDK

使用以下選項來決定 span 中包含哪些內容，以及它們要傳送到何處。您可以在程式碼中設定選項，或者（如果該選項有對應的環境變數）使用其名稱下方列出的環境變數來設定。

以下範例示範如何使用每個選項：

# 使用特定的 tracer provider 並記錄內容。
# 設定 open_telemetry 會覆寫所有 ANTHROPIC_OPEN_TELEMETRY* 環境變數。
client = Anthropic(
    open_telemetry={"tracer_provider": provider, "traces": {"content_mode": "content"}}
)

# 為單一用戶端關閉 span。
quiet_client = Anthropic(open_telemetry=False)

# 使用 with_options() 設定對話 ID，此方法會傳回用戶端的副本。
# with_options() 會取代整個選項，因此請從 client.open_telemetry 開始。
message = client.with_options(
    open_telemetry={**client.open_telemetry, "conversation_id": "conv_42"}
).messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)

後續步驟

串流追蹤

串流的 anthropic.messages.create span 會在您的程式碼讀取完整個串流或關閉串流時結束，因此請關閉您提前停止讀取的串流。在內容模式下，只有當您使用 messages.stream() 讀取串流時，span 才會包含模型回應。

您在讀取串流期間啟動的 span 是 SDK span 的同層級 span，而非其子 span。若要將它們與請求歸為一組，請在呼叫與讀取迴圈外圍啟動您自己的 span。

Managed Agents 自行託管沙箱追蹤

在 Managed Agents 自行託管沙箱中，由您的沙箱執行工具，因此工具 span 來自 SDK 而非 API。Python、TypeScript 與 Go SDK 中的環境 worker 會為其執行的每個工具以及傳送的每個請求發出一個 span。它會將這些 span 歸入每個工作項目的一個 anthropic.environment.work span 之下。

若要取得這些 span：

1. 在執行 worker 的程序中，依照步驟 1 至 4 設定 SDK 追蹤。
2. 允許從沙箱到您的可觀測性平台或 OpenTelemetry Collector 的網路流量。

當 worker 傳送工具結果時，該請求的 API span 會巢狀於其 SDK span 之下。

trace context 和 baggage

SDK 會在每個請求中使用您應用程式的 propagator，透過 traceparent 等標頭將 trace context 傳送給 API。如果該 propagator 也寫入 baggage，SDK 也會傳送您的 baggage。若想傳送不含 baggage 的 trace context，請只註冊 W3C trace context propagator。

若不想讓 SDK 傳送這些標頭（例如您的 HTTP 用戶端檢測已經傳送了它們），請關閉 SDK 的傳播：

client = Anthropic(open_telemetry={"propagation": False})

SDK 呼叫 MCP 工具時，SDK 的工具 span 就是目前的 span。部分 MCP 用戶端函式庫會透過 _meta 將 trace context 傳送到 MCP 伺服器，因此讀取它的伺服器可以將自己的 span 加入您的 trace，位於該工具 span 之下。2.0 以上版本的 Python mcp 套件和 C# ModelContextProtocol 套件會這樣做。TypeScript、Go、Java、Ruby 和 PHP 的 MCP SDK 不會自行這樣做。

疑難排解

Compatibility