搭配 Claude SDK 使用 OpenTelemetry

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

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

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，並將它們歸入每個工作項目各一個的 anthropic.environment.work span 之下。

若要取得這些 span：

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

當 worker 傳送工具結果時，該請求的 API span 會巢狀位於其 SDK span 之下。對於工作程序傳送至 Claude Platform on AWS 的請求，API 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