---
title: "Mastra"
description: "Learn how to send Mastra agent traces, model calls, and tool executions to Sentry."
url: https://docs.sentry.io/platforms/javascript/guides/mastra/
---

# Mastra | Sentry for Mastra

[Mastra](https://mastra.ai/) is a TypeScript framework for building AI applications and agents. This guide configures Mastra's `@mastra/sentry` exporter to send agent runs, model generations, tool calls, and workflows to [Sentry Agent Tracing](https://docs.sentry.io/product/agents.md).

The exporter uses `@sentry/node` internally, so it can send Mastra telemetry directly to a Sentry project without another Sentry SDK.

## [Prerequisites](https://docs.sentry.io/platforms/javascript/guides/mastra.md#prerequisites)

Before you begin, you need:

* A Sentry [account](https://sentry.io/signup/) and [project](https://docs.sentry.io/product/projects.md). 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 Mastra Sentry exporter does not support browser or edge runtimes.

## [Install](https://docs.sentry.io/platforms/javascript/guides/mastra.md#install)

Install the Mastra Sentry exporter and observability packages:

```bash
npm install @mastra/sentry@latest @mastra/observability@latest
```

*Other available variations of the above snippet: yarn, pnpm*

You don't need to install or initialize `@sentry/node` separately for this setup. The exporter includes it as a dependency and initializes it for you.

## [Configure](https://docs.sentry.io/platforms/javascript/guides/mastra.md#configure)

Add your Sentry DSN to the environment. You can find it in **Project Settings > Client Keys (DSN)**.

```bash
SENTRY_DSN=https://<key>@o<orgId>.ingest.sentry.io/<projectId>
```

Add the Sentry exporter to your Mastra observability configuration:

```typescript
import { Mastra } from "@mastra/core";
import { Observability } from "@mastra/observability";
import { SentryExporter } from "@mastra/sentry";

export const mastra = new Mastra({
  // agents, workflows, ...
  observability: new Observability({
    configs: {
      sentry: {
        serviceName: "my-mastra-service",
        exporters: [
          new SentryExporter({
            tracesSampleRate: 1.0,
          }),
        ],
      },
    },
  }),
});
```

Mastra sends agent data to Sentry as traces. Keep `tracesSampleRate` above `0` to enable tracing. The example sends every trace so you can verify the setup; lower the value in production if needed.

The exporter also reads `SENTRY_ENVIRONMENT` and `SENTRY_RELEASE` when those environment variables are set. You can instead pass `dsn`, `environment`, and `release` directly to `SentryExporter`.

##### Using Mastra With a Framework or Different Runtime?

This setup covers telemetry produced by Mastra. If a frontend or another service communicates with a separate Mastra server, configure that application with its own [JavaScript framework guide](https://docs.sentry.io/platforms/javascript.md) and use this guide for the Mastra service.

`@mastra/sentry` initializes `@sentry/node` internally. If Mastra runs in the same process as an application that already calls `Sentry.init()`, don't initialize Sentry a second time without first confirming that the two SDK setups are compatible.

## [Verify](https://docs.sentry.io/platforms/javascript/guides/mastra.md#verify)

Run one of your Mastra agents, then open the **Agents** page in your Sentry project. You should see an agent run with its model generations, tool calls, token usage, and any related errors.

If no data appears, confirm that:

* `SENTRY_DSN` belongs to the Sentry project you're viewing.
* `tracesSampleRate` is greater than `0`.
* Your application completed at least one agent run after you added the exporter.

## [Next Steps](https://docs.sentry.io/platforms/javascript/guides/mastra.md#next-steps)

* [Name your agents](https://docs.sentry.io/product/agents/naming.md) so you can identify them in the Agents Dashboard.
* Add a stable thread ID to group multi-turn chats in [Conversations](https://docs.sentry.io/product/agents/conversations.md). Mastra maps `metadata.threadId` to `gen_ai.conversation.id`.
* Review the [Mastra Sentry exporter reference](https://mastra.ai/integrations/observability/sentry).
* Use the appropriate [JavaScript framework guide](https://docs.sentry.io/platforms/javascript.md) for application monitoring in a separate frontend or service.

What gets captured?

Mastra maps its span types to Sentry operations for the Agents dashboards:

| Mastra Span Type       | Sentry Operation       |
| ---------------------- | ---------------------- |
| `AGENT_RUN`            | `gen_ai.invoke_agent`  |
| `MODEL_GENERATION`     | `gen_ai.chat`          |
| `TOOL_CALL`            | `gen_ai.execute_tool`  |
| `MCP_TOOL_CALL`        | `gen_ai.execute_tool`  |
| `WORKFLOW_RUN`         | `workflow.run`         |
| `WORKFLOW_STEP`        | `workflow.step`        |
| `WORKFLOW_CONDITIONAL` | `workflow.conditional` |
| `WORKFLOW_PARALLEL`    | `workflow.parallel`    |
| `WORKFLOW_LOOP`        | `workflow.loop`        |
| `PROCESSOR_RUN`        | `ai.processor`         |
| `GENERIC`              | `ai.span`              |

`MODEL_STEP` and `MODEL_CHUNK` spans are skipped. Their data is aggregated into parent `MODEL_GENERATION` spans.

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

## [Supported Versions](https://docs.sentry.io/platforms/javascript/guides/mastra.md#supported-versions)

* `@mastra/sentry`: `>=1.0.0`
* Node.js: `>=22.13.0`