OpenTelemetryトレースをエージェント分析に送信する

AmplitudeのOTLPエンドポイントはOpenTelemetry GenAIスパンを受け入れ、それらをAI SDKが生成するのと同じ[Agent]イベントに変換します。そのため、セッション、エンリッチメント、およびすべてのチャートは同じように機能します。スタックがすでにGenAIスパンを発行している場合は、エクスポータにAmplitudeを指定します。 Amplitude SDKや新しいインストルメンテーションは必要ありません。

OpenTelemetryエクスポーターまたはコレクターをすでに実行している場合は、このパスを使用してください。代わりにAI SDKを使用してNodeまたはPythonアプリをインストルメントする場合は、SDKのプロセス内OTelエクスポーターを使用してください。これは別のパスです。開始する前に、セッションIDとプライバシーモードを決定します。

エクスポータを設定する

エクスポータまたはコレクタで次の環境変数を設定します。

bash
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://api.amplitude.com/otlp/v1/traces   # US
# OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://api.eu.amplitude.com/otlp/v1/traces  # EU
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <project API key>"
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf   # or http/json

OTLP HTTPエンドポイントは、米国とEUで一般的に利用できます。 有効なプロジェクトAPIキーだけで十分です。Amplitudeでは、プロジェクトごとに有効化をリクエストする必要はありません。また、許可リストがなくても、レシーバーが403を返すことはありません。

  • プロトコル:OTLP over HTTPのみ。Amplitudeは、http/protobuf(OpenTelemetry SDKおよびコレクタのデフォルト設定)とhttp/jsonに対応しており、gzip圧縮もオプションで使用できます。AmplitudeはOTLP/gRPCをサポートしていないため、OTLP/HTTPエクスポーターを使用して、ローカルのCollector経由でgRPCトラフィックをブリッジしてください。
  • 認証:プロジェクトのAPIキーをBearerトークンとして、またはapi_keyクエリパラメータとして渡します。
  • サポートされているインストルメンテーション:OpenTelemetry GenAIのセマンティック規約、OpenInference(llm.*)、OpenLLMetryおよびTraceloop(traceloop.*)、OpenLIT、LiteLLM。AmplitudeはGenAI以外のスパンを無視するため、混合するコレクタをAmplitudeにポイントできます。

Claude Platformのトレースを送信

ClaudeはすでにOpenTelemetryをエクスポートしています。AmplitudeをClaudeの送信先として追加します。このパスにはAmplitude SDKは必要ありません。

Claudeコンソールで、送信先のベースURLを地域ホストに設定します。Claudeによって/v1/tracesが付加されるため、ベースURLにそのパスは含まれません。

ヘッダーをAuthorization: Bearer <project API key>に設定します。

  • フルコンテンツはトランスクリプトを送信します。 マネージドエージェントターンにおけるユーザーとアシスタントのテキストは、[Agent] User Messageおよび[Agent] AI Responseになります。
  • メタデータのみにしても、モデル、トークン、レイテンシ、ツール呼び出し、エラーは送信されます。メッセージテキストのないターンは[Agent] Spanのままになります。
  • 1つのエクスポートパスを使用します。 Claude SDKとClaude Platformの両方が同じレスポンスをエクスポートする場合、Amplitudeは両方を保存します。
  • 送信先のテストアクションはanthropic.testを送信します。Amplitudeはそのスパンを受け入れますが、ライブイベントには表示されません。

Claudeセッションはanthropic.session.idです。gen_ai.conversation.idはそのセッション内のスレッドのままです。Messages APIスパンにはClaudeセッションIDがないため、セッション属性の順序が使用されます。 スパンのマッピングについては、Claude Platformのスパンを参照してください。

セッションとユーザーの属性を設定します。

セッション属性は、インストルメンテーションに加える価値のある変更です。Amplitudeは他のすべての情報を自動的にマッピングします。

Amplitudeエージェントセッションは、1つのトレースではなく、会話全体です。 会話属性がない場合、すべてのトレースは独自のシングルターンセッションになります。 その後、タスクの完了と放棄はノイズとして読み取られ、課金はエージェントセッションごとに行われるため、1 つの会話は複数として請求されます。

