Claude OpenTelemetryトレーシング：APIとSDKの設定を解説

Anthropicは、Claude Managed Agents、Messages API、Claude SDK向けにOpenTelemetryトレースエクスポートを導入しました。2026年10月14日に発表されたこの機能はパブリックベータ版であり、OTLPを受け付けるオブザーバビリティプラットフォームへ標準的なトレースデータを送信します。

目的は実務的です。エージェントのモデル呼び出しやツールアクティビティを、それを呼び出したアプリケーションと併せて追跡できます。レイテンシー、障害、トークン使用量を別々の場所で調査する代わりに、チームは既存のオブザーバビリティシステム内で関連するスパンを確認できます。

2つの設定経路と1つのトレースモデル

トレースは、システム内でリクエストがたどる経路を記録します。スパンは、モデル呼び出しやツール実行など、その経路内の1つの操作を記録します。ClaudeのスパンはOpenTelemetryのGenAIセマンティック規約に従っており、互換ツールが複数のモデルプロバイダーにまたがってデータを解釈しやすくなっています。

出典：Anthropic。この図は、計測済みのパフォーマンス結果ではなく、トレース構造と分析ワークフローを示しています。

データを収集する方法は、相互補完的な2種類です。

どちらの経路でもリクエストスパンとトークン使用量が記録されます。両方を組み合わせることで、クライアント側の処理とClaude API内部で実行される処理の両方を可視化できます。さらに、両方を同一のバックエンドへ送信すると、その関係をバックエンド上で表示できます。

ConsoleでAPIトレーシングを設定する

APIトレーシングでは、単独のAPIトレースを受け取るためだけに通常のリクエストコードを変更する必要はありません。管理者が、Claudeから送信する先を指定するデスティネーションを追加します。

1. Claude Consoleで組織のOpenTelemetry設定を開き、Add destinationを選択します。
2. 一覧にあるプロバイダーを選ぶか、カスタムOTLP/HTTPエンドポイントと認証ヘッダーを入力します。
3. デスティネーションの対象となるワークスペースを選び、コンテンツモードを選択します。
4. デスティネーションを保存してTestを実行し、anthropic.testスパンが到着することを確認します。
5. 対象ワークスペースからリクエストを送信し、デスティネーションの健全性と生成されたトレースを確認します。APIスパンはservice.name = claude-platformを使用します。

カスタムデスティネーションでは、ドキュメント上の要件として、ポート443のHTTPSホスト名でprotobufを受け入れるOTLP/HTTPエンドポイントが必要です。通常のポート4318だけで待ち受けるCollectorには、適切なHTTPS公開またはリバースプロキシが必要です。認証情報はヘッダー値に設定します。

通常、ベースエンドポイントには/v1/tracesを含めません。Claudeがこのパスを追加するためです。高度なトレースエンドポイントではパスを上書きできますが、同じホストを使用する必要があります。プライベートアドレスのエンドポイントおよびリダイレクトは、通常の配信先デスティネーションとしてサポートされていません。

アプリケーションでSDKトレーシングを設定する

SDKトレーシングは、サポート対象の最新Claude SDKをインストールし、トレース対象となる最初の呼び出しより前にOpenTelemetryトレーサープロバイダーを登録することから始まります。アプリケーションは、スパンをオブザーバビリティバックエンドへ配信するエクスポーターを提供します。そのため、「SDKの自動エクスポート」は、トレーサープロバイダーと配信先エクスポーターなしで、新しいアプリケーションが自動的にどこかへデータを送信することを意味するものではありません。

リモートプラットフォームに接続する前に、コンソールエクスポーターを使用してローカルの計装を確認できます。設定後、SDKはリクエストスパンと、そのツールランナーを通じて実行されるツールのスパンを出力します。アプリケーションスパン内で行われた呼び出しは、そのスパンの配下にネストできます。

ベータ期間中は、SDKのオプション、スパン名、属性が変更される場合があります。Anthropicは、チームがこれらの変更をいつ採用するか選べるよう、SDKバージョンを固定することを推奨しています。

トレースの結合とエージェントセッションを理解する

SDKはトレースコンテキストを伝播するため、APIのサーバースパンをSDKのクライアントスパンの配下に配置できます。Claude Platform on AWSへのリクエストは例外です。このプラットフォームでは、同じトレースコンテキスト結合の動作がまだサポートされていないため、APIスパンはそれぞれ別のトレースに表示されます。

