Sentry for Mastra

Learn how to send Mastra agent traces, model calls, tool executions, and errors to Sentry with the Sentry SDK.

Mastra is a TypeScript framework for building AI applications and agents. This guide sets up the Sentry SDK in a Mastra app so agent runs, model generations, tool calls, workflows, and errors flow into Sentry Agent Tracing.

This guide covers the Sentry SDK-based setup, which replaces the earlier @mastra/sentry exporter. It requires JavaScript SDK version 11.0.0 or later. If you previously used the @mastra/sentry exporter, remove it from your Mastra exporters — it calls Sentry.init() itself and conflicts with the built-in integration.

Running Mastra on Cloudflare Workers? Follow the Cloudflare Quick Start instead.

Before you begin, you need:

A Sentry account and project. The project's DSN tells the SDK where to send data.
A Mastra application using @mastra/core version 1.63.2 or later.
@mastra/observability. Sentry's Mastra integration needs it to attach to Mastra's telemetry pipeline.
@sentry/node version 11.0.0 or later, or @sentry/cloudflare@^11.0.0 when running on Cloudflare. Browser runtimes are not supported.

Choose the features you want to configure, and this guide will show you how:

Error MonitoringTracingProfiling

Install the Sentry Node SDK and Mastra's observability package:

Copied

npm install @sentry/node@^11.0.0 @mastra/observability@latest

npm install @sentry/node@^11.0.0 @mastra/observability@latest

yarn add @sentry/node@^11.0.0 @mastra/observability@latest

pnpm add @sentry/node@^11.0.0 @mastra/observability@latest

Copied

npm install @sentry/node@^11.0.0 @sentry/profiling-node@^11.0.0 @mastra/observability@latest

npm install @sentry/node@^11.0.0 @sentry/profiling-node@^11.0.0 @mastra/observability@latest

yarn add @sentry/node@^11.0.0 @sentry/profiling-node@^11.0.0 @mastra/observability@latest

pnpm add @sentry/node@^11.0.0 @sentry/profiling-node@^11.0.0 @mastra/observability@latest

If Mastra can't load @mastra/observability, the integration warns and creates no spans.

Create an instrument file that calls Sentry.init(), and preload it so Sentry starts before Mastra and the AI SDK load.

Place the file in your Mastra public/ directory. mastra build and mastra dev copy public/ into the build output, so the file lands next to the compiled server as instrument.mjs, where --import=./instrument.mjs can resolve it:

src/mastra/public/instrument.mjs

Copied

import * as Sentry from "@sentry/node";
// ___PRODUCT_OPTION_START___ profiling
import { nodeProfilingIntegration } from "@sentry/profiling-node";
// ___PRODUCT_OPTION_END___ profiling

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  // ___PRODUCT_OPTION_START___ profiling

  integrations: [
    // Add our Profiling integration
    nodeProfilingIntegration(),
  ],
  // ___PRODUCT_OPTION_END___ profiling
  // ___PRODUCT_OPTION_START___ performance

  // Set tracesSampleRate to 1.0 to capture 100%
  // of spans for tracing.
  // We recommend adjusting this value in production.
  // Learn more at
  // https://docs.sentry.io/platforms/javascript/guides/node/configuration/options/#tracesSampleRate
  tracesSampleRate: 1.0,
  // ___PRODUCT_OPTION_END___ performance
  // ___PRODUCT_OPTION_START___ profiling

  // Set profileSessionSampleRate to 1.0 to profile every session.
  // Learn more at
  // https://docs.sentry.io/platforms/javascript/configuration/options/#profileSessionSampleRate
  profileSessionSampleRate: 1.0,
  // ___PRODUCT_OPTION_END___ profiling
});

import * as Sentry from "@sentry/node";
// ___PRODUCT_OPTION_START___ profiling
import { nodeProfilingIntegration } from "@sentry/profiling-node";
// ___PRODUCT_OPTION_END___ profiling

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  // ___PRODUCT_OPTION_START___ profiling

  integrations: [
    // Add our Profiling integration
    nodeProfilingIntegration(),
  ],
  // ___PRODUCT_OPTION_END___ profiling
  // ___PRODUCT_OPTION_START___ performance

  // Set tracesSampleRate to 1.0 to capture 100%
  // of spans for tracing.
  // We recommend adjusting this value in production.
  // Learn more at
  // https://docs.sentry.io/platforms/javascript/guides/node/configuration/options/#tracesSampleRate
  tracesSampleRate: 1.0,
  // ___PRODUCT_OPTION_END___ performance
  // ___PRODUCT_OPTION_START___ profiling

  // Set profileSessionSampleRate to 1.0 to profile every session.
  // Learn more at
  // https://docs.sentry.io/platforms/javascript/configuration/options/#profileSessionSampleRate
  profileSessionSampleRate: 1.0,
  // ___PRODUCT_OPTION_END___ profiling
});

