docs(javascript): rework Mastra guide to SDK-based setup, extend Node guide by mydea · Pull Request #19445 · getsentry/sentry-docs

mydea · 2026-09-16T14:59:17Z

DESCRIBE YOUR PR

Reworks the standalone Mastra JavaScript guide to the Sentry SDK-based setup, mirroring the Eve guide (#19310). Based on the node-mastra and cloudflare-mastra e2e test apps.

Extends the Node guide (fallbackGuide: javascript.node) instead of inheritCommonContent: false, so the Mastra guide inherits the Node common pages. Adds the mastra icon.
Replaces the @mastra/sentry exporter with a plain Sentry.init(). Sentry's Mastra integration is enabled by default and auto-bootstraps observability through @mastra/observability. Adds a warning against running the community @mastra/sentry exporter alongside it.
Node setup (primary): instrument.mjs in src/mastra/public/, preloaded via mastra dev/start --custom-args="--import=./instrument.mjs".
Cloudflare Workers (install variant): @sentry/cloudflare + sentryCloudflareVitePlugin() + src/instrument.server.ts + nodejs_compat.
Requires @sentry/node / @sentry/cloudflare >=11.0.0-rc.0 and @mastra/core >=1.63.2; updates the captured-span mapping to the built-in integration.
Adds javascript.mastra to every supported/notSupported list in JS common content wherever javascript.eve appears (112 files), so inherited Node sections render and browser-only content is hidden from the Mastra guide. PlatformSection doesn't resolve fallbackGuide, so javascript.mastra must be enumerated alongside javascript.node/javascript.eve in both directions.

IS YOUR CHANGE URGENT?

Help us prioritize incoming PRs by letting us know when the change needs to go live.
Select exactly one option. For deadlines, replace YYYY-MM-DD with the due date. You can update this information later by editing the PR description.

Urgent deadline (GA date, etc.): YYYY-MM-DD
Other deadline: YYYY-MM-DD
No deadline: Not urgent, can wait up to 1 week+

SLA

Teamwork makes the dream work, so please add a reviewer to your PRs.
Please give the docs team up to 1 week to review your PR unless you've supplied a deadline.

Thanks in advance for your help!

PRE-MERGE CHECKLIST

Make sure you've checked the following before merging your changes:

Checked Vercel preview for correctness, including links
PR was reviewed and approved by any necessary SMEs (subject matter experts)
PR was reviewed and approved by a member of the Sentry docs team

🤖 Generated with Claude Code

vercel · 2026-09-16T14:59:23Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
sentry-docs	Ready	Preview	Sep 21, 2026 7:19am UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
develop-docs	Ignored	Preview	Sep 21, 2026 7:19am UTC

s1gr1d · 2026-09-17T08:24:21Z

+
+The Sentry SDK instruments Mastra on its own — there's no exporter to register and no manual wiring. Sentry's Mastra integration is enabled by default and reads Mastra's AI telemetry, so a plain `Sentry.init()` is all you need.
+
+Running Mastra on Cloudflare Workers? Follow the [Cloudflare Quick Start](./cloudflare/) instead.


Maybe we should put this into a highlighted box.

I updated this generally a bit!

s1gr1d · 2026-09-17T08:32:58Z

+## Privacy Controls
+
+Generative AI inputs and outputs — the prompts your agent sends and the model responses it receives — are recorded on your AI spans by default. Review the data your agent handles and tighten this before production. To turn recording off, set `genAI.inputs` and `genAI.outputs` to `false` in `dataCollection`:
+
+```javascript {filename:src/mastra/public/instrument.mjs}
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  dataCollection: {
+    genAI: { inputs: false, outputs: false },
+  },
+});
+```


Other docs show this as part of the "configure" step, I think we could also move this up to be aligned.

https://docs.sentry.io/platforms/javascript/#control-the-data-you-send-to-sentry-optional

s1gr1d · 2026-09-17T08:34:42Z

+
+## Privacy Controls
+
+Generative AI inputs and outputs — the prompts your agent sends and the model responses it receives — are recorded on your AI spans by default. Review the data your agent handles and tighten this before production. To turn recording off, set `genAI.inputs` and `genAI.outputs` to `false` in `dataCollection`:


Keep in mind, that inputs and outputs handle more than just the prompts. Maybe also link to this page, without listing everything inline: https://docs.sentry.io/platforms/javascript/configuration/options/#dataCollection

From our docs:

For inputs: Include the content of generative AI inputs. This gates system instructions, prompt messages, tool definitions, and tool call arguments.

For outputs: Include the content of generative AI outputs (e.g. completion text, tool call results).

https://develop.sentry.dev/sdk/foundations/client/data-collection/#datacollection-options

btw, I opened a PR that updates the option docs so they are more detailed: https://github.com/getsentry/sentry-docs/pull/19454/changes#diff-96c5d3a51798dece73da3ce1b4537fac346e8bc11f5f331c57bcb48e6e7efeaaR157

updates this whole section a bit to reflect this better and link out!

s1gr1d · 2026-09-17T08:41:37Z

+});
+```
+
+## Link Conversations


Link Conversations and Next Steps is not part of the numbered view. Usually, the setup guides have numbered items until Next Steps.

moved this up, good point!

s1gr1d · 2026-09-17T08:43:36Z

+
+</StepConnector>
+
+## Privacy Controls


Privacy Controls and Link Conversations probably also works in Cloudflare. You could create a platform include and use this in both guides.

I updated this so it is more or less the same in cloudflare and node. moved this into includes!

RulaKhaled

https://sentry-docs-git-mastra-guide-sdk-setup.sentry.dev/platforms/javascript/guides/nextjs/agent-tracing/mastra/ this still references @mastra/sentry, could you also cover it?

RulaKhaled · 2026-09-17T10:44:02Z

RulaKhaled · 2026-09-17T10:44:22Z

 supported:
  - javascript.node
  - javascript.eve
+  - javascript.mastra


https://sentry-docs-git-mastra-guide-sdk-setup.sentry.dev/platforms/javascript/guides/nextjs/agent-tracing/mastra/ this still references @mastra/sentry, could you also cover this file?

removed this whole thing and redirecting to the guide now!

coolguyzone

Looks good, thanks for updating!

… guide Rework the standalone Mastra guide to the Sentry SDK-based setup (rc.0+), mirroring the Eve guide. - Extend the Node guide (fallbackGuide: javascript.node) instead of inheritCommonContent: false, with the mastra icon. - Replace the @mastra/sentry exporter approach with a plain Sentry.init(); Sentry's Mastra integration is enabled by default and needs @mastra/observability. - Document the Node setup (instrument.mjs in src/mastra/public, preloaded via mastra --custom-args="--import=./instrument.mjs") as primary, with a Cloudflare Workers install variant (@sentry/cloudflare + sentryCloudflareVitePlugin + instrument.server.ts + nodejs_compat), matching the node-mastra and cloudflare-mastra e2e test apps. - Require @sentry/node / @sentry/cloudflare >=11.0.0-rc.0 and @mastra/core >=1.63.2; update the captured-span mapping to the built-in integration. - Add javascript.mastra to every supported/notSupported list in JS common content wherever javascript.eve appears, so inherited Node sections render and browser-only content is hidden from the Mastra guide. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Co-authored-by: Sigrid <32902192+s1gr1d@users.noreply.github.com> Co-authored-by: Francesco Gringl-Novy <francesconovy@gmail.com>

…ptions - Rework the Mastra guide's quick start to mirror the Eve guide: StepConnector stepper and OnboardingOptionButtons (error-monitoring / performance / profiling, performance on by default), with profiling install/config variants. - Remove the old exporter-based agent-tracing/mastra.mdx subpage and redirect its routes (plus the older configuration/integrations and ai-agent-* aliases) directly to the standalone guide, matching how Eve was consolidated. - Surface Mastra and Eve as link-only entries in every JavaScript Agent Tracing sidebar that navigate straight to their standalone guides (platformSidebar.tsx), reusing the existing Cloudflare alias mechanism. The Agent Tracing index grid keeps the Mastra and Eve cards. - Note that users upgrading from the community @mastra/sentry exporter must remove it, and require @mastra/observability (no version pinned). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…stra Recovers the standalone Cloudflare Quick Start (a force-push had overwritten it) and reconciles it with the Node onboarding rework. - Re-add guides/mastra/cloudflare/index.mdx (sidebar_order 0.5) as a self-contained Cloudflare Workers quick start that links back to the default quick start. - Main quick start links to it ("Running Mastra on Cloudflare Workers? Follow the Cloudflare Quick Start instead.") and drops the inline Cloudflare Expandable; the Node onboarding options (performance default, profiling variants) stay. - Make the main prerequisites Node-only and note that both `mastra build` and `mastra dev` copy `public/`. - Clarify that Conversation linking is automatic via Mastra's memory thread id — no Sentry-specific setup. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

- Move Privacy Controls and Link Conversations under Configuration as h3 subsections in the main Mastra quick start. - Rework the Cloudflare Quick Start to mirror the main quick start's structure and content (onboarding options, stepper, Configure with Privacy Controls and Link Conversations subheadings, Verify, Next Steps, What gets captured, Supported Versions), with Cloudflare-specific snippets. Profiling is omitted since it isn't available on Workers. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Extract the content shared between the Node and Cloudflare Mastra quick starts into reusable includes under includes/mastra/ and reference them from both pages: - sdk-setup-alert, captured-summary, link-conversations, verify, next-steps, what-gets-captured. Page-specific content (install commands, instrument snippets, Privacy Controls code and its dataCollection link, Supported Versions) stays inline. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

The Mastra guide has its own dedicated quick start, so it no longer inherits the generic Agent Tracing provider pages. Remove javascript.mastra from the agent-tracing library pages (openai, anthropic, google-genai, langchain, langgraph, vercelai, manual-instrumentation, flue) so those pages are no longer generated under the Mastra guide. Keep javascript.mastra where the guide still inherits Node content: add it back alongside javascript.eve in the tracing Session Replay notSupported lists so browser-only content stays hidden from the Mastra guide. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Rename the destructured `guide` in the standalone-guide agent-tracing alias mapping so it no longer shadows the outer `guide` binding. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Co-authored-by: Alex Krawiec <alex.krawiec@sentry.io>

The Flue guide extends the Node guide through `fallbackGuide`, but `PlatformSection` doesn't resolve that, so `javascript.flue` has to be enumerated wherever `javascript.eve` already is — in both directions. Without it the inherited Node sections don't render in the Flue guide and browser-only content isn't hidden from it. 102 frontmatter entries and 37 PlatformSection arrays across 106 files, matching what #19445 does for `javascript.mastra`. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

… guide (#19445) ## DESCRIBE YOUR PR Reworks the standalone **Mastra** JavaScript guide to the Sentry SDK-based setup, mirroring the Eve guide (#19310). Based on the [`node-mastra`](https://github.com/getsentry/sentry-javascript/tree/develop/dev-packages/e2e-tests/test-applications/node-mastra) and [`cloudflare-mastra`](https://github.com/getsentry/sentry-javascript/tree/develop/dev-packages/e2e-tests/test-applications/cloudflare-mastra) e2e test apps. - **Extends the Node guide** (`fallbackGuide: javascript.node`) instead of `inheritCommonContent: false`, so the Mastra guide inherits the Node common pages. Adds the `mastra` icon. - **Replaces the `@mastra/sentry` exporter** with a plain `Sentry.init()`. Sentry's Mastra integration is enabled by default and auto-bootstraps observability through `@mastra/observability`. Adds a warning against running the community `@mastra/sentry` exporter alongside it. - **Node setup (primary):** `instrument.mjs` in `src/mastra/public/`, preloaded via `mastra dev/start --custom-args="--import=./instrument.mjs"`. - **Cloudflare Workers (install variant):** `@sentry/cloudflare` + `sentryCloudflareVitePlugin()` + `src/instrument.server.ts` + `nodejs_compat`. - Requires `@sentry/node` / `@sentry/cloudflare` `>=11.0.0-rc.0` and `@mastra/core` `>=1.63.2`; updates the captured-span mapping to the built-in integration. - Adds `javascript.mastra` to every `supported`/`notSupported` list in JS common content wherever `javascript.eve` appears (112 files), so inherited Node sections render and browser-only content is hidden from the Mastra guide. `PlatformSection` doesn't resolve `fallbackGuide`, so `javascript.mastra` must be enumerated alongside `javascript.node`/`javascript.eve` in both directions. ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. Select exactly one option. For deadlines, replace `YYYY-MM-DD` with the due date. You can update this information later by editing the PR description. - [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD - [ ] Other deadline: YYYY-MM-DD - [x] No deadline: Not urgent, can wait up to 1 week+ ## SLA - Teamwork makes the dream work, so please add a reviewer to your PRs. - Please give the docs team up to 1 week to review your PR unless you've supplied a deadline. Thanks in advance for your help! ## PRE-MERGE CHECKLIST _Make sure you've checked the following before merging your changes:_ - [ ] Checked Vercel preview for correctness, including links - [ ] PR was reviewed and approved by any necessary SMEs (subject matter experts) - [ ] PR was reviewed and approved by a member of the [Sentry docs team](https://github.com/orgs/getsentry/teams/docs) 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Co-authored-by: Sigrid <32902192+s1gr1d@users.noreply.github.com> Co-authored-by: Alex Krawiec <alex.krawiec@sentry.io>

github-actions Bot added the Priority: Normal Docs review has no urgent deadline label Sep 16, 2026

codeowner-assignment Bot requested a review from a team September 16, 2026 15:00

vercel Bot deployed to Preview – sentry-docs September 16, 2026 15:08 View deployment

logaretm approved these changes Sep 16, 2026

View reviewed changes

codeowner-assignment Bot requested a review from a team September 17, 2026 07:34

vercel Bot deployed to Preview – sentry-docs September 17, 2026 07:41 View deployment

mydea commented Sep 17, 2026

View reviewed changes

Comment thread docs/platforms/javascript/guides/mastra/index.mdx Outdated

vercel Bot deployed to Preview – sentry-docs September 17, 2026 08:03 View deployment

s1gr1d reviewed Sep 17, 2026

View reviewed changes

RulaKhaled reviewed Sep 17, 2026

View reviewed changes

mydea force-pushed the mastra-guide-sdk-setup branch from 0dbcde0 to a94ac37 Compare September 17, 2026 11:23

vercel Bot deployed to Preview – sentry-docs September 17, 2026 11:30 View deployment

mydea self-assigned this Sep 17, 2026

vercel Bot deployed to Preview – sentry-docs September 17, 2026 12:29 View deployment

vercel Bot deployed to Preview – develop-docs September 17, 2026 12:41 View deployment

vercel Bot deployed to Preview – sentry-docs September 17, 2026 12:45 View deployment

mydea force-pushed the mastra-guide-sdk-setup branch from 1211929 to 5bda762 Compare September 17, 2026 12:49

vercel Bot deployed to Preview – develop-docs September 17, 2026 12:52 View deployment

vercel Bot deployed to Preview – sentry-docs September 17, 2026 12:57 View deployment

vercel Bot deployed to Preview – sentry-docs September 18, 2026 07:24 View deployment

mydea force-pushed the mastra-guide-sdk-setup branch from f29b796 to f232f6c Compare September 18, 2026 07:24

vercel Bot deployed to Preview – sentry-docs September 18, 2026 07:32 View deployment

vercel Bot deployed to Preview – sentry-docs September 18, 2026 07:49 View deployment

mydea marked this pull request as ready for review September 18, 2026 07:58

codeowner-assignment Bot requested a review from a team September 18, 2026 07:59

vercel Bot deployed to Preview – sentry-docs September 18, 2026 08:05 View deployment

mydea force-pushed the mastra-guide-sdk-setup branch from 8dccef0 to 67ad3bb Compare September 18, 2026 08:08

vercel Bot deployed to Preview – sentry-docs September 18, 2026 08:18 View deployment

sentry Bot reviewed Sep 18, 2026

View reviewed changes

Comment thread src/components/sidebar/platformSidebar.tsx

vercel Bot deployed to Preview – develop-docs September 18, 2026 08:25 View deployment

vercel Bot deployed to Preview – sentry-docs September 18, 2026 08:28 View deployment

s1gr1d approved these changes Sep 18, 2026

View reviewed changes

coolguyzone reviewed Sep 18, 2026

View reviewed changes

Comment thread includes/mastra/link-conversations.mdx Outdated

coolguyzone approved these changes Sep 18, 2026

View reviewed changes

codeowner-assignment Bot requested a review from a team September 21, 2026 06:59

sentry Bot reviewed Sep 21, 2026

View reviewed changes

Comment thread src/components/sidebar/platformSidebar.tsx

vercel Bot deployed to Preview – sentry-docs September 21, 2026 07:06 View deployment

mydea and others added 11 commits September 21, 2026 09:11

Apply batched suggestions from code review

6a26bf3

Co-authored-by: Sigrid <32902192+s1gr1d@users.noreply.github.com> Co-authored-by: Francesco Gringl-Novy <francesconovy@gmail.com>

some fixes

b6e4533

update

dcd27cf

docs(javascript): fix eslint no-shadow in Mastra sidebar aliases

e334d35

Rename the destructured `guide` in the standalone-guide agent-tracing alias mapping so it no longer shadows the outer `guide` binding. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Update includes/mastra/link-conversations.mdx

bda0708

Co-authored-by: Alex Krawiec <alex.krawiec@sentry.io>

mydea force-pushed the mastra-guide-sdk-setup branch from c0fb579 to bda0708 Compare September 21, 2026 07:11

vercel Bot deployed to Preview – sentry-docs September 21, 2026 07:19 View deployment

mydea merged commit 9e60b4e into master Sep 21, 2026
24 checks passed

mydea deleted the mastra-guide-sdk-setup branch September 21, 2026 07:28

RulaKhaled mentioned this pull request Sep 21, 2026

docs(javascript): Give Flue its own guide with SDK-based setup #19528

Merged

1 of 6 tasks


		The Sentry SDK instruments Mastra on its own — there's no exporter to register and no manual wiring. Sentry's Mastra integration is enabled by default and reads Mastra's AI telemetry, so a plain `Sentry.init()` is all you need.

		Running Mastra on Cloudflare Workers? Follow the [Cloudflare Quick Start](./cloudflare/) instead.


		## Privacy Controls

		Generative AI inputs and outputs — the prompts your agent sends and the model responses it receives — are recorded on your AI spans by default. Review the data your agent handles and tighten this before production. To turn recording off, set `genAI.inputs` and `genAI.outputs` to `false` in `dataCollection`:

Uh oh!

Conversation

mydea commented Sep 16, 2026

DESCRIBE YOUR PR

IS YOUR CHANGE URGENT?

SLA

PRE-MERGE CHECKLIST

Uh oh!

vercel Bot commented Sep 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RulaKhaled left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

coolguyzone left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

vercel Bot commented Sep 16, 2026 •

edited

Loading