Managed Agentsのセッションでは、Sessions APIのリクエストスパン、エージェントターンスパン、モデルリクエスト、APIが実行したツール、結果評価が公開されます。1つのセッションは複数のトレースにまたがることがあり、マルチエージェント運用では複数のスレッドにまたがる場合もあります。ドキュメントは、セッションにはanthropic.session.id、スレッドにはgen_ai.conversation.idでグループ化することを推奨しています。

Claude Code、Agent SDK、Coworkには、それぞれ独自のモニタリングドキュメントがあります。この新しいプラットフォーム機能を、各製品の既存の計装手順すべてを置き換えるものとして扱うべきではありません。

コンテンツモード、制限、データ処理

各ConsoleデスティネーションとSDKクライアントにはコンテンツモードがあります。デフォルトのMetadata onlyには、識別子、タイミング、ステータス、トークン数、ツール名、ツール説明、MCPサーバー名など一部の説明テキストが含まれます。モデルのプロンプトと応答は除外されますが、エクスポートされるすべてのフィールドがアプリケーション提供テキストを含まないことを保証するものではありません。

Full contentには、プロンプトと応答も含まれます。失敗した対話のデバッグや実トラフィックに基づく評価の構築には有用ですが、会話コンテンツが、独自のアクセス制御および保持設定を持つ別のシステムへ移動することになります。

コンテンツサイズと切り詰め

デフォルトのコンテンツ上限は、1スパンあたり0.75 MBです。Anthropicによれば、この上限は約20万トークンの英語コンテキストに対応し、多くのオブザーバビリティサービスおよびプロキシで使用される1 MBのリクエスト上限を下回ります。100万トークンの完全なコンテキストには約4 MBが必要になる可能性があるため、デフォルトでは大きなプロンプトをすべて完全に保持するには不十分です。

スパンがコンテンツ上限を超えると、SDKまたはAPIが内容を短縮し、anthropic.content.truncatedをtrueに設定します。リクエストスパンでは、システムプロンプトと最も古いメッセージから先に破棄されます。ツールスパンでは、ツール結果の末尾からブロックが破棄されます。画像とドキュメントは、完全なメディアペイロードではなくタイプとして表示されます。

SDKでは、traces.max_content_bytesで上限を制御します。Consoleデスティネーションでは、高度な設定に最大コンテンツサイズがあり、一覧にあるプロバイダーにはプロバイダー固有のデフォルトが設定されている場合があります。

制限対象データとゼロデータ保持

Anthropicとの間でHIPAA、FERPA、またはK–12のデータ処理制限を持つ組織は、選択したコンテンツモードにかかわらず、APIデスティネーションを通じてメタデータのみをエクスポートします。ドキュメントによれば、この制限はSDKスパンには適用されないため、SDK設定については別途レビューが必要です。

Full contentエクスポートは、配信までAPIがエクスポートコンテンツをメモリ内に保持するため、対象となるゼロデータ保持のMessages APIリクエストで使用できます。Managed Agentsはゼロデータ保持の対象ではなく、OpenTelemetryを有効化してもその保持条件は変わりません。

トークンの二重計上を避ける

1つのリクエストのトークン使用量が、トレース内の複数スパンに記録されることがあります。そのため、トレース内のすべてのスパンを合算すると、使用量を過大に見積もる可能性があります。

Messages APIリクエストにSDKスパンとAPIスパンの両方が存在する場合は、APIソースを使用します。そのソース内では、リクエストスパンまたはそのモデルリクエストスパンのどちらかを合算し、両方を合算しないでください。コンパクションについては、ドキュメントにある特定のルールに従ってください。Managed Agentsでは、関連するAPIスパンはモデルリクエストと結果評価です。

配信の再試行によって、重複するスパンが生成される場合もあります。バックエンドがすでに処理していない場合は、トレースIDとスパンIDを使用して重複を除去してください。

**エクスポートされたトレースはデバッグ記録であり、完全性が保証された請求台帳ではありません。**配信はベストエフォートであり、サンプリングによってリクエストが除外されることがあります。APIキー単位で完全な使用量追跡が必要なチームには、AnthropicはUsage APIを案内しています。

オブザーバビリティ統合と顧客事例

Anthropicは、アプリケーションログやメトリクスと並べてエージェントトレースを表示するツールとして、Grafana Cloud、Honeycomb、Sentry、Splunkを挙げています。また、トレースを評価や品質改善と結び付けるワークフロー向けに、Arize AI、Braintrust、Datadog、Langfuse、LangSmith、New Relic、PostHogを挙げています。Databricks Unity Gatewayは、組織レベルの可視性を提供するものとして取り上げられています。

