Send Mastra traces to Agent Analytics

이 페이지는 아직 귀하의 언어로 번역되지 않았습니다. 현재 작업 중이므로 곧 다시 확인해 주십시오.

Mastra emits OpenTelemetry GenAI spans through @mastra/otel-exporter. Point that exporter at Amplitude. You don't need the Amplitude AI SDK in the agent process.

This page covers @mastra/core 1.79.0, @mastra/observability 1.21.0, and @mastra/otel-exporter 1.4.9. Amplitude stores the spans you export. Scrub personal data before it leaves your infrastructure. Refer to Agent Analytics privacy modes.

Set up with your AI coding agent (recommended)

Paste this prompt into your AI coding agent, such as Cursor, Claude Code, Windsurf, GitHub Copilot, or Codex.

text

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

Review the changes, then verify with the steps in Get started.

What this means for you

You run: The Mastra process, with @mastra/otel-exporter pointed at Amplitude. Turn the logs signal off. Amplitude has no logs route.
You need: @mastra/core@1.79.0, @mastra/observability@1.21.0, @mastra/otel-exporter@1.4.9, your Amplitude project API key, and userId plus sessionId on every generate call.
Protocol: OTLP over HTTP. Amplitude accepts protobuf and JSON. Amplitude doesn't accept gRPC.
Privacy: Amplitude doesn't scrub content after receipt. tracingOptions.hideInput and hideOutput drop message text and tool arguments. userId, sessionId, the tool name, the model, and both token counts still arrive. Mask or drop content attributes before export.

Export

Set these variables in the agent process. Encode the space in the header value as %20 when the value is in an environment variable. Leave Authorization= as written.

bash

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 data residency uses https://api.eu.amplitude.com/otlp/v1/traces.

Register OtelExporter with protocol: "http/protobuf" and signals: { traces: true, logs: false }. Pass tracingOptions.metadata.userId and tracingOptions.metadata.sessionId on every generate call.

Identity

Attribute	Value
`mastra.metadata.sessionId`	The conversation, thread, or ticket ID. Use the same value on every turn. Amplitude maps it to `session.id`.
`mastra.metadata.userId`	The user ID product analytics already uses. Amplitude maps it to `user.id` and stores a missing user as `unknown`.
`gen_ai.agent.id`	A stable name for this agent. Mastra sets this from the agent id. Amplitude doesn't read `gen_ai.agent.name`.

What carries over

Mastra span	Amplitude event
Model invocation (`chat`)	`[Agent] AI Response`, plus an `[Agent] User Message` for each new user message after the last assistant message
Tool (`execute_tool`)	`[Agent] Tool Call`
Agent, step, and processor spans	`[Agent] Span`

A tool-loop continuation repeats the earlier user text inside gen_ai.input.messages. Amplitude doesn't emit that earlier user message again. Tool output is [Agent] Tool Output.

Session close

[Agent] Session End is optional and recommended. A native Mastra export doesn't send it. Amplitude closes the session after 30 minutes without a qualifying agent event by default, and 24 hours from the session start when no per-session override is set. The first close is the one that counts. Enrichment, including the Session Record and content-based signals, runs once after that close. The OpenTelemetry translator doesn't read an idle-timeout attribute from a span. Refer to How sessions close.

Get started

Follow the Mastra integration guide. Send two turns with the same session id, then confirm in Live Events:

Session ID is the metadata session id, not a trace ID.
User ID is the product-analytics user, not unknown.
Agent ID is gen_ai.agent.id.
The turn shows User Message text, the tool call, and AI Response text, with the model name and both token counts.
The second turn doesn't duplicate the first user message.

Guide last verified on October 28, 2026, against @mastra/core 1.79.0, @mastra/observability 1.21.0, and @mastra/otel-exporter 1.4.9. Mastra is a trademark of its owner. Amplitude isn't affiliated with or endorsed by that owner.

이 내용이 도움이 되었나요?