管理OpenTelemetry

Claude APIのOpenTelemetry

Copy page



Claude SDKとClaude APIから出力されるOpenTelemetryスパンを使用して、Messages APIリクエスト、ツール使用、Managed Agentsセッションをトレースします。

Claude APIとSDKは、Messages APIリクエスト、ツール使用、Managed AgentsセッションをOpenTelemetryでトレースできます。これらのトレースは、すでにお使いのオブザーバビリティプラットフォームで確認できます。失敗したリクエストや遅いリクエストのデバッグ、トークン消費量とレイテンシの追跡、実際のトラフィックからの評価の構築に活用してください。また、アプリケーション自体のトレース内で各リクエストを確認し、それを送信したユーザーや機能と関連付けることもできます。

OpenTelemetryは、ほとんどのオブザーバビリティプラットフォームがサポートしているベンダー中立の標準です。「trace」（トレース）とは、システム内を通過する1つのリクエストの完全な記録です。「span」（スパン）とは、モデルリクエストやツール使用など、トレース内の1つのステップです。APIとSDKはGenAIセマンティック規約の属性を使用するため、この規約をサポートするプラットフォームは追加の設定なしでスパンを認識できます。

はじめに

SDKトレーシング、APIトレーシング、またはその両方を設定できます。トレースの例のように、リクエストのSDKスパンとAPIスパンを1つのトレースで確認するには、両方を設定してください。Claude Platform on AWSへのリクエストの場合、APIスパンは代わりに独自のトレースに含まれます。

Claude Code、Agent SDK、またはCoworkについては、Claude Codeのモニタリング、Agent SDKのオブザーバビリティ、またはCoworkのアクティビティモニタリングを参照してください。

パートナープラットフォームにトレースを送信する

トレースは、以下のパートナーを含め、OTLP を受け付けるあらゆるオブザーバビリティプラットフォームに送信できます。

コンテンツモード

各宛先と各SDKクライアントにはコンテンツモードがあり、スパンにモデルのプロンプトとレスポンスを含めるかどうかを設定します。宛先を追加するとき、またはSDKを設定するときに設定します。

• Metadata only（SDKではmetadata_only）：デフォルトです。スパンには識別子、タイミング、ステータス、トークン数、およびエージェントやツールの名前と説明、MCPサーバーの名前など、ご自身で指定したテキストが含まれます。
• Full content（SDKではcontent）：最も高い可視性が得られます。スパンにはモデルのプロンプトとレスポンス、およびMetadata onlyのすべての内容が含まれます。

Full contentを使用すると、実行が失敗した理由や遅かった理由の確認、会話全体の閲覧、実際のトレースからの評価の構築も可能です。OpenTelemetryスパンリファレンスでは、プロンプトとレスポンスを保持する属性にContentタグが付いています。

組織にAnthropicとのHIPAA、FERPA、またはK-12のデータ取り扱い制限がある場合、宛先はコンテンツモードにかかわらずメタデータのみをエクスポートします。SDKスパンは影響を受けません。

ゼロデータ保持を利用している場合でも、Full contentを使用できます。Messages APIリクエストについては、APIはエクスポートされたコンテンツを、宛先に配信するまでメモリ内にのみ保持します。Claude Managed Agentsはゼロデータ保持の対象外であり、OpenTelemetryを使用してもそのデータ保持は変わりません。

コンテンツの制限

Full contentでは、デフォルトで各スパンに最大0.75 MBのコンテンツを含められます。この制限には、200kトークンのコンテキストウィンドウを英語のテキストで埋めた内容が収まり、また多くのオブザーバビリティプラットフォームやプロキシの1 MBのリクエスト制限を下回ります。Providerとしてパートナープラットフォームを選択した場合、Consoleはそのプラットフォームが受け付ける制限を設定します。

コンテンツが制限を超えると、SDKまたはAPIはそのコンテンツを短縮し、anthropic.content.truncatedをtrueに設定します。リクエストのスパンでは、まずシステムプロンプトと最も古いメッセージが削除され、ツールスパンでは、結果の末尾からブロック単位で削除されます。画像とドキュメントは、そのタイプのみが表示されます。

