Claude APIで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. 宛先を追加する

1. Consoleで、組織のOpenTelemetry設定ページを開き、Add destinationをクリックします。

2. 宛先を設定します：

   フィールド	入力内容
   Provider	お使いのオブザーバビリティプラットフォーム。一覧にない場合はCustom。一覧にあるプラットフォームを選択した場合、ConsoleではOTLP endpoint URL、Request headers、OTLP traces endpoint URLの代わりに、APIキーなどのプラットフォームの詳細の入力を求められます。
   Name	任意。たとえば「Acmeのオブザーバビリティプラットフォーム」。
   OTLP endpoint URL	オブザーバビリティプラットフォームのOTLP/HTTPエンドポイントのベースHTTPS URL。IPアドレスではなくホスト名を使用します。https://gateway.example.com/otlpのようにパスプレフィックスを含めることができます。/v1/tracesはAPIが追加するため、追加しないでください。OTLP traces endpoint URLを設定した場合、APIは代わりにそのURLを使用します。
   Request headers	APIが各リクエストとともに送信するヘッダー。たとえばオブザーバビリティプラットフォームのAPIキーヘッダーです。認証情報はヘッダー値にのみ入力してください。保存後、Consoleは値を再表示しません。
   Content mode	Metadata onlyまたはFull content。コンテンツモードの違いを参照してください。
   Workspaces	宛先がスパンを受け取るワークスペース：All、Selected、またはAll except。宛先のワークスペースを選択するを参照してください。
   OTLP traces endpoint URL	任意。Advanced settingsの下にあります。オブザーバビリティプラットフォームのトレースエンドポイントの完全なURL。たとえばhttps://gateway.example.com/custom/traces。プラットフォームが、OTLP endpoint URLに/v1/tracesを付けたもの以外のURLでトレースを受け取る場合に設定します。OTLP endpoint URLと同じホストである必要があります。
   Maximum content size in MB	任意。コンテンツモードがFull contentの場合、Advanced settingsの下にあります。APIが各スパンで送信するコンテンツの最大量。選択したProviderに応じて、Consoleが自動的に入力します。オブザーバビリティプラットフォームが受け付けるサイズに合わせて変更してください。APIが許容する最大量まで送信するには、空のままにしてください。コンテンツの制限を参照してください。

3. Add destinationをクリックして保存します。

4. 宛先のMore actionsメニューでTestをクリックします。テストスパンがコレクターに配信されたことを示すメッセージ、または配信がどのように失敗したかを示すメッセージが表示されます（配信エラーを参照）。

5. anthropic.testスパンがオブザーバビリティプラットフォームに届いたことを確認します。

Admin APIとCLI

Consoleの代わりにAdmin APIを通じて宛先を追加することもできます。管理者としてCLIにサインインするか、ANTHROPIC_API_KEYに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)

作成リクエストはProviderを除くConsoleの設定を受け取るため、オブザーバビリティプラットフォームのエンドポイントURLとヘッダーはご自身で入力してください。オブザーバビリティプラットフォームが受け付ける量に合わせて、traces.max_content_bytesをバイト単位で設定します（コンテンツの制限を参照）。宛先の一覧表示、変更、削除、またはワークスペースを1つ追加または削除するには、テレメトリ宛先APIのその他のメソッドを使用します。

2. 宛先のワークスペースを選択する

宛先は、対象とするワークスペースのスパンを受け取ります。ワークスペースは宛先を追加するときに選択します。Workspacesで、次のいずれかを選択します。

• All： Default Workspaceや後から作成されるワークスペースを含む、組織内のすべてのワークスペース。
• Selected： 選択したワークスペースのみ。
• All except： Allと同様ですが、選択したワークスペースを除きます。

SelectedまたはAll exceptの場合は、オプションの下に表示される検索ボックスでワークスペースを選択します。後から宛先のワークスペースを変更するには、WorkspaceフィルターがAllを表示している状態で、OpenTelemetry設定ページでその宛先のMore actionsメニューを開きます。Editをクリックし、別のWorkspacesオプションを選択するか、検索ボックスでワークスペースを変更します。

組織で開発者ロールを持ち、あるワークスペースでWorkspace Adminロールを持っている場合は、Selectedの宛先にそのワークスペースを追加したり、宛先から削除したりできます。Workspaceフィルターをそのワークスペースに設定してから、宛先のMore actionsメニューを開きます。Claude Platform on AWSでは、ConsoleにWorkspace Adminロールはありません。その場合は、IAMポリシーによって、宛先にワークスペースを追加したり、宛先から削除したりできるユーザーが決まります。

APIは、リクエストまたはセッションが実行されるワークスペースを対象とする有効なすべての宛先にスパンを送信します。

