OpenTelemetryの取り込みリファレンス
このページは、AmplitudeのOTLPエンドポイントがOpenTelemetry GenAIスパンをエージェント分析[Agent]イベントにどのように変換するかを示すリファレンスです。設定手順については、OpenTelemetryトレースをエージェント分析に送信するを参照してください。
エンドポイントとプロトコル
| 地域 | エンドポイント |
|---|---|
| 米国 | https://api.amplitude.com/otlp/v1/traces |
| 欧州連合 | https://api.eu.amplitude.com/otlp/v1/traces |
- プロトコル:OTLP over HTTPのみ。
http/protobufまたはhttp/jsonで、オプションでgzip可能。AmplitudeはOTLP/gRPCをサポートしていません。 - 認証:プロジェクトのAPIキーを
Bearerトークンとして、またはapi_keyクエリパラメータとして指定します。Amplitudeは、プロジェクトごとの有効化リクエストを必要としません。 - サポートされているインストルメンテーション:OpenTelemetry GenAIのセマンティック規約、OpenInference(
llm.*)、OpenLLMetryとTraceloop(traceloop.*)、OpenLIT、LiteLLM。Amplitudeは、GenAI以外のスパンを無視します。
属性の解決順序
Amplitudeは、存在する最初の属性をこの順序で読み取ります。
| シグナル | Amplitudeが読み取る属性(順序通り) |
|---|---|
| セッション | gen_ai.conversation.id、session.id、traceloop.association.properties.session(またはchat、thread、conversation)、gen_ai.session.id、次にリソースsession.idおよびgen_ai.conversation.id。これらのいずれもない場合、AmplitudeはトレースIDにフォールバックし、セッションを劣化としてマークします。Claudeネイティブのスパンは例外です。anthropic.session.idがセッションであり、異なるgen_ai.conversation.idはスレッドとして保持されます。 |
| ユーザー | enduser.id、gen_ai.request.user、gen_ai.user、user.id、traceloop.association.properties.user、リソースenduser.idおよびuser.id、次にLiteLLMのmetadata.user_api_key_end_user_id。これらのいずれもない場合、ユーザーはにunknown解決されます。 |
| エージェント | gen_ai.agent.id、それ以外はリソースservice.name。Claude-nativeのスパンはservice.nameにフォールバックされないため、claude-platformはエージェントとして保存されません。 |
| 親エージェント | スパン属性amplitude.parent.agent.idのみ。親スパンIDとリソース属性は、親エージェントではありません。 |
| 環境 | deployment.environment、スパンまたはリソース上。 |
何が何にマップされるか
| OpenTelemetryのソース | [Agent] 結果 |
|---|---|
chat のtext_completion、gen_ai.operation.name、または generate_content | [Agent] AI Response、プラス新しい入力メッセージから[Agent] User Message合成された |
execute_tool の gen_ai.operation.name | [Agent] Tool Call、、gen_ai.tool.name、gen_ai.tool.call.id、引数、および結果 |
その他の任意の操作(invoke_agent、retrieval、plan、またはメモリ操作など) | [Agent] Span |
gen_ai.request.model, gen_ai.response.model | [Agent] Model Name |
gen_ai.provider.name、または非推奨の gen_ai.system | [Agent] Provider |
gen_ai.usage.input_tokens、gen_ai.usage.output_tokens、およびreasoning属性とキャッシュトークン属性 | トークンのプロパティ |
gen_ai.usage.cost | [Agent] Cost USD。 これはAmplitudeの拡張機能です。OpenTelemetryはコストを標準化していないため、ほとんどのインストルメンテーションではこの値が省略されています。 |
gen_ai.response.finish_reasons | [Agent] Finish Reason |
gen_ai.input.messages, gen_ai.output.messages | $llm_message |
gen_ai.system_instructions、またはsystem-roleメッセージ | [Agent] System Prompt AIレスポンスについて |
スパンのステータス ERROR | [Agent] Is Error, [Agent] Error Message |
trace_id、span_id、parent_span_id、開始時刻、期間 | [Agent] Trace ID、[Agent] Span ID、[Agent] Parent Span ID、イベントのタイムスタンプ、[Agent] Latency Ms |
amplitude.parent.agent.id | [Agent] Parent Agent ID |
| 合成されたユーザーメッセージから派生します。 | [Agent] Message Source:明示的なamplitude.message.sourceが優先されます。そうでない場合は、親エージェントが存在する場合はagent、それ以外の場合はuser |
Amplitudeは、gen_ai.usage.costが不在の場合にコストを計算しません。コストの計算方法を参照してください。
チャット呼び出しはプロンプト履歴全体を再送信するため、最後のアシスタントメッセージの後のユーザーメッセージのみが新しいになります[Agent] User Message。 Amplitudeはリプレイされた履歴を再出力しません。また、新しい入力がツールの結果であるtool-loopの継続は、ユーザーのTurnを生成しません。
AI SDKのプロセス内OpenTelemetryエクスポータは、独自のマッピングを使用しています。SDKリファレンスのOpenTelemetry属性マッピングを参照してください。
機能フラグの属性
Amplitudeは、GenAIスパンからOpenTelemetry機能フラグの評価を読み取り、それぞれを実験として記録します。 まずすべてのfeature_flag.evaluationスパンイベントを読み取り、次にスパン自身のfeature_flag.*属性を読み取ります。リソース属性はカウントされません。
| OpenTelemetryのソース | 実験フィールド |
|---|---|
feature_flag.key | キー |
feature_flag.result.variant、またはより古いfeature_flag.variant | バリアント |
feature_flag.provider.name、またはより古いfeature_flag.provider_name | プロバイダー |
agent_session〜amplitude.experiment.unitの、またはturn〜 | 単位。 それがなければ、またはその他を指定した場合、単位はspan〜です。 |
このスパンが生成するすべてのイベントには[Agent] Experimentsが含まれ、評価がちょうど1つ残っている場合は、さらに[Agent] Experiment Key、Variant、Unit、Providerも含まれます。エラーを返したようなバリアントのない評価では、何も追加されません。 2つの評価がキーを共有している場合、後者の方が勝ちます。そのため、span属性は同じキーを持つspanイベントを上書きします。 検証ルールと10個の実験制限は、AI SDKと一致します。 Agent Analyticsの実験バリアントの記録を参照してください。
Claude Platformのスパン
Amplitudeは、スパン名がanthropic.で始まり、スパンに、gen_ai.provider.name=anthropic、com.anthropic.claude-platformまたはcom.anthropic.sdkインストルメンテーションスコープ、またはリソースservice.name=claude-platformも含まれる場合にのみ、これらのルールを適用します。 汎用invoke_agentスパンと、その他の名前を持つAnthropicチャットスパンは上記のマッピングに残ります。
| Claudeスパン | [Agent] 結果 |
|---|---|
anthropic.messages.create | ユーザーメッセージとAIレスポンス。 この範囲は、トークンの合計を維持します。 |
Messages APIのanthropic.model_request | [Agent] Span 使用状況が削除されたため、親の合計は再びカウントされません。 |
anthropic.session.turn メッセージテキスト付き | ユーザーメッセージとAIレスポンス。これらのイベントにコピーされた使用状況はありません。 |
anthropic.session.turn メッセージテキストなし | [Agent] Span、使用状況は削除されました。 |
gen_ai.operation.name=chatを伴うanthropic.model_request | [Agent] Span これは、model、tokens、cache、latency、errorを保持します。 いくつかのモデルリクエストは、それぞれ独自の使用法を保持します。 |
anthropic.tool_use、anthropic.mcp_tool_useまたはanthropic.custom_tool_useで始まるSpan名 | [Agent] Tool Callはanthropic.tool_result.contentツールの出力です。anthropic.mcp.server.nameは追加のプロパティとして保持されます。 |
anthropic.test | 受け入れられ、廃棄されました。 この値は、ライブイベントには表示されません。 |
gen_ai.response.finish_reasonsが存在しない場合、anthropic.message.stop_reason、ついでanthropic.session.turn.stop_reasonがAIレスポンス上の[Agent] Finish Reasonになります。Amplitudeはenduser.idまたはgen_ai.usage.costを発明しません。親スパンIDは階層を維持します。それらは[Agent] Parent Agent IDではありません。
送信先を追加するには、Send Claude Platformのトレースを参照してください。
配信、制限、およびレスポンス
配信は少なくとも1回です。永続的な送信キューを使用してコレクタを実行し、再試行は有効なままにします。メモリ内キューは、再起動時にバッファリングされたスパンを失います。
| 制限 | 行動 |
|---|---|
| 4MBの解凍済みリクエスト本文 | 413 |
| エクスポートあたり2,000件の翻訳済みイベント | 413。 コレクタのバッチサイズを小さくします。 |
| レスポンス | 意味 |
|---|---|
200 | 承認されました。partial_successボディは、取り込みが拒否した任意のイベントを報告します。注意してください。これはコレクタにバッチを削除するように200指示しているためです。 |
400 | 不正なリクエスト本文またはOTLPペイロード。 再試行不可。 |
401 | APIキーがありません、または無効です。 |
415 | application/x-protobufまたはapplication/json以外のコンテンツタイプ。 |
503 | ダウンストリームの取り込みの中断を含む、一時的なものです。 コレクタは、そのキューから再試行する必要があります。 |
OTLPレシーバーは決して403を返しません。CDNやWAFなどの別のホップからのものは、Amplitudeが有効になっていないの403ではなく、設定エラーとして扱ってください。
これは役に立ちましたか?
For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.