次の場合は制限を変更します。

• オブザーバビリティプラットフォームがより大きなペイロードを受け付ける場合： 制限を引き上げるか撤廃して、長いプロンプトとレスポンスを短縮せずに保持します。1Mトークンのコンテキストウィンドウ全体には約4 MBが必要です。
• オブザーバビリティプラットフォームまたはその前段にあるプロキシが大きなリクエストを拒否する場合： 制限を引き下げます。

SDKでは、traces.max_content_bytesを設定します。Consoleでは、宛先を追加する際にContent modeをFull contentに設定し、Advanced settingsでMaximum content size in MBを設定します。

トレースの例と読み方

Messages APIリクエスト

メッセージを作成するリクエストのAPIスパンの下に、APIは各モデルリクエストのスパンと、APIが実行するサーバーツールまたはMCPコネクタツールの各使用についてのツールスパンを追加します。

この例では、アプリケーションがツールランナーを呼び出します。ツールランナーは、ツールを実行してその結果をClaudeに送り返すSDKヘルパーです。ツールランナーが送信する各リクエストには、SDKからのクライアントスパンとAPIからのサーバースパンがあります。スパンは次の順序で表示されます：

1. アプリケーションがanswer_questionスパンを開始し、その内側でMessagesツールランナーを呼び出します（anthropic.messages.tool_runnerスパンとして表示されます）。
2. ツールランナーが最初のリクエストを送信します（最初のanthropic.messages.createクライアントスパンとその下のスパンとして表示されます）。このリクエストでは、APIが2つのモデルリクエストの間でウェブ検索ツールを実行します。
3. 2番目のモデルリクエストで、モデルがカスタムのget_weatherツールの使用を要求するため、最初のリクエストが終了します。
4. ツールランナーがget_weatherを実行します（anthropic.custom_tool_use get_weatherスパンとして表示されます）。
5. ツールランナーがツールの結果とともに2番目のリクエストを送信します（2番目のanthropic.messages.createクライアントスパンとその下のスパンとして表示されます）。
6. 2番目のリクエストで、モデルが最終的な回答を返します。

アプリケーション内のSDKは、anthropic.messages.tool_runnerスパン、anthropic.custom_tool_useスパン、および各リクエストのクライアントスパンを出力します。これらのスパンを取得するには、SDKトレースを設定してください。

各リクエストのトークン使用量は、そのリクエストの複数のスパンに記録されます。各トークンを1回だけカウントするには、トークンのカウントを参照してください。

Full contentでは、anthropic.messages.createサーバースパンにプロンプトとレスポンスが含まれます。システムプロンプトはgen_ai.system_instructionsに、リクエストのメッセージはgen_ai.input.messagesに、レスポンスはgen_ai.output.messagesに含まれます。

各スパンとその属性については、OpenTelemetryスパンリファレンスを参照してください。

Managed Agentsのセッション

セッションには、Sessions APIリクエストごとの「span」（スパン）と、エージェントのターンごとのターンスパンがあります。リクエストによって開始されたターンは、そのリクエストのスパンの子になります。ターンには、モデルリクエストごとのスパンと、APIが実行するツールごとのスパンが含まれます。ただし、ツールスパンのリファレンスに記載されているケースは除きます。また、結果評価ごとのスパンも含まれます。

この例では、アプリケーションがセッションにメッセージを送信し、カスタムツールを実行する1つのチャットリクエストを追跡します。「trace」（トレース）には、アプリケーションとAPIの両方からのスパンが、次の順序で含まれます。

