Mastra
Learn how to export Mastra AI tracing to Sentry.
Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack. The Mastra Sentry Exporter sends tracing data to Sentry using OpenTelemetry semantic conventions, providing insights into model performance, token usage, and tool executions.
Before you begin, you need:
- A Sentry account and project. The project's DSN tells the exporter where to send data.
- A Mastra application using
@mastra/core. - Node.js 22.13.0 or newer. The exporter uses
@sentry/nodeinternally and does not support browser or edge runtimes.
Mastra sends agent data as traces. Keep tracesSampleRate above 0 to enable tracing.
Install the Mastra Sentry exporter and observability packages:
npm install @mastra/sentry@latest @mastra/observability@latest
npm install @mastra/sentry@latest @mastra/observability@latest
yarn add @mastra/sentry@latest @mastra/observability@latest
pnpm add @mastra/sentry@latest @mastra/observability@latest
You don't need to install or initialize @sentry/node separately for this standalone setup. The exporter includes it as a dependency and initializes it for you.
The Sentry exporter can automatically read configuration from environment variables (SENTRY_DSN, SENTRY_ENVIRONMENT, SENTRY_RELEASE):
import { Mastra } from "@mastra/core";
import { Observability } from "@mastra/observability";
import { SentryExporter } from "@mastra/sentry";
export const mastra = new Mastra({
observability: new Observability({
configs: {
sentry: {
serviceName: "my-service",
exporters: [new SentryExporter()],
},
},
}),
});
import { Mastra } from "@mastra/core";
import { Observability } from "@mastra/observability";
import { SentryExporter } from "@mastra/sentry";
export const mastra = new Mastra({
observability: new Observability({
configs: {
sentry: {
serviceName: "my-service",
exporters: [new SentryExporter()],
},
},
}),
});
You can also pass configuration directly:
import { Mastra } from "@mastra/core";
import { Observability } from "@mastra/observability";
import { SentryExporter } from "@mastra/sentry";
export const mastra = new Mastra({
observability: new Observability({
configs: {
sentry: {
serviceName: "my-service",
exporters: [
new SentryExporter({
dsn: process.env.SENTRY_DSN,
environment: "production",
tracesSampleRate: 1.0,
}),
],
},
},
}),
});
import { Mastra } from "@mastra/core";
import { Observability } from "@mastra/observability";
import { SentryExporter } from "@mastra/sentry";
export const mastra = new Mastra({
observability: new Observability({
configs: {
sentry: {
serviceName: "my-service",
exporters: [
new SentryExporter({
dsn: process.env.SENTRY_DSN,
environment: "production",
tracesSampleRate: 1.0,
}),
],
},
},
}),
});
Exports a tracing event to Sentry. Handles SPAN_STARTED, SPAN_UPDATED, and SPAN_ENDED events.
await exporter.exportTracingEvent(event);
await exporter.exportTracingEvent(event);
Force flushes any pending spans to Sentry without shutting down the exporter. Waits up to 2 seconds for pending data to be sent. Useful in serverless environments where you need to ensure spans are exported before the runtime terminates.
await exporter.flush();
await exporter.flush();
Ends all active spans, clears internal state, and closes the Sentry connection. Waits up to 2 seconds for pending data to be sent.
await exporter.shutdown();
await exporter.shutdown();
For a standalone setup walkthrough, see the Sentry guide for Mastra. For complete exporter documentation, see the Mastra Sentry Exporter documentation.
@mastra/sentry:>=1.0.0- Node.js:
>=22.13.0
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").