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
develop-docs	Ready	Preview	Sep 18, 2026 8:28am UTC
sentry-docs	Ready	Preview	Sep 18, 2026 8:28am 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!

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

sentry · 2026-09-18T08:25:13Z

+    platformName !== 'javascript' || !agentTracingNode
+      ? []


Bug: The check for an agent-tracing/ subdirectory fails for the Mastra guide, causing related sidebar links to be omitted because the directory does not exist.
_{Severity: MEDIUM}

Suggested Fix

Create an agent-tracing/ subdirectory inside the Mastra guide's directory at docs/platforms/javascript/guides/mastra/. This will allow the agentTracingNode variable to be correctly populated, enabling the logic to generate the necessary sidebar links.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not valid. Location: src/components/sidebar/platformSidebar.tsx#L146-L147 Potential issue: The logic to display agent-tracing sidebar links depends on the presence of an `agent-tracing/` subdirectory within the guide's path. The variable `agentTracingNode` is populated based on this check. However, the Mastra guide's directory (`docs/platforms/javascript/guides/mastra/`) lacks this subdirectory. Consequently, `agentTracingNode` evaluates to a falsy value for the Mastra guide. This causes `standaloneGuideAgentTracingAliases` to return an empty array, preventing the rendering of expected sidebar links, such as the link to the Eve guide.

_{Did we get this right? 👍 / 👎 to inform future reviews.}

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

mydea and others added 4 commits September 18, 2026 10:04

Apply batched suggestions from code review

9d1aa66

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

mydea and others added 4 commits September 18, 2026 10:04

some fixes

8234a13

update

ea8967d

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

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

c198493

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>

sentry Bot reviewed Sep 18, 2026

View reviewed changes

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


		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!

sentry Bot Sep 18, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

vercel Bot commented Sep 16, 2026 •

edited

Loading