Claude SDKでOpenTelemetryを設定する

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

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

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を設定する

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

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

# 特定のトレーサープロバイダーを使用し、コンテンツを記録します。
# 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スパンの下にネストされます。

トレースコンテキストと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