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

# Cloudflare Quick Start | Sentry for Mastra

[Mastra](https://mastra.ai/) is a TypeScript framework for building AI applications and agents. This guide sets up the Sentry SDK in a Mastra app running on Cloudflare Workers so agent runs, model generations, tool calls, workflows, and errors flow into [Sentry Agent Tracing](https://docs.sentry.io/product/agents.md).

This guide covers the Sentry SDK-based setup, which replaces the earlier `@mastra/sentry` exporter. It requires JavaScript SDK version `11.0.0-rc.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 Node.js? Follow the [Mastra Quick Start](https://docs.sentry.io/platforms/javascript/guides/mastra.md) instead.

## [Prerequisites](https://docs.sentry.io/platforms/javascript/guides/mastra/cloudflare.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 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/cloudflare` version `11.0.0-rc.0` or later.

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

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

Error Monitoring\[ ]Tracing

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

```bash
npm install @sentry/cloudflare@^11.0.0-rc.0 @mastra/observability@latest
```

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

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

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

Add the Sentry Vite plugin to your Vite config. It wraps your Worker entry with Sentry at build time:

```typescript
import { cloudflare } from "@cloudflare/vite-plugin";
import { sentryCloudflareVitePlugin } from "@sentry/cloudflare/vite";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [cloudflare(), sentryCloudflareVitePlugin()],
});
```

Create an `instrument.server.ts` file next to your Worker entry (the file named in Wrangler's `main`). The plugin picks it up by convention and uses its default export as the Sentry options:

```typescript
export default (env: Env) => ({
  dsn: "https://<key>@o<orgId>.ingest.sentry.io/<projectId>",
  // ___PRODUCT_OPTION_START___ performance

  // Set tracesSampleRate to 1.0 to capture 100%
  // of spans for tracing.
  // We recommend adjusting this value in production.
  tracesSampleRate: 1.0,
  // ___PRODUCT_OPTION_END___ performance
});
```

Enable Node.js compatibility in your `wrangler.toml` so Mastra and the SDK can run on Workers:

```toml
main = "src/index.ts"
compatibility_date = "2026-04-26"
compatibility_flags = ["nodejs_compat"]
```

With the plugin in place, `Sentry.init()` runs automatically — you don't add an instrument file or `--import` flag as you do for Node.js.

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 [Privacy Controls](https://docs.sentry.io/platforms/javascript/guides/mastra/cloudflare.md#privacy-controls) below.

### [Privacy Controls](https://docs.sentry.io/platforms/javascript/guides/mastra/cloudflare.md#privacy-controls)

The SDK will record generative AI inputs and outputs (the prompts your agent sends and the model responses it receives) by default. To turn recording off, set `genAI.inputs` and `genAI.outputs` to `false` in `dataCollection`:

```typescript
export default (env: Env) => ({
  dsn: "https://<key>@o<orgId>.ingest.sentry.io/<projectId>",
  dataCollection: {
    genAI: { inputs: false, outputs: false },
  },
});
```

See [`dataCollection` documentation](https://docs.sentry.io/platforms/javascript/guides/mastra/configuration/options.md#dataCollection) for details on privacy control options.

### [Link Conversations](https://docs.sentry.io/platforms/javascript/guides/mastra/cloudflare.md#link-conversations)

Sentry groups a multi-turn chat into a single [Conversation](https://docs.sentry.io/product/agents/conversations.md) 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:

```typescript
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.

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

Run one of your Mastra agents, then open [Agent Tracing](https://docs.sentry.io/product/agents.md) in Sentry and select the run. The timeline shows the model generations, tool calls, token usage, and latency for that run, plus 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.

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

* [Name your agents](https://docs.sentry.io/product/agents/naming.md) so you can identify them in the Agents Dashboard.
* [Track AI agent spend with dashboards and alerts](https://sentry.io/cookbook/monitor-ai-agent-spend-with-dashboards-and-alerts/): build a dashboard for cost, tokens, models, and conversations.
* 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?

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`   |

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

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

* `@sentry/cloudflare`: `>=11.0.0-rc.0`
* `@mastra/core`: `>=1.63.2`
* `@mastra/observability`: required for the integration to create spans