Preload the instrument file when you start Mastra by passing it through --custom-args:

package.json

Copied

{
  "scripts": {
    "dev": "mastra dev --custom-args=\"--import=./instrument.mjs\"",
    "start": "mastra start --custom-args=\"--import=./instrument.mjs\""
  }
}

{
  "scripts": {
    "dev": "mastra dev --custom-args=\"--import=./instrument.mjs\"",
    "start": "mastra start --custom-args=\"--import=./instrument.mjs\""
  }
}

With this setup, Sentry captures errors thrown by your agents and AI spans for every run (agent runs, model generations, tool calls, workflows, token usage, and latency) along with outgoing HTTP and fetch requests. Prompts and model outputs are recorded on your AI spans by default.

To review what's captured and turn recording of prompts and responses off, see Control the Data You Send to Sentry below.

By default, the SDK sends the inputs and outputs of your LLM and tool calls, such as prompts, responses, and tool arguments. This will give you rich debugging context. Review the data your agent handles before you deploy to production.

The SDK always filters sensitive values whose keys match a built-in denylist, such as auth or password, and sends [Filtered] instead.

To send less data, turn off the categories you don't need in the dataCollection option. For the full list of categories and their defaults, see the dataCollection options.

src/mastra/public/instrument.mjs

Copied

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  dataCollection: {
    genAI: { inputs: false, outputs: false },
  },
});

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  dataCollection: {
    genAI: { inputs: false, outputs: false },
  },
});

Sentry groups a multi-turn chat into a single Conversation automatically — there's no Sentry-specific setup. Mastra maps its memory thread id to gen_ai.conversation.id, so agent runs that share a thread id are grouped into one conversation.

Threads come from Mastra's own memory feature. If your app already passes a thread when it calls an agent — as multi-turn chat apps do — Sentry picks it up as the conversation id with no extra work:

Copied

const result = await agent.generate(message, {
  memory: {
    thread: "session-123",
    resource: "user-456",
  },
});

const result = await agent.generate(message, {
  memory: {
    thread: "session-123",
    resource: "user-456",
  },
});

Your agent needs a storage provider configured before Mastra accepts the memory option. Reuse the same thread id across the messages in a session.

Run one of your Mastra agents, then open Explore → Agents in Sentry. Select the trace to open its detail. The timeline shows the model generations, tool calls, token usage, latency, and any errors your agent threw.

If no data appears, confirm that:

The dsn belongs to the Sentry project you're viewing.
tracesSampleRate is greater than 0.
@mastra/observability is installed, so the integration can attach to Mastra's telemetry.
Your application completed at least one agent run after you added the setup.

Name your agents so you can identify them in the Agents Dashboard.
Track AI agent spend with dashboards and alerts: build a dashboard for cost, tokens, models, and conversations.
Use the appropriate JavaScript framework guide for application monitoring in a separate frontend or service.

What gets captured?

Sentry's Mastra integration maps Mastra's span types to Sentry operations for the Agents dashboards:

Mastra Span Type	Sentry Operation
`AGENT_RUN`	`gen_ai.invoke_agent`
`WORKFLOW_RUN`	`gen_ai.invoke_agent`
`MODEL_GENERATION`	`gen_ai.chat`
`TOOL_CALL`	`gen_ai.execute_tool`
`MCP_TOOL_CALL`	`gen_ai.execute_tool`
`PROVIDER_TOOL_CALL`	`gen_ai.execute_tool`
`CLIENT_TOOL_CALL`	`gen_ai.execute_tool`
`RAG_EMBEDDING`	`gen_ai.embeddings`
`CLASSIFIER_EVALUATION`	`gen_ai.evaluate`

Spans are tagged with sentry.origin: auto.ai.mastra.

@sentry/node: >=11.0.0
@sentry/cloudflare: >=11.0.0
@mastra/core: >=1.63.2
@mastra/observability: required for the integration to create spans

Was this helpful?

Help improve this content
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").

How to contribute | Edit this page | Create a docs issue | Get support