GenAIスパンに次の属性を設定します。

  • セッション:gen_ai.conversation.id、会話、チケット、または実行IDに設定します。セッションIDの選択を参照してください。
  • ユーザー:enduser.id、プロダクト分析に使用するのと同じユーザーIDに設定します。anonymousなどのプレースホルダは絶対に送信しないでください。ユーザーIDの設定を参照してください。
  • エージェント:gen_ai.agent.id、またはAmplitudeがservice.nameリソースにフォールバックします。
  • 親エージェント:スパン属性amplitude.parent.agent.id。親スパンIDは親エージェントではありません。また、Amplitudeはリソースから親エージェントを読み取りません。

Amplitudeは、session.idおよびTraceloop関連プロパティなど、他の一般的な属性も読み取ります。完全な解決順序については、「属性の解決順序」を参照してください。

コストをレポートする場合は、gen_ai.usage.costも設定します。この属性が指定されていない場合、Amplitudeはコストを計算しません。

A/Bテストまたは機能フラグのバリアントをスパンに記録するには、feature_flag.evaluationスパンイベントを追加するか、スパンにfeature_flag.keyとfeature_flag.result.variantを設定します。Amplitudeはそれらを[Agent] Experiment*プロパティにマップします。機能フラグの属性を参照してください。

プライバシーモードを適用する

ほとんどのOpenTelemetry GenAIインストルメンテーションは、メッセージコンテンツをオプトインとして扱います。

  • コンテンツのキャプチャがオフ:metadata_onlyになり、コスト、トークン、レイテンシ、モデル、およびセッションは取得できますが、トランスクリプトは含まれません。
  • コンテンツのキャプチャがオン:gen_ai.input.messages、gen_ai.output.messages、およびgen_ai.system_instructionsが、メッセージテキストと[Agent] System Promptになります。Amplitudeは、そのテキストをエクスポートされた状態で保存します。 Amplitudeは、受信後にそれを削除しません。 エクスポートする前に、これらの属性、およびツールの引数とツールの結果をスクラブしてください。Agent分析のプライバシーモードを参照してください。

データがネットワークから離れる前に実行しなければならないリダクションは、アプリケーションまたはコレクタプロセッサ内で行う必要があります。各モードの送信内容については、Agent分析のプライバシーモードを参照してください。

OTLPのみのパスでセッションを閉じる

[Agent] Session Endはオプションであり、推奨されます。OpenTelemetryのエクスポートでは、パイプラインによってそのイベントが追加されない限り、このイベントは送信されません。Amplitudeは、デフォルトでは条件を満たすエージェントイベントがない場合30分後に、セッションごとのオーバーライドが設定されていない場合はセッション開始から24時間後にセッションを終了します。エンリッチメントは、最初のクローズの後に1回だけ実行されます。OpenTelemetryトランスレータは、スパンからidle-timeout属性を読み取ることはありません。 ウィンドウを変更するには、HTTPの[Agent] Contextキーidle_timeout_minutesを送信するか、[Agent] Session Idle Timeout Minutesを使用して[Agent] Session Endを1件送信します。セッションの終了方法を参照してください。 エージェントフレームワークのガイドでは、この同じパスを使用します。 エージェントフレームワークを参照してください。

信頼性の高い配信を維持する

配信は少なくとも1回です。メモリ内キューは再起動時にバッファリングされたスパンを失うため、永続的な送信キューを使用してコレクタを実行し、再試行を有効にしてください。200レスポンスには、拒否されたイベントをリスト表示するpartial_successボディが含まれる場合があります。制限値とレスポンスコードについては、Delivery、Limits、Responsesを参照してください。

確認する

追跡された1つの会話を送信し、ライブイベントでイベントが次のように到着していることを確認します:

  1. トレースIDではなく、実際の[Agent] Session IDの値である。
  2. [Agent] Agent IDが入力されている。
  3. unknownではなく自身のユーザーIDである。

これら3つの値は、セッションおよびユーザー属性を設定する属性から取得されます。チェックリストの詳細については、「Agent分析のインストルメンテーションを確認する」を参照してください。

これは役に立ちましたか?

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.

このページでは