1. アプリケーションがユーザーからPOST /chatリクエストを受け取ります。
2. アプリケーションがSDKのセッションツールランナーを開始し、セッションのイベントを一覧表示してストリーミングします（anthropic.sessions.events.streamスパンとanthropic.sessions.events.listスパンとして表示されます）。
3. アプリケーションがsessions.events.sendを呼び出して、ユーザーのメッセージをセッションに送信します。
4. ターンが開始され、モデルリクエスト、bashツール使用、および別のスレッドでのターンが含まれます（最初のanthropic.session.turnスパンとその配下のスパンとして表示されます）。
5. モデルがカスタムツールlist_issuesの使用を要求するため、ターンは停止理由requires_actionで終了します。
6. セッションツールランナーがlist_issuesを実行し（anthropic.custom_tool_use list_issuesスパンとして表示されます）、sessions.events.sendを呼び出してその結果を送信します。
7. ツールの結果とともに2番目のターンが開始されます（最後のanthropic.session.turnスパンとして表示されます）。

アプリケーション内のSDKは、anthropic.custom_tool_useスパンと各リクエストのクライアントスパンを出力します。これらのスパンを取得するには、SDKトレーシングを設定してください。

セッションのスパンは、複数のトレースにまたがる場合があります。たとえば、新しいルートトレースから後続のリクエストを送信した場合です。マルチエージェントを有効にすると、セッションは複数のスレッドを持つこともできます。必要なスパンを見つけるには、IDでグループ化します。

• 1つのスレッド： セッションスレッドIDを保持するgen_ai.conversation.idでスパンをグループ化します。開始時刻で並べ替えると、スレッドをトランスクリプトとして読むことができます。
• すべてのスレッドを含むセッション全体： トレースをまたいでanthropic.session.idでスパンをグループ化します。

Full contentを使用すると、セッションのスパンからその内容を読むことができます。

• ターンの内容を読むには、そのターンスパンを使用します。システムプロンプトはスレッドの最初のターンスパンのgen_ai.system_instructionsに、入力はgen_ai.input.messages（あなたのメッセージとツールの結果、system.messageイベント、および他のスレッドからのメッセージ）に、出力はgen_ai.output.messages（エージェントのメッセージ、ツール使用、およびツールの結果）に含まれます。
• ツール使用の引数と結果を確認するには、そのツールスパンを読みます。引数はgen_ai.tool.call.argumentsに、結果はanthropic.tool_result.contentに含まれます。

各スパンとその属性については、OpenTelemetryスパンリファレンスを参照してください。

トークンのカウント

各トークンを1回だけカウントするには、リクエストごとに1つのソースのスパンのみを合計します。Messages APIリクエストにSDKスパンとAPIスパンの両方がある場合は、そのAPIスパンを合計します。どちらもanthropic.messages.createという名前なので、種類（kind）で区別します。SDKスパンはCLIENTで、その子であるAPIスパンはSERVERです。

一部の使用量属性はAPIスパンの複数のレベルで重複するため、各ソースについて次のスパンのみを合計してください。

• SDKスパン： anthropic.messages.createスパンを合計します。リクエストにコンパクションがある場合は、gen_ai.usage.*属性にコンパクションのトークンが含まれないため、スパンのanthropic.usage.compaction.input_tokensとanthropic.usage.compaction.output_tokensも加算します。フォールバックモデルがリクエストを処理した場合、そのスパンにはレスポンスを処理したモデルの使用量のみが含まれます。
• Messages APIリクエストのAPIスパン： anthropic.messages.createスパンか、そのanthropic.model_requestスパンのいずれか一方を合計し、両方は合計しないでください。リクエストにコンパクションがある場合は、そのanthropic.compactionスパンも加算します。anthropic.messages.createスパンのanthropic.usage.compaction.*属性は同じトークンを保持しているため、これらを追加で加算しないでください。
• Managed AgentsセッションのAPIスパン： anthropic.model_requestスパンとanthropic.session.outcome_evaluationスパンを合計します。

たとえば配信が再試行された場合など、スパンが複数回届くことがあります。オブザーバビリティプラットフォームで重複が除去されない場合は、トレースIDとスパンIDによって各スパンを1回だけカウントしてください。

gen_ai.usage.input_tokensには、プロンプトキャッシングのキャッシュから読み取られたトークンとキャッシュに書き込まれたトークンがすでに含まれているため、キャッシュ属性を加算しないでください。すべての使用量属性については、トークン使用量を参照してください。