Claude SDKでOpenTelemetryを使用する

OpenTelemetryを使用すると、Claude SDKは送信する各リクエストと、ツールランナーが実行する各ツール使用について、「span」（スパン）を出力できます。これらのスパンは、オブザーバビリティプラットフォームで、独自のトレース内にネストされた形で確認できます。

SDKはアプリケーション内でスパンを出力します。アプリケーションのOpenTelemetryエクスポーターがそれらをオブザーバビリティプラットフォームに送信します。

1. SDKをインストールする

Claude SDKの最新バージョンをインストールするか、最新バージョンにアップグレードします：

pip install --upgrade anthropic

pip install opentelemetry-sdk

2. トレーサープロバイダーを登録する

「tracer provider」（トレーサープロバイダー）とは、スパンを作成してエクスポーターに渡すOpenTelemetryのオブジェクトです。SDKはアプリケーションが登録したトレーサープロバイダーを使用するため、SDKの呼び出しは変更不要です。トレースしたい最初の呼び出しの前に登録してください。

次の例では、各スパンをコンソールに出力するトレーサープロバイダーを登録し、1回の呼び出しを行います。オブザーバビリティプラットフォームに接続する前にスパンを確認するために使用してください：

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

# 各スパンをコンソールに出力する tracer provider を登録します。
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)

コンソールには1つのanthropic.messages.createスパンが表示されます。

3. スパンをオブザーバビリティプラットフォームに送信する

コンソールエクスポーターを、オブザーバビリティプラットフォームを指すOTLPエクスポーターに置き換えます。お使いの言語での設定については、OpenTelemetryドキュメントのPythonエクスポーター、TypeScriptエクスポーター、.NETエクスポーター、Goエクスポーター、Java SDKの設定、PHPエクスポーター、またはRubyエクスポーターを参照してください。

4. SDKを設定する

次のオプションを使用して、スパンに含める内容と送信先を決定します。オプションは、コードで設定することも、環境変数がある場合はオプション名の下に記載されている環境変数で設定することもできます。

次の例は、各オプションの使用方法を示しています：

# 特定の tracer provider を使用し、コンテンツを記録します。
# open_telemetry を設定すると、すべての ANTHROPIC_OPEN_TELEMETRY* 環境変数が上書きされます。
client = Anthropic(
    open_telemetry={"tracer_provider": provider, "traces": {"content_mode": "content"}}
)

# 1 つのクライアントでスパンを無効にします。
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スパンは、コードがストリーム全体を読み終えるか、ストリームを閉じた時点で終了します。そのため、途中で読み取りをやめるストリームは閉じてください。コンテンツモードでは、messages.stream()でストリームを読み取った場合にのみ、スパンにモデルのレスポンスが含まれます。

ストリームの読み取り中に開始したスパンは、SDKスパンの子ではなく兄弟になります。それらをリクエストとまとめるには、呼び出しと読み取りループの両方を囲む独自のスパンを開始してください。

Managed Agentsのセルフホストサンドボックスのトレース

Managed Agentsのセルフホストサンドボックスでは、サンドボックスがツールを実行するため、ツールスパンはAPIではなくSDKから出力されます。Python、TypeScript、およびGo SDKの環境ワーカーは、実行する各ツールと送信する各リクエストについてスパンを出力します。これらのスパンは、作業項目ごとに1つのanthropic.environment.workスパンの下にまとめられます。

これらのスパンを取得するには：

1. ワーカーを実行するプロセスで、手順1～4に従ってSDKトレーシングをセットアップします。
2. サンドボックスからオブザーバビリティプラットフォームまたはOpenTelemetry Collectorへのネットワークトラフィックを許可します。

ワーカーがツール結果を送信すると、そのリクエストのAPIスパンがそのSDKスパンの下にネストされます。ワーカーがClaude Platform on AWSに送信するリクエストについては、APIスパンは代わりにそれぞれ独自のトレースに含まれます。

トレースコンテキストとbaggage

SDKは各リクエストで、アプリケーションのプロパゲーターを使って、traceparentなどのヘッダーでトレースコンテキストをAPIに送信します。そのプロパゲーターがbaggageも書き込む場合、SDKはbaggageも送信します。baggageなしでトレースコンテキストを送信するには、W3Cトレースコンテキストプロパゲーターだけを登録してください。

SDKがこれらのヘッダーを送信しないようにするには（HTTPクライアントのインストルメンテーションがすでに送信している場合など）、SDKのプロパゲーションをオフにします。

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

SDKがMCPツールを呼び出している間は、SDKのツールスパンが現在のスパンです。一部のMCPクライアントライブラリは、トレースコンテキストを_metaでMCPサーバーに送信します。これを読み取るサーバーは、そのツールスパンの下にスパンを追加してトレースに加えることができます。バージョン2.0以降のPythonのmcpパッケージと、C#のModelContextProtocolパッケージがこれを行います。TypeScript、Go、Java、Ruby、PHPのMCP SDKは、自動ではこれを行いません。

トラブルシューティング

Compatibility