Mastraのトレースをエージェント分析に送信する
Mastraは、@mastra/otel-exporterを通してOpenTelemetry GenAIのスパンを発行します。そのエクスポータをAmplitudeに向けます。エージェントプロセスではAmplitude AI SDKは必要ありません。
このページでは、@mastra/core 1.79.0、@mastra/observability 1.21.0、および@mastra/otel-exporter 1.4.9について説明します。Amplitudeは、エクスポートしたスパンを保存します。 個人データがインフラストラクチャを離れる前に、秘匿化してください。エージェント分析のプライバシーモードを参照してください。
AIコーディングエージェントを使用した設定(推奨)
このプロンプトを、Cursor、Claude Code、Windsurf、GitHub Copilot、Codex などの AI コーディングエージェントに貼り付けます。
Connect this Mastra agent to Amplitude Agent Analytics with native OpenTelemetry.
Fetch https://raw.githubusercontent.com/amplitude/Amplitude-AI-Node/main/docs/integrations/mastra.md
and follow "Part 2: Coding agent procedure".
If @amplitude/ai is installed, the same file is under node_modules/@amplitude/ai/docs/integrations/.
Also follow https://raw.githubusercontent.com/amplitude/Amplitude-AI-Node/main/docs/integrations/privacy.md
and scrub content before export.
Follow links in the guide. If your source isn't listed, start at https://raw.githubusercontent.com/amplitude/Amplitude-AI-Node/main/docs/integrations/README.md
変更を確認し、「Get started」の手順に従って検証します。
必要な対応
- 実行するもの:Mastraプロセス(
@mastra/otel-exporterをAmplitudeに向けてポイントします)。logsシグナルをオフにします。 Amplitudeにはlogsルートはありません。 - 必要なもの:
@mastra/core@1.79.0、@mastra/observability@1.21.0、@mastra/otel-exporter@1.4.9、AmplitudeプロジェクトのAPIキー、userIdおよびすべての生成呼び出しのsessionId。 - プロトコル:OTLP over HTTP。 AmplitudeはprotobufとJSONを受け入れます。 AmplitudeはgRPCを受け入れません。
- プライバシー:Amplitude は、受信後にコンテンツをスクラブ(匿名化)しません。
tracingOptions.hideInputおよびhideOutputによってメッセージテキストとツール引数はドロップされます。userId、sessionId、ツール名、モデル、および両方のトークンカウント数は引き続き届きます。エクスポートする前に、コンテンツの属性をマスクまたはドロップします。
エクスポート
エージェントプロセスでこれらの変数を設定します。 環境変数に値がある場合、ヘッダー値内のスペースは%20としてエンコードします。Authorization=の記述は変更しないでください。
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://api.amplitude.com/otlp/v1/traces
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer%20<project API key>"
OTEL_SERVICE_NAME=order-support
EU地域のデータレジデンシーの場合はhttps://api.eu.amplitude.com/otlp/v1/tracesを使用します。
OtelExporterをprotocol: "http/protobuf"とsignals: { traces: true, logs: false }とともに登録します。すべてのgenerate呼び出しでtracingOptions.metadata.userIdおよびtracingOptions.metadata.sessionIdを渡します。
アイデンティティ
| 属性 | 値 |
|---|---|
mastra.metadata.sessionId | 会話、スレッド、またはチケットID。 すべてのターンで同じ値を使用します。Amplitudeはそれをsession.idにマッピングします。 |
mastra.metadata.userId | プロダクト分析で既に使用されているユーザーID。Amplitudeはそれをuser.idにマップし、欠落しているユーザーをunknownとして保存します。 |
gen_ai.agent.id | このエージェントの安定した名前。Mastraは、エージェントidからこれを設定します。 Amplitudeはgen_ai.agent.nameを読み取りません。 |
引き継がれる内容
| Mastraのスパン | Amplitudeイベント |
|---|---|
モデル呼び出し(chat) | [Agent] AI Response、さらに最後のアシスタントメッセージの後に続く新しいユーザーメッセージごとに[Agent] User Message |
ツール(execute_tool) | [Agent] Tool Call |
| エージェント、ステップ、およびプロセッサのスパン | [Agent] Span |
ツールループが継続する場合、以前のユーザーテキストがgen_ai.input.messages内で繰り返されます。Amplitudeは、以前のユーザーメッセージを再度送信しません。 ツールの出力は[Agent] Tool Outputです。
セッションを閉じる
[Agent] Session Endはオプションであり、推奨されます。ネイティブのMastraエクスポートはこれを送信しません。 Amplitudeは、デフォルトで条件を満たすエージェントイベントなしで30分後にセッションを終了します。また、セッションごとのオーバーライドが設定されていない場合は、セッション開始から24時間後にセッションが終了します。最初に発生した終了がカウントされます。セッションレコードとコンテンツベースのシグナルを含むエンリッチメントは、その終了後に一度実行されます。OpenTelemetryトランスレータは、スパンからidle-timeout属性を読み取ることはありません。 セッションの終了方法を参照してください。
今すぐ始める
Mastra連携ガイドに従ってください。 同じセッションIDを使用して2つのターンを送信し、ライブイベントで確認します。
- セッションIDはメタデータセッションIDであり、トレースIDではありません。
- ユーザーIDはプロダクト分析ユーザーであり、
unknownではありません。 - エージェントIDは
gen_ai.agent.idです。 - ターンには、ユーザーメッセージのテキスト、ツール呼び出し、AIレスポンスのテキストが表示されます。また、モデル名と両方のトークン数も含まれます。
- 2番目のターンでは、最初のユーザーメッセージは複製されません。
Guideは2026年10月28日に、@mastra/core1.79.0、@mastra/observability1.21.0、および@mastra/otel-exporter1.4.9に対して最後に検証されました。Mastraは、その所有者の商標です。 Amplitudeは、その所有者と提携していません。また、その所有者によって承認されていません。
これは役に立ちましたか?
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.