3. スパンが届いていることを確認する

1. Consoleで、その宛先の対象となるワークスペースを選択し、playgroundでMessages APIリクエストを送信します。アプリケーションからMessages APIリクエストを送信するか、そのワークスペースでManaged Agentsセッションを開始することもできます。セッションを開始するには、Claude Managed Agentsを始めるの手順に従ってください。
2. ConsoleのOpenTelemetry設定ページで、宛先のDelivery列にHealthyと表示されていることを確認します。これには1分ほどかかる場合があります。
3. オブザーバビリティプラットフォームでservice.name = claude-platformでフィルタリングし、リクエストのスパンを見つけます。

列にFailingと表示されている場合は、ポインターを合わせると最後のエラーが表示されます。考えられる原因については、配信エラーを参照してください。

4. APIスパンを独自のトレースに接続する

デフォルトでは、Messages APIリクエストまたはManaged AgentsセッションのAPIスパンは、それぞれ独立したトレースに含まれます。これらをアプリケーションのトレースに接続すると、独自のスパンの下にネストされます。

APIは、各リクエストのトレースコンテキストをW3Cのtraceparentヘッダーから読み取ります。ヘッダー内のsampledフラグがオフの場合、APIはそのリクエストのスパンおよびその下のスパンを出力しません。Claude Platform on AWSはまだこのヘッダーをサポートしていません。Claude Platform on AWSに送信するリクエストのスパンは、sampledフラグがオフの場合でも、常に独自のトレースを開始します。

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"}],
            },
        ],
    )

import os
import httpx2
from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator

headers = {
    "x-api-key": os.environ["ANTHROPIC_API_KEY"],
    "anthropic-version": "2023-06-01",
    "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コネクターでMCPサーバーを接続した場合、そのMCPサーバーにもトレースを引き継ぐため、MCPサーバーは独自のスパンをAPIスパンの下に配置できます。APIがMCPサーバーに送信する各リクエストと通知には、params._metaにW3Cのtraceparentが含まれます。tools/callリクエストでは、そのツール使用のanthropic.mcp_tool_useスパンを参照します。その他のメッセージではanthropic.messages.createスパンを参照します。traceparentヘッダーのsampledフラグがオフのリクエストなど、APIがトレースしないリクエストについては、APIはtraceparentを送信しません。

次のステップ

配信とヘルス

APIが宛先に送信するスパンには、次のルールが適用されます。

• 少なくとも1回： 宛先は同じスパンを複数回受け取る場合があります。重複を除去するには、トレースIDとスパンIDを使用してください。
• ベストエフォート： スパンは配信前に失われる場合があります。APIは失われたスパンを再送することはできません。
• 圧縮： APIは各配信の最初のリクエストをgzipで圧縮し、ヘッダーContent-Encoding: gzipを設定します。エンドポイントがそのリクエストに400または415レスポンスを返した場合、APIは同じスパンを圧縮せずにすぐに再送します。
• 再試行： タイムアウト、接続・TLS・DNSの失敗、または408、429、5xxレスポンスの後、APIは限られた回数だけ後で配信を再試行します。その他の失敗については再試行しません。
• タイムアウト： 各リクエストについて、エンドポイントは5秒以内にTLSハンドシェイクを完了し、5秒以内にレスポンスヘッダーを送信する必要があります。各配信は、圧縮なしでの再送信を含めて合計10秒でタイムアウトします。
• ユーザーエージェント： 各リクエストにはヘッダーUser-Agent: Claude-Platformが含まれます。

Delivery列には各宛先の状態が表示されます。状態の反映は最大1分遅れる場合があります。

APIは次の場合に宛先を無効にします：

• エンドポイントが3xxリダイレクトを送信した場合。
• エンドポイントのホスト名がパブリックではないIPアドレスに解決された場合。
• 24時間にわたってすべての配信が失敗した場合。

APIは無効化された宛先にスパンを送信しません。エクスポートを再開するには、原因を修正してください。その後、OpenTelemetry設定ページのWorkspaceフィルターがAllを表示している状態で、宛先のMore actionsメニューからEnableをクリックします。エクスポートは約1分以内に再開されます。

宛先を変更するには、WorkspaceフィルターがAllを表示している状態で、そのMore actionsメニューを開きます。次に、Edit、Disable、Enable、またはDeleteをクリックします。OTLP endpoint URLのホストを変更した場合は、ヘッダーの値を再入力してください。宛先にOTLP traces endpoint URLがある場合は、同じ新しいホストを指定するか、クリアしてください。

制限

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

配信エラー

配信が失敗すると、Delivery列にFailingが表示されます。ポインターを合わせてエラーを確認し、考えられる原因を特定します。

Compatibility