Claude APIでOpenTelemetryを設定する
Claude Consoleで送信先を追加して、Messages APIリクエストとManaged AgentsセッションのOpenTelemetryトレースをオブザーバビリティプラットフォームに送信します。
OpenTelemetryを使用すると、Claude APIは実行する各モデルリクエストと各ツール使用について「span」(スパン)を出力できます。コードを変更することなく、これらのスパンをオブザーバビリティプラットフォームで確認できます。
APIは、Messages APIリクエストとManaged Agentsセッションのスパンを出力します。それらを受け取るには、Claude Consoleで「destination」(宛先)を追加します。宛先は、オブザーバビリティプラットフォームのOTLPエンドポイントと、そのプラットフォームでの認証方法をAPIに伝えます。
必要なもの
- Claude Console組織における管理者ロール。宛先の追加と変更に必要です。開発者ロールでは、宛先を表示できます。組織がClaude Platform on AWSを利用している場合は、サインインの説明に従って、AWS Console経由でConsoleにサインインしてください。
- ポート443のHTTPS URLでprotobufエンコーディングを受け付けるOTLP/HTTPエンドポイント。独自のOpenTelemetry Collectorを実行している場合、そのOTLP/HTTPレシーバーはデフォルトでポート4318をリッスンします。ポート443でHTTPSを受け付けるようにレシーバーを設定するか、Collectorの前にロードバランサーまたはリバースプロキシを配置してください。
- APIキーなどのエンドポイントの認証情報。
1. 宛先を追加する
-
Consoleで、組織のOpenTelemetry設定ページを開き、送信先を追加をクリックします。
-
宛先を設定します:
フィールド 入力内容 プロバイダー お使いのオブザーバビリティプラットフォーム。一覧にない場合はカスタム。一覧にあるプラットフォームを選択した場合、ConsoleではOTLP エンドポイント URL、リクエストヘッダー、OTLP トレースエンドポイント URLの代わりに、APIキーなどのプラットフォームの詳細の入力を求められます。 名前 任意。たとえば「Acmeのオブザーバビリティプラットフォーム」。 OTLP エンドポイント URL オブザーバビリティプラットフォームのOTLP/HTTPエンドポイントのベースHTTPS URL。IPアドレスではなくホスト名を使用します。 https://gateway.example.com/otlpのようにパスプレフィックスを含めることができます。/v1/tracesはAPIが追加するため、追加しないでください。OTLP トレースエンドポイント URLを設定した場合、APIは代わりにそのURLを使用します。リクエストヘッダー APIが各リクエストとともに送信するヘッダー。たとえばオブザーバビリティプラットフォームのAPIキーヘッダーです。認証情報はヘッダー値にのみ入力してください。保存後、Consoleは値を再表示しません。 コンテンツモード メタデータのみまたはコンテンツ全体。コンテンツモードの違いを参照してください。 ワークスペース 宛先がスパンを受け取るワークスペース:すべて、選択したもののみ、または次を除くすべて。宛先のワークスペースを選択するを参照してください。 OTLP トレースエンドポイント URL 任意。詳細設定の下にあります。オブザーバビリティプラットフォームのトレースエンドポイントの完全なURL。たとえば https://gateway.example.com/custom/traces。プラットフォームが、OTLPエンドポイントURLに/v1/tracesを付けたもの以外のURLでトレースを受け取る場合に設定します。OTLPエンドポイントURLと同じホストである必要があります。最大コンテンツサイズ(MB) 任意。コンテンツモードがコンテンツ全体の場合、詳細設定の下にあります。APIが各スパンで送信するコンテンツの最大量。選択したプロバイダーに応じて、Consoleが自動的に入力します。オブザーバビリティプラットフォームが受け付けるサイズに合わせて変更してください。APIが許容する最大量まで送信するには、空のままにしてください。コンテンツの制限を参照してください。 -
送信先を追加をクリックして保存します。
-
宛先のその他の操作メニューでテストをクリックします。テストスパンがコレクターに配信されたことを示すメッセージ、または配信がどのように失敗したかを示すメッセージが表示されます(配信エラーを参照)。
-
anthropic.testスパンがオブザーバビリティプラットフォームに届いたことを確認します。
Admin APIとCLI
Consoleの代わりにAdmin APIを通じて宛先を追加することもできます。管理者としてCLIにサインインするか、ANTHROPIC_API_KEYに設定したAdmin APIキーやサービスアカウントキーなど、その他のAdmin API認証情報を使用してください。Claude Platform on AWSでは、代わりにhttps://aws-external-anthropic.{region}.api.awsにリクエストを送信し、リクエストの送信と同様にAWS認証情報で署名してください。その場合、宛先を管理できるユーザーはIAMポリシーによって決まります。リクエストに含めることができるのは、そのリージョンにあるお客様のAWSアカウントのワークスペースのみです。
client = anthropic.Anthropic()
destination = client.beta.organization.telemetry_destinations.create(
endpoint_url="https://gateway.example.com/otlp",
headers={"authorization": "Bearer YOUR_OBSERVABILITY_API_KEY"},
traces={"content_mode": "metadata_only"},
workspaces={"type": "all"},
)
print(destination.id)作成リクエストはプロバイダーを除くConsoleの設定を受け取るため、オブザーバビリティプラットフォームのエンドポイントURLとヘッダーはご自身で入力してください。オブザーバビリティプラットフォームが受け付ける量に合わせて、traces.max_content_bytesをバイト単位で設定します(コンテンツの制限を参照)。宛先の一覧表示、変更、削除、またはワークスペースを1つ追加または削除するには、テレメトリ宛先APIのその他のメソッドを使用します。
2. 宛先のワークスペースを選択する
宛先は、対象とするワークスペースのスパンを受け取ります。ワークスペースは宛先を追加するときに選択します。ワークスペースで、次のいずれかを選択します。
- すべて: デフォルトワークスペースや後から作成されるワークスペースを含む、組織内のすべてのワークスペース。
- 選択したもののみ: 選択したワークスペースのみ。
- 次を除くすべて: すべてと同様ですが、選択したワークスペースを除きます。
選択したもののみまたは次を除くすべての場合は、オプションの下に表示される検索ボックスでワークスペースを選択します。後から宛先のワークスペースを変更するには、ワークスペースフィルターがすべてを表示している状態で、ConsoleのOpenTelemetry設定ページでその宛先のその他の操作メニューを開きます。編集をクリックし、別のワークスペースオプションを選択するか、検索ボックスでワークスペースを変更します。
組織で開発者ロールを持ち、あるワークスペースでワークスペース管理者ロールを持っている場合は、選択したもののみの宛先にそのワークスペースを追加したり、宛先から削除したりできます。ワークスペースフィルターをそのワークスペースに設定してから、宛先のその他の操作メニューを開きます。Claude Platform on AWSでは、Consoleにワークスペース管理者ロールはありません。その場合は、IAMポリシーによって、宛先にワークスペースを追加したり、宛先から削除したりできるユーザーが決まります。
APIは、リクエストまたはセッションが実行されるワークスペースを対象とする有効なすべての宛先にスパンを送信します。
3. スパンが届いていることを確認する
- Consoleで、その宛先の対象となるワークスペースを選択し、PlaygroundでMessages APIリクエストを送信します。アプリケーションからMessages APIリクエストを送信するか、そのワークスペースでManaged Agentsセッションを開始することもできます。セッションを開始するには、Claude Managed Agentsを始めるの手順に従ってください。
- ConsoleのOpenTelemetry設定ページで、宛先の配信列に正常と表示されていることを確認します。これには1分ほどかかる場合があります。
- オブザーバビリティプラットフォームで
service.name=claude-platformでフィルタリングし、リクエストのスパンを見つけます。
列に失敗と表示されている場合は、ポインターを合わせると最後のエラーが表示されます。考えられる原因については、配信エラーを参照してください。
4. APIスパンを独自のトレースに接続する
デフォルトでは、Messages APIリクエストまたはManaged AgentsセッションのAPIスパンは、それぞれ独立したトレースに含まれます。これらをアプリケーションのトレースに接続すると、独自のスパンの下にネストされます。
APIは、各リクエストのトレースコンテキストをW3Cのtraceparentヘッダーから読み取ります。ヘッダー内のsampledフラグがオフの場合、APIはそのリクエストのスパンおよびその下のスパンを出力しません。
APIスパンを接続するには、アプリケーションでSDKトレースを設定し、独自のスパンの内側からSDKを呼び出します。すると、独自のスパンにSDKスパンが含まれ、SDKスパンにAPIスパンが含まれます。これらのスパンをすべて同じオブザーバビリティプラットフォームに送信すると、プラットフォームはそれらを1つのトレースとして表示できます。Messages APIリクエストとManaged Agentsセッションのトレース例を参照してください。
次の例では、独自のスパンの内側でセッションにユーザーメッセージを送信します:
from opentelemetry import trace
tracer = trace.get_tracer("my-service")
with tracer.start_as_current_span("summarize_issues"):
client.beta.sessions.events.send(
session.id,
events=[
{
"type": "user.message",
"content": [{"type": "text", "text": "Summarize the open issues"}],
},
],
)SDKはアプリケーションのプロパゲーターを使用してtraceparentヘッダーを書き込み、その中のsampledフラグはサンプラーに従います。アプリケーションがB3など、W3Cトレースコンテキスト以外のプロパゲーターを使用している場合は、W3Cトレースコンテキストのプロパゲーターも追加してください。
たとえばManaged Agentsセッションを作成するときやユーザーメッセージを送信するときに、現在のスパンのトレースコンテキストをリクエストヘッダーにコピーします:
import os
import httpx2
from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
headers = {
"x-api-key": os.environ["ANTHROPIC_API_KEY"],
"anthropic-version": "2026-10-21",
"anthropic-beta": "managed-agents-2026-04-01",
"content-type": "application/json",
}
# アクティブなスパンのトレースコンテキストをリクエストヘッダーにコピーします。
TraceContextTextMapPropagator().inject(headers)
httpx2.post(
f"https://api.anthropic.com/v1/sessions/{os.environ['SESSION_ID']}/events",
headers=headers,
json={
"events": [
{
"type": "user.message",
"content": [{"type": "text", "text": "Summarize the open issues"}],
},
],
},
)Messages APIのMCPコネクターまたはManaged AgentsのMCPコネクターでMCPサーバーを接続した場合、APIはそのサーバーにもトレースを引き継ぎます。これにより、サーバーは独自のスパンをAPIスパンの下に配置できます。tools/callリクエストのparams._metaで、APIはそのツール使用のanthropic.mcp_tool_useスパンを参照するW3Cのtraceparentを送信します。Messages APIのMCPコネクターでは、MCPサーバーへのその他のリクエストと通知にもtraceparentが含まれ、anthropic.messages.createスパンを参照します。traceparentヘッダーのsampledフラグがオフのときなど、APIがMessages APIリクエストをトレースしない場合、MCPサーバーはtraceparentを受け取りません。
次のステップ
クライアントのオブザーバビリティを得られます。
クライアントからClaude APIへのリクエストを追跡します。
配信とヘルス
APIが宛先に送信するスパンには、次のルールが適用されます。
- 少なくとも1回: 宛先は同じスパンを複数回受け取る場合があります。重複を除去するには、トレースIDとスパンIDを使用してください。
- ベストエフォート: スパンは配信前に失われる場合があります。APIは失われたスパンを再送することはできません。
- 圧縮: APIはリクエストをgzipで圧縮し、ヘッダー
Content-Encoding: gzipを設定します。エンドポイントが圧縮されたリクエストに400、406、415、または422レスポンスを返した場合、APIは同じスパンを圧縮せずにすぐに再送します。その後約1日間は通常、その宛先への以降のリクエストを圧縮せずに送信します。 - 再試行: タイムアウト、接続・TLS・DNSの失敗、無効なアドレス、または
408、429、5xxレスポンスの後、APIは限られた回数だけ後で配信を再試行します。その他の失敗については再試行しません。 - タイムアウト: 各リクエストについて、エンドポイントは5秒以内にTLSハンドシェイクを完了し、5秒以内にレスポンスヘッダーを送信する必要があります。各配信は、再送信を含めて合計10秒でタイムアウトします。
- ユーザーエージェント: 各リクエストにはヘッダー
User-Agent: Claude-Platformが含まれます。
配信列には各宛先の状態が表示されます。状態の反映は最大1分遅れる場合があります。
| 配信状態 | 意味 |
|---|---|
| 正常 | 最後の配信が成功しました。 |
| 失敗 | 最後の配信が失敗しました。エラーを確認するには、失敗にポインターを合わせます。 |
| データなし | APIはまだ配信を試行していません。 |
| 無効 | 宛先はスパンを受け取りません。理由を確認するには、無効にポインターを合わせます。 |
APIは次の場合に宛先を無効にします:
- エンドポイントが
3xxリダイレクトを送信した場合。 - 24時間にわたってすべての配信が失敗した場合。
宛先が無効化されている間、APIはその宛先のスパンを破棄し、再度有効にしてもそれらは送信されません。エクスポートを再開するには、原因を修正し、宛先のその他の操作メニューのテストで修正を確認してください。その後、ワークスペースフィルターがすべてを表示している状態で、ConsoleのOpenTelemetry設定ページで同じメニューから有効にするをクリックします。エクスポートは約1分以内に再開されます。次の配信までは、配信列に以前のエラーとともに失敗が表示されたままになる場合があります。
宛先を変更するには、ワークスペースフィルターがすべてを表示している状態で、そのその他の操作メニューを開きます。次に、編集、無効化、有効にする、または削除をクリックします。宛先を無効化または削除すると、約1分以内に配信が停止します。OTLP エンドポイント URLのホストを変更した場合は、ヘッダーの値を再入力してください。宛先にOTLP トレースエンドポイント URLがある場合は、同じ新しいホストを指定するか、クリアしてください。
制限
| 制限 | 値 |
|---|---|
| 組織あたりの送信先(無効化されたものを含む) | 10 |
| 送信先に選択するワークスペース数 | 1,000 |
| 送信先あたりのリクエストヘッダー | 20 |
| ヘッダー名の長さ | 128バイト |
| ヘッダー値の長さ | 4,096バイト |
| すべてのヘッダー名と値の合計の長さ | 16,384バイト |
| エンドポイントURLの長さ | 2,048文字 |
ゼロデータ保持
スパンは、それを生成する機能と同じZDR適格性を持ちます。Claude Managed AgentsはZDRの対象外です。機能の適格性を参照してください。
トラブルシューティング
| 問題 | 確認事項 |
|---|---|
| APIスパンがない | ワークスペースには、そのワークスペースを対象とする有効な送信先が必要です。宛先のワークスペースを選択するを参照してください。送信先がワークスペースを対象にし始めた後、そのワークスペースからのスパンが届くまでに最大1分かかる場合があります。APIは、traceparentヘッダーのsampledフラグがオフになっているリクエスト、またはOpenAI互換エンドポイントへのリクエストに対してはスパンを出力しません。 |
| 配信列に失敗と表示される | ポインターを合わせると、最後のエラーが表示されます。考えられる原因を確認するには、配信エラーを参照してください。 |
| 配信列に無効と表示される | ポインターを合わせると、その理由が表示されます。理由については、APIが送信先を無効にする場合を参照してください。 |
| 送信先がコンテンツ全体に設定されているのに、スパンにプロンプトやレスポンスが含まれない | 組織がAnthropicとの間でHIPAA、FERPA、またはK-12のデータ取り扱い制限を設けている可能性があります。コンテンツモードを参照してください。 |
配信エラー
配信が失敗すると、配信列に失敗が表示されます。ポインターを合わせてエラーを確認し、考えられる原因を特定します。
| エラー | 考えられる原因 |
|---|---|
| HTTP error (status 401) または HTTP error (status 403) | 認証ヘッダーが間違っている |
| HTTP error (status 404) | OTLP エンドポイント URLまたはOTLP トレースエンドポイント URLのパスが間違っている |
| Invalid address | エンドポイントのホスト名が存在しないか、パブリックなIPアドレスに解決されない |
| Temporary DNS failure | エンドポイントのホスト名のDNS検索に失敗した(DNSサーバーがエラーを返した場合など) |
| TLS failure | エンドポイントの証明書などに関するTLSの問題 |
| Timeout | エンドポイントが時間内に応答しなかった。配信タイムアウトを参照してください |
| Connection failure | APIがエンドポイントに接続できなかった |
| Redirect (status 3xx) | エンドポイントがリクエストをリダイレクトした。APIはリダイレクトに従わないため、リダイレクト先のURLを使用してください |
| HTTP error (status 408、429、または 5xx) | エンドポイントが過負荷だった、リクエストのレートを制限した、またはエラーが発生した |
| HTTP error (その他の status 4xx) | エンドポイントがリクエストを拒否した(たとえば、サイズや形式が原因) |
利用可能状況
APIトレーシングはすべてのモデルでベータ版であり、ゼロデータ保持の対象です。
APIサポート
- Claude API
- Claude Platform on AWS
- Claude API
- Claude Platform on AWS
データの取り扱い
データの取り扱いの概要対象エンドポイント
/v1/organizations/telemetry_destinations
対象モデルを除く
ベータ版です。スパンのZDR適格性は、そのスパンを生成する機能と同じです。HIPAA組織はメタデータをエクスポートできます。SDKのスパンは、お使いの環境からエクスポーターに直接送信されます。配信後、データはAnthropicの外部にある選択したサービスによって、そのサービスの保持ポリシーとアクセス制御のもとで保持されます。
HIPAA組織はメタデータをエクスポートできます。
このページは役に立ちましたか?