これらは例であり、互換性のあるツールを限定する一覧ではありません。必要な標準OTLPエクスポートを受け入れられる他のツールもデータを受信できます。

発表には、Foxglove、Ramp、Sterling Labs、FloQastの顧客コメントが含まれています。ユースケースには、ロボティクスのデバッグ、市場分析エージェントの分析、会計ワークフローのトレースが含まれます。

Rampは、Langfuseトレースをスコアリングして修正案を提案するReflectという社内システムについて説明しています。同社のエンジニアは、一部のエージェントでトークン使用量が10～20%減少し、セッションが30%高速化したと報告しています。これらはその改善ワークフローにおける顧客報告の結果であり、トレースエクスポートを有効にするだけで同様の成果が得られることを約束するものではありません。

FAQ

Claude OpenTelemetryトレースエクスポートとは何ですか？

Claude APIリクエスト、エージェントターン、モデル呼び出し、サポート対象のツールアクティビティを表す標準スパンを、オブザーバビリティバックエンドへ送信する機能です。この機能はパブリックベータ版であり、APIトレーシングとSDKトレーシングの別々の経路をサポートしています。

トレーシングを有効にするにはAdminロールが必要ですか？

Claude ConsoleでAPIトレーシングのデスティネーションを追加または変更するにはAdminロールが必要です。SDKトレーシングはアプリケーションコードで設定し、Claude組織における特別な権限は必要ありません。

プロンプトと応答はデフォルトでエクスポートされますか？

いいえ。デフォルトモードはMetadata onlyです。Full contentではプロンプトと応答が追加されますが、コンテンツ上限および特定の組織に適用されるドキュメント上の制限に従います。

セルフホスト型OpenTelemetry Collectorを使用できますか？

はい。APIデスティネーションがドキュメントに記載されたネットワークおよびプロトコル要件を満たしている場合に使用できます。特に、APIエクスポートには、プライベートなCollectorリスナーだけではなく、ポート443のパブリックHTTPSホスト名から到達可能なOTLP/HTTP protobufレシーバーが必要です。

SDKスパンとAPIスパンを同じトレースに表示できますか？

はい。トレースコンテキストが伝播され、スパンが同一のオブザーバビリティバックエンドに届く場合に可能です。ただし、Claude Platform on AWSへのリクエストのAPIスパンは、現在はそれぞれ別のトレースに表示されます。

トレースは請求総額のためにUsage APIの代わりになりますか？

いいえ。トレースはサンプリングされたり、失われたり、複数回配信されたりする可能性があります。分析にはドキュメント化された計数ルールを使用し、完全な使用量計算が必要な場合はUsage APIを使用してください。

関連ツール

• Claude SDKトレーシング：リクエストおよびツールランナースパン向けのクライアント計装。
• Claude APIトレーシング：API側のモデルおよびツールスパンをConsoleで管理してエクスポートする機能。
• OpenTelemetry：この統合で使用される、ベンダー中立のトレーシングフレームワークおよびエクスポートエコシステム。

関連リンク

• Unite.AIの元レポート：この記事のきっかけとなった10月14日のニュースレポート。
• Anthropicの発表：公式の機能提供状況、統合、顧客コメント。
• OpenTelemetry概要：対象範囲、コンテンツ制限、トークン計数、データ処理ルール。
• APIトレーシング設定：デスティネーション設定、エンドポイント要件、配信トラブルシューティング。
• SDKトレーシング設定：トレーサープロバイダー、エクスポーター、設定、ストリーム処理。
• GenAIセマンティック規約：生成AIテレメトリーに関するOpenTelemetryプロジェクトの共通規約。

まとめ

ClaudeのOpenTelemetryベータ版は、モデル呼び出しとエージェントツールを、チームがすでに利用しているトレーシングシステムへ接続します。APIトレーシングはサーバー側アクティビティを公開し、SDKトレーシングはクライアント操作とツールを追加します。トレース結合がサポートされる環境では、両方を組み合わせることで最も明確なアプリケーションタイムラインを得られます。

コンテンツモードは慎重に選び、切り詰めと配信の健全性を確認し、適切な単一ソースからトークンを計数してください。トレーシングは可視性を向上させますが、完全な使用量計算と保持管理は依然として別の責務です。