ClaudeDevsはClaude PlatformのOpenTelemetryトレースがパブリックベータだと述べました

変わったこと

ClaudeDevsは、スパンがOpenTelemetryのgen_aiコンベンションに従い、既定では所要時間、ステータス、トークン数、モデル、ツール名といったメタデータを運ぶと述べました。同じ投稿は、送信先を「full content」に切り替えると、プロンプト、応答、ツールの入力、ツールの結果もエクスポートされると述べました。

APIのドキュメントは、Claude APIがモデルリクエストごと、およびツール使用ごとにスパンを出し、対象はMessages APIリクエストとManaged Agentsセッションだと述べています。送信先があれば、アプリケーションのコードを変えずにそれらのスパンを見られます。既定では、一つのリクエストまたは一つのセッションのスパンは独自のトレースで始まります。それらのスパンをアプリケーションのトレースの下にぶら下げるときは、APIがW3Cのtraceparentヘッダーを読みます。そのヘッダーのsampledフラグがオフなら、APIはそのリクエストのスパンも、その下のスパンも出しません。Claude Platform on AWSはまだこのヘッダーに対応していません。そこへ送ったリクエストのスパンは、sampledフラグがオフでも常に独自のトレースで始まります。

SDKのドキュメントは別の経路を説明しています。SDKは、自ら送るリクエストごと、およびtool runnerが実行するツール使用ごとに、アプリケーション内でスパンを出し、アプリケーションのOpenTelemetryエクスポーターがそれを送ります。ベータの間、SDKのオプションとスパンのスキーマは、コード、クエリ、ダッシュボードを壊し得ます。スパン、属性、オプション、環境変数の改名も含まれます。SDKのページはSDKのバージョンを固定するよう述べています。スパンは既定でオンです。

Consoleの送信先はMetadata onlyまたはFull contentです。SDKではtraces.content_modeの既定値がmetadata_onlyです。プロンプトと応答を含めるSDKの値はcontentで、Consoleの送信先のFull contentとは別のラベルです。SDKのオプション表は、スパンあたり既定0.75 MBとし、traces.max_content_bytesで変えると記しています。それらのページが名を挙げるgen_ai属性は、gen_ai.conversation.idに載る任意の会話idだけで、両方のコンテンツモードでエクスポートされます。SDKのページは、そのidに個人データや秘密を入れないよう述べています。Full contentの送信先なのにプロンプトや応答がまだ無い場合、APIのドキュメントはHIPAA、FERPA、またはK-12の制限の可能性を指しています。

同じリクエストのSDKスパンとAPIスパンは名前を共有できます。その組はspan kindまたはservice.nameで見分けます。これは、送信先が同じAPIスパンを二度受け取ることとは別です。

• ClaudeDevsの発表
• Claude APIのOpenTelemetry
• Claude SDKのOpenTelemetry

誰が有効にできるか

送信先の追加や変更には、Claude Console組織のadminロールが要ります。developerロールは送信先を閲覧できます。Claude Platform on AWSでは、AWS Consoleからサインインします。そこでは、誰が送信先を管理できるかをIAMポリシーが決めます。

エンドポイントは、protobufを使うHTTP上のOpenTelemetry Protocol（OTLP）を、ポート443のHTTPS URLで受ける必要があります。URLはホスト名を使います。ドキュメントは、セルフホストのコレクターが既定でポート4318を待ち受けると述べているので、443でHTTPSを受けるか、前段にロードバランサーかリバースプロキシを置きます。資格情報はヘッダー値にだけ入れます。保存後、Consoleはその値を再び表示しません。同じホストにOTLP traces endpoint URLを設定しない限り、APIは/v1/tracesを付けます。送信先のTest操作はanthropic.testスパンを送ります。エンドポイントが3xxリダイレクトを返す、ホスト名がパブリックでないIPに解決される、またはすべての配送が24時間失敗すると、APIは送信先を無効にします。原因を直したあと、送信先メニューのEnableがエクスポートを再開し、エクスポートは約1分以内に再び始まります。

ワークスペースの対象は三つの設定です。Allは、Default Workspaceと、あとから作られるワークスペースを含め、組織のすべてのワークスペースを覆います。All exceptは、その全体から、指定したワークスペースを外します。Selectedは、指定したワークスペースだけを覆います。APIは、リクエストまたはセッションが動くワークスペースを覆う、有効なすべての送信先へスパンを送ります。Workspace Adminロールも持つdeveloperは、Selectedの送信先でそのワークスペースを追加または削除できます。Claude Platform on AWSにWorkspace Adminロールはありません。そこでは、ワークスペースを送信先に追加する人、外す人をIAMポリシーが決めます。

管理者はAdmin APIでも送信先を作れます。Claude Platform on AWSでは、その呼び出しはAWS資格情報で署名され、https://aws-external-anthropic.{region}.api.aws へ向かいます。その呼び出しのリクエストに入れられるのは、そのリージョンにあるそのアカウントのワークスペースだけです。

APIのページは、このサーバー側エクスポートをClaude APIとClaude Platform on AWSでベータと表示しています。SDKのページは、その二つにAmazon Bedrock、Google Cloud、Microsoft Foundryを加えた対象でトレーシングをベータと表示しています。どちらのページも、Messages APIとClaude Managed Agentsで動くと述べています。SDKスパンはアプリケーションのエクスポーターが送ります。APIが送信先へ送るスパンの配送はat least onceかつbest effortです。同じスパンが複数回到着することがあり、そのコピーはtrace IDとspan IDで取り除きます。配送前に失われたスパンは、再び送ることはできません。

配送のあと、選んだサービスがAnthropicの外で、そのサービスの保持とアクセス制御の下にデータを持ちます。APIのページはOpenTelemetryをZDR eligibleと表示し、covered modelsの除外を加えています。この表示は、それ自体がZDR eligibleな機能、たとえばMessages APIにだけ当てはまります。同じ注記は、Claude Managed AgentsはZDR eligibleではないと述べています。これらのページはZDRもcovered modelsも定義していません。

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

Managed Agentsのセルフホストサンドボックスではサンドボックスがツールを実行するので、ツールのスパンはAPIではなくSDKから出ます。Python、TypeScript、GoのSDKにあるenvironment workerは、実行するツールごと、送るリクエストごとにスパンを出し、作業項目ごとに一つのanthropic.environment.workスパンの下へまとめます。ワーカーのプロセスにはSDKトレーシングの設定が必要で、サンドボックスはオブザーバビリティの基盤かコレクターへ到達できる必要があります。ワーカーがツール結果を送ると、そのリクエストのAPIスパンは対応するSDKスパンの下に入ります。そのワーカーがClaude Platform on AWSへ送るリクエストは、APIスパンを別のトレースに置いたままにします。