--- title: 搭配 Claude SDK 使用 OpenTelemetry url: https://platform.claude.com/docs/zh-TW/manage-claude/opentelemetry/sdk description: 追蹤 Claude SDK 傳送的每個請求以及其工具執行器執行的每個工具，並將 span 傳送至您的可觀測性平台。 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: 適用於 value: Messages API, Claude Managed Agents --- 透過 OpenTelemetry，Claude SDK 可以為其發送的每個請求，以及 [tool runner](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/tool-runner)（工具執行器）執行的每次工具使用，各發出一個「*Span*」（跨度）。您可以在您的可觀測性平台中檢視這些 span，它們會巢狀於您自己的追蹤中。 SDK 會在您的應用程式中發出 span。您應用程式的 OpenTelemetry 匯出器會將它們傳送到您的可觀測性平台。 在測試期間，SDK 選項與 span 結構描述可能會以破壞您的程式碼、查詢或儀表板的方式變更。例如，新版 SDK 可能會重新命名某個 span、屬性、選項或環境變數。請在相依套件中固定 SDK 版本，以自行選擇何時採用這些變更。 ## 1. 安裝 SDK 安裝或升級至最新版本的 Claude SDK： ```bash pip install --upgrade anthropic ``` 如果您的應用程式尚未使用 OpenTelemetry SDK，請安裝它並搭配一個主控台匯出器，您將在下一步中使用該匯出器來列印 span： ```bash pip install opentelemetry-sdk ``` ```bash npm install @anthropic-ai/sdk@latest ``` 如果您的應用程式尚未使用 OpenTelemetry SDK，請連同主控台匯出器一起安裝，您將在下一步使用它來列印 span： ```bash npm install @opentelemetry/sdk-trace-node ``` ```bash dotnet add package Anthropic ``` 如果您的應用程式尚未使用 OpenTelemetry SDK，請連同主控台匯出器一起安裝，您將在下一步使用它來列印 span： ```bash dotnet add package OpenTelemetry.Exporter.Console ``` ```bash go get github.com/anthropics/anthropic-sdk-go@latest ``` 如果您的應用程式尚未使用 OpenTelemetry SDK，請連同主控台匯出器一起安裝，您將在下一步使用它來列印 span： ```bash go get go.opentelemetry.io/otel/sdk go.opentelemetry.io/otel/exporters/stdout/stdouttrace ``` 將 Claude SDK 加入您的相依套件；如果您的建置檔已宣告它，請將其更新至至少以下版本： ```kotlin Gradle implementation("com.anthropic:anthropic-java:2.72.0") ``` ```xml Maven com.anthropic anthropic-java 2.72.0 ``` 如果您的應用程式尚未使用 OpenTelemetry SDK，請連同主控台匯出器一起安裝，您將在下一步使用它來列印 span。將 `io.opentelemetry:opentelemetry-sdk` 與 `io.opentelemetry:opentelemetry-exporter-logging` 加入您的建置，兩者皆使用 [Maven Central](https://central.sonatype.com/artifact/io.opentelemetry/opentelemetry-sdk) 上的最新版本。 ```bash composer require "anthropic-ai/sdk" "guzzlehttp/guzzle:^7" ``` 如果您的應用程式尚未使用 OpenTelemetry SDK，請連同主控台匯出器一起安裝，您將在下一步使用它來列印 span： ```bash composer require open-telemetry/sdk ``` 如果您的 `Gemfile` 尚未列出 `anthropic`，請加入該 gem： ```bash bundle add anthropic ``` 如果您的 `Gemfile` 已列出 `anthropic`，請更新該 gem： ```bash bundle update anthropic ``` 如果您的應用程式尚未使用 OpenTelemetry SDK，請連同主控台匯出器一起安裝，您將在下一步使用它來列印 span： ```bash bundle add opentelemetry-sdk ``` ## 2. 註冊 tracer provider 「*Tracer provider*」（追蹤器提供者）是建立 span 並將其傳遞給您匯出器的 OpenTelemetry 物件。SDK 會使用您應用程式所註冊的 tracer provider，因此您的 SDK 呼叫維持不變。請在您想要追蹤的第一個呼叫之前註冊它。 以下範例註冊一個將每個 span 列印到主控台的 tracer provider，然後發出一次呼叫。在連接可觀測性平台之前，您可以用它來查看 span： ```python Python 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) ``` ```typescript TypeScript import Anthropic from "@anthropic-ai/sdk"; import { ConsoleSpanExporter, NodeTracerProvider, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-node"; // 註冊一個 tracer provider，將每個 span 輸出至主控台。 const provider = new NodeTracerProvider({ spanProcessors: [new SimpleSpanProcessor(new ConsoleSpanExporter())] }); // register() 也會安裝 context manager，讓 SDK 的 span 能巢狀於您的 span 之下。 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; // 註冊一個 tracer provider，將每個 span 輸出至主控台。 // SDK 會從來源 com.anthropic.sdk.csharp 發出其 span。若改為加入 com.anthropic.sdk.csharp*， // 即可一併納入 SDK 針對雲端平台的用戶端。 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() // 註冊一個會將每個 span 輸出至主控台的 tracer provider。 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 預設不會註冊 propagator，因此 // 請註冊 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() { // 註冊一個 tracer provider，將每個 span 寫入日誌。 var tracerProvider = SdkTracerProvider.builder() .addSpanProcessor(SimpleSpanProcessor.create(LoggingSpanExporter.create())) .build(); OpenTelemetrySdk.builder() .setTracerProvider(tracerProvider) // 以程式碼建構 OpenTelemetry for Java 時，它不會註冊 propagator， // 因此請註冊 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; use OpenTelemetry\SDK\Trace\TracerProvider; // 註冊一個 tracer provider，將每個 span 輸出至主控台。 $tracerProvider = new TracerProvider( new SimpleSpanProcessor((new ConsoleSpanExporterFactory())->create()), ); Sdk::builder() ->setTracerProvider($tracerProvider) // 以程式碼建構 OpenTelemetry for PHP 時，它不會註冊 propagator， // 因此請註冊 W3C trace context propagator。 ->setPropagator(TraceContextPropagator::getInstance()) ->buildAndRegisterGlobal(); $client = new Client(); $message = $client->messages->create( maxTokens: 1024, messages: [['role' => 'user', 'content' => 'Hello, Claude']], model: Model::CLAUDE_OPUS_5_5, ); echo $message; ``` ```ruby Ruby require "anthropic" require "opentelemetry/sdk" # 註冊一個 tracer provider，將每個 span 輸出至主控台。 OpenTelemetry::SDK.configure do |config| config.add_span_processor( OpenTelemetry::SDK::Trace::Export::SimpleSpanProcessor.new( OpenTelemetry::SDK::Trace::Export::ConsoleSpanExporter.new ) ) end client = Anthropic::Client.new message = client.messages.create( model: Anthropic::Model::CLAUDE_OPUS_5_5, max_tokens: 1024, messages: [{role: "user", content: "Hello, Claude"}] ) puts(message.content) ``` 主控台會顯示一個 [`anthropic.messages.create`](https://platform.claude.com/docs/zh-TW/api/opentelemetry/spans#anthropic-messages-create) span。 ## 3. 將 span 傳送到您的可觀測性平台 將主控台匯出器替換為指向您可觀測性平台的 OTLP 匯出器。關於您所用語言的設定方式，請參閱 OpenTelemetry 文件中的 [Python 匯出器](https://opentelemetry.io/docs/languages/python/exporters/)、[TypeScript 匯出器](https://opentelemetry.io/docs/languages/js/exporters/)、[.NET 匯出器](https://opentelemetry.io/docs/languages/dotnet/exporters/)、[Go 匯出器](https://opentelemetry.io/docs/languages/go/exporters/)、[Java SDK 設定](https://opentelemetry.io/docs/languages/java/configuration/)、[PHP 匯出器](https://opentelemetry.io/docs/languages/php/exporters/)、或 [Ruby 匯出器](https://opentelemetry.io/docs/languages/ruby/exporters/)。 ## 4. 設定 SDK 使用以下選項來決定 span 中包含哪些內容以及它們傳送到何處。您可以在程式碼中設定選項，或使用其名稱下方列出的環境變數（如果有的話）來設定。 如果您將 `open_telemetry` (typescript, java, php: `openTelemetry`; csharp: `OpenTelemetry`; go: `option.With…()`) 傳遞給用戶端，該值會整體優先於該選項的環境變數，包括巢狀鍵。您省略的任何巢狀鍵都會採用表格中的預設值，即使已設定其環境變數也是如此。 | 選項 | 用途 | 預設值 | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `traces.content_mode` (typescript, java, php: `traces.contentMode`; csharp: `Traces.ContentMode`; go: `option.WithOpenTelemetryTracesContentMode()`)
`ANTHROPIC_OPEN_TELEMETRY_TRACES_CONTENT_MODE=content` | 在 span 中包含提示與回應。請參閱[內容模式](https://platform.claude.com/docs/zh-TW/manage-claude/opentelemetry#choose-a-content-mode)。 | `metadata_only` | | `traces.max_content_bytes` (typescript, java, php: `traces.maxContentBytes`; csharp: `Traces.MaxContentBytes`; go: `option.WithOpenTelemetryTracesMaxContentBytes()`)
`ANTHROPIC_OPEN_TELEMETRY_TRACES_MAX_CONTENT_BYTES` | 變更每個 span 的內容限制。請參閱[內容限制](https://platform.claude.com/docs/zh-TW/manage-claude/opentelemetry#content-limits)。 | 0.75 MB | | `conversation_id` (typescript, java, php: `conversationId`; csharp: `ConversationId`; go: `option.WithOpenTelemetryConversationID()`) | 將多個呼叫連結成一段對話。SDK 會將 ID 寫入 `gen_ai.conversation.id`。此 ID 在兩種內容模式下都會被匯出，因此請勿在其中放入個人資料或機密資訊。 | 無 | | `tracer_provider` (typescript, java, php: `tracerProvider`; csharp: `AddSource("com.anthropic.sdk.csharp")`; go: `option.WithTracerProvider()`) | 選擇接收 SDK span 的 tracer provider。 | 您在[註冊 tracer provider](https://platform.claude.com/docs/zh-TW/manage-claude/opentelemetry/sdk#register-a-tracer-provider) 中設定的 tracer provider | | `propagation` (go: `option.WithOpenTelemetryPropagation()`)
`ANTHROPIC_OPEN_TELEMETRY_PROPAGATION=false` | 停止隨請求傳送 trace context 和 baggage 標頭，例如當您的 HTTP 用戶端檢測已經傳送它們時。SDK 仍會產生 span。適用於 Python、TypeScript、Go、Java、Ruby 和 PHP SDK。 | 開啟 | | `open_telemetry` (typescript, java, php: `openTelemetry`; csharp: `OpenTelemetry`; go: `option.WithoutOpenTelemetry()`)
`ANTHROPIC_OPEN_TELEMETRY=false` | 為單一用戶端關閉 span，例如當另一個函式庫已在追蹤 SDK 時。 | 開啟 | 以下範例示範如何使用每個選項： ```python Python # 使用特定的 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"}], ) ``` ```typescript TypeScript // 使用特定的 tracer provider 並記錄內容。 // 設定 openTelemetry 會覆寫所有 ANTHROPIC_OPEN_TELEMETRY* 環境變數。 const client = new Anthropic({ openTelemetry: { tracerProvider: provider, traces: { contentMode: "content" } } }); // 為單一用戶端關閉 span。 const quietClient = new Anthropic({ openTelemetry: false }); // 在單次呼叫的請求選項中設定對話 ID。 const message = await client.messages.create( { model: "claude-opus-5-5", max_tokens: 1024, messages: [{ role: "user", content: "Hello, Claude" }] }, { openTelemetry: { conversationId: "conv_42" } } ); ``` ```csharp C# // 使用特定的 tracer provider：請將 SDK 的來源加入該 tracer provider。 using var tracerProvider = Sdk.CreateTracerProviderBuilder() .AddSource("com.anthropic.sdk.csharp") .AddConsoleExporter() .Build(); // 記錄內容。 // 設定 OpenTelemetry 會覆寫所有 ANTHROPIC_OPEN_TELEMETRY* 環境變數。 AnthropicClient client = new() { OpenTelemetry = new() { Traces = new() { ContentMode = OpenTelemetryContentMode.Content } }, }; // 為單一用戶端關閉 span。 AnthropicClient quietClient = new() { OpenTelemetry = false }; // 為同一對話中的呼叫設定對話 ID。 var conversation = client.WithOptions(options => options with { OpenTelemetryRequest = new() { ConversationId = "conv_42" }, }); var message = await conversation.Messages.Create(new MessageCreateParams { Model = Model.ClaudeOpus5_5, MaxTokens = 1024, Messages = [new() { Role = Role.User, Content = "Hello, Claude" }], }); ``` ```go Go // 使用特定的 tracer provider 並記錄內容。 client := anthropic.NewClient( option.WithTracerProvider(provider), option.WithOpenTelemetryTracesContentMode(option.OpenTelemetryContentModeContent), ) // 為單一用戶端關閉 span。 quietClient := anthropic.NewClient(option.WithoutOpenTelemetry()) // 在單次呼叫的請求選項中設定對話 ID。 message, err := client.Messages.New(ctx, anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus5_5, MaxTokens: 1024, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("Hello, Claude")), }, }, option.WithOpenTelemetryConversationID("conv_42")) ``` ```java Java // 只有在您使用 fromEnv() 建構用戶端時，用戶端才會讀取環境變數。 // 系統屬性 anthropic.openTelemetry、anthropic.openTelemetryTracesContentMode // 及 anthropic.openTelemetryTracesMaxContentBytes 的優先順序高於環境 // 變數。 // 使用特定的 tracer provider 並記錄內容。請從 // OpenTelemetryOptions.fromEnv() 開始，以保留 fromEnv() 讀取的選項。 var envOptions = OpenTelemetryOptions.fromEnv(); var client = AnthropicOkHttpClient.builder() .fromEnv() .openTelemetry(envOptions.toBuilder() .tracerProvider(tracerProvider) .traces(envOptions.traces().toBuilder() .contentMode(OpenTelemetryContentMode.CONTENT) .build()) .build()) .build(); // 為單一用戶端關閉 span。 var quietClient = AnthropicOkHttpClient.builder().fromEnv().openTelemetry(false).build(); // 在單次呼叫的請求選項中設定對話 ID。 var params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_5_5) .maxTokens(1024) .addUserMessage("Hello, Claude") .build(); var message = client.messages().create(params, RequestOptions.builder() .openTelemetry(OpenTelemetryRequestOptions.builder().conversationId("conv_42").build()) .build()); ``` ```php PHP // 使用特定的 tracer provider 並記錄內容。 // 設定 openTelemetry 會覆寫所有 ANTHROPIC_OPEN_TELEMETRY* 環境變數。 $client = new Client( openTelemetry: ['tracerProvider' => $tracerProvider, 'traces' => ['contentMode' => 'content']], ); // 為單一用戶端關閉 span。 $quietClient = new Client(openTelemetry: false); // 在單次呼叫的請求選項中設定對話 ID。 $message = $client->messages->create( maxTokens: 1024, messages: [['role' => 'user', 'content' => 'Hello, Claude']], model: Model::CLAUDE_OPUS_5_5, requestOptions: ['openTelemetry' => ['conversationId' => 'conv_42']], ); ``` ```ruby Ruby # 使用特定的 tracer provider 並記錄內容。 # 設定 open_telemetry 會覆寫所有 ANTHROPIC_OPEN_TELEMETRY* 環境變數。 client = Anthropic::Client.new(open_telemetry: {tracer_provider: provider, traces: {content_mode: :content}}) # 為單一用戶端關閉 span。 quiet_client = Anthropic::Client.new(open_telemetry: false) # 在單次呼叫的請求選項中設定對話 ID。 message = client.messages.create( model: Anthropic::Model::CLAUDE_OPUS_5_5, max_tokens: 1024, messages: [{role: "user", content: "Hello, Claude"}], request_options: {open_telemetry: {conversation_id: "conv_42"}} ) ``` ## 後續步驟 取得 Claude API 的可觀測性。 追蹤一個請求從您的用戶端進入 Claude API 的過程。 ## 串流追蹤 串流的 `anthropic.messages.create` span 會在您的程式碼讀完整個串流或關閉串流時結束，因此若您提前停止讀取串流，請將其關閉。在內容模式下，只有當您使用 `messages.stream()` (go: `Messages.NewStreaming()`; java: `messages().createStreaming()`; csharp: `Messages.CreateStreaming()`; php: `messages->createStream()`) 讀取串流時，span 才會包含模型回應。 您在讀取串流期間啟動的 span 是 SDK span 的同層級 span，而非其子 span。若要將它們與請求歸為一組，請在呼叫與讀取迴圈外圍啟動您自己的 span。 ## Managed Agents 自行託管沙箱追蹤 在 Managed Agents [自行託管沙箱](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes)中，工具由您的沙箱執行，因此工具 span 來自 SDK 而非 API。Python、TypeScript 和 Go SDK 中的環境 worker 會為其執行的每個工具以及其傳送的每個請求發出一個 span，並將它們歸入每個工作項目各一個的 [`anthropic.environment.work`](https://platform.claude.com/docs/zh-TW/api/opentelemetry/spans#anthropic-environment-work) span 之下。 若要取得這些 span： 1. 在執行 worker 的程序中，依照步驟 1 至 4 [設定 SDK 追蹤](https://platform.claude.com/docs/zh-TW/manage-claude/opentelemetry/sdk#install-the-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 的傳播： ```python Python client = Anthropic(open_telemetry={"propagation": False}) ``` ```typescript TypeScript const client = new Anthropic({ openTelemetry: { propagation: false } }); ``` 如果您使用 `@opentelemetry/auto-instrumentations-node` 中包含的 `@opentelemetry/instrumentation-undici` ，請設定 `propagation: false` 。否則， [該套件的一個錯誤](https://github.com/open-telemetry/opentelemetry-js-contrib/issues/3711) 會為每個請求加上第二個 `traceparent` 標頭，導致 trace context 無效。 ```csharp C# // SDK 使用 .NET 的 DistributedContextPropagator 寫入這些標頭。 // 無輸出 propagator 會讓處理程序中的每個 HttpClient 都不再傳送這些標頭。 // 請在建立任何用戶端之前設定。 DistributedContextPropagator.Current = DistributedContextPropagator.CreateNoOutputPropagator(); AnthropicClient client = new(); ``` ```go Go client := anthropic.NewClient(option.WithOpenTelemetryPropagation(false)) ``` ```java Java var envOptions = OpenTelemetryOptions.fromEnv(); var client = AnthropicOkHttpClient.builder() .fromEnv() .openTelemetry(envOptions.toBuilder().propagation(false).build()) .build(); ``` ```php PHP $client = new Client(openTelemetry: ['propagation' => false]); ``` ```ruby Ruby client = Anthropic::Client.new(open_telemetry: {propagation: false}) ``` SDK 呼叫 [MCP 工具](https://platform.claude.com/docs/zh-TW/agents-and-tools/mcp-connector#client-side-mcp-helpers)時，SDK 的工具 span 就是目前的 span。部分 MCP 用戶端函式庫會透過 `_meta` 將 trace context 傳送到 MCP 伺服器，因此讀取它的伺服器可以將自己的 span 加入您的 trace，位於該工具 span 之下。2.0 以上版本的 Python `mcp` 套件和 C# `ModelContextProtocol` 套件會這樣做。TypeScript、Go、Java、Ruby 和 PHP 的 MCP SDK 不會自行這樣做。 ## 疑難排解 | 問題 | 檢查項目 | | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 沒有來自 SDK 的 span | 在第一次呼叫之前註冊 tracer provider。請確認您已依照[安裝 SDK](https://platform.claude.com/docs/zh-TW/manage-claude/opentelemetry/sdk#install-the-sdk) 安裝 SDK，且 `ANTHROPIC_OPEN_TELEMETRY` 不是 `false`。 | | Java SDK 未將 span 傳送至已註冊的 tracer provider，或未將 trace context 傳送至 API | 另一個相依套件將 `opentelemetry-api` 設定為低於 1.57.0 的版本。請將 `opentelemetry-api` 升級至 1.57.0 或更新版本。 | | SDK span 未巢狀於您的 span 之下，或您的工具所建立的 span 未巢狀於工具 span 之下 | 請從您自己的某個 span 內部呼叫 SDK，如[將 API span 連接到您自己的追蹤中的範例](https://platform.claude.com/docs/zh-TW/manage-claude/opentelemetry/api#connect-api-spans-to-your-own-traces)所示。在 Go 中，請從工具執行器傳遞給工具的 `ctx` 啟動您的工具所建立的 span。 | | 來自 SDK 的請求沒有 `traceparent` 標頭 | 向 OpenTelemetry 註冊 W3C trace context propagator。SDK 會使用您應用程式的 propagator 寫入標頭。 | | 串流的 SDK span 未結束或沒有回應 | 請參閱[串流追蹤](https://platform.claude.com/docs/zh-TW/manage-claude/opentelemetry/sdk#trace-a-stream)。 | | 每個請求都出現兩次 | 請求的 SDK span 和 API span 名稱相同。請使用 span 種類或 `service.name` 來區分它們。如果另一個函式庫也在追蹤 SDK，請關閉其中一個。 |