docs(js): Replace Mastra community exporter with first-party integration - #19296
Closed
RulaKhaled wants to merge 4 commits into
Closed
RulaKhaled wants to merge 4 commits into
RulaKhaled wants to merge 4 commits into
Conversation
The JavaScript SDK now instruments Mastra natively via `mastraIntegration`, enabled by default in Node runtimes. Both Mastra pages still documented the community `@mastra/sentry` exporter, which initializes its own Sentry client. - Rewrite the agent-tracing page around `Sentry.mastraIntegration` and `Sentry.SentryMastraExporter`, following the LangGraph/LangChain page pattern: Automatic Instrumentation, Manual Instrumentation, Options, Supported Operations. - Correct the span mapping table to what the SDK actually emits. The old table listed `workflow.run`, `ai.processor` and `ai.span`, none of which are produced; add `provider_tool_call`, `client_tool_call` and `rag_embedding`, and explain why unmapped types are dropped. - Document `recordInputs`, `recordOutputs` and `bootstrapObservability`, and add a migration section covering why leaving `@mastra/sentry` installed replaces or duplicates the configured client. - Rewrite the standalone Mastra guide as a `@sentry/node` setup: install `@sentry/node` and `@mastra/observability`, `instrument.mjs` plus `--import`, then no Mastra-side configuration. - Update the Mastra card copy on the home page. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Cy8ky8AVsY8dxgUNzWQMMT
|
The latest updates on your projects. Learn more about Vercel for GitHub.
1 Skipped Deployment
|
The page claimed meta-frameworks bundle Mastra into the server build where "the SDK can't hook it at runtime", and told users to fall back to manual instrumentation. That is wrong: every meta-framework SDK registers the orchestrion code transform over the server build by default, and `mastraConfig` is in the `SENTRY_INSTRUMENTATIONS` set those plugins inject. Verified on a real Next.js app (@mastra/core 1.63.2, no `Observability` configured, no manual exporter): - Next 15.5.4, webpack build: integration subscribes, emits `gen_ai.invoke_agent` and `gen_ai.chat`. - Next 16.2.11, Turbopack build: same spans. - Next 15.5.4, `next build --turbopack`: never subscribes, no spans. The last case is the only real gap, and it matches the code — `supportsTurbopackRuleCondition` gates the Turbopack loader rule on Next major >= 16. Replace the blanket meta-framework warning with that specific caveat, note that bundled server builds are covered by the build-time transform, and point Manual Instrumentation at the cases where the transform doesn't run (Next 15 + Turbopack, or `buildTimeInstrumentation: false`). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Cy8ky8AVsY8dxgUNzWQMMT
The caveat named a version without the reason, and scoped the gap to `next build` when it applies to `next dev --turbopack` too. Verified by inspecting the config `withSentryConfig` produces, with the same SDK build and app and only the Next.js version changed: - Next 16.2.11, TURBOPACK=1: orchestrion loader rule present, condition "node". - Next 15.5.4, TURBOPACK=1: no orchestrion loader rule at all. The rule needs Turbopack's `condition` field to scope the transform to the Node server compilation; that field landed in Next.js 16. Without it the loader would also run over the client and edge compilations, so the SDK omits the rule rather than inject `node:diagnostics_channel` into browser bundles. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Cy8ky8AVsY8dxgUNzWQMMT
The alert named only Next.js 15, but the gate is `major >= 16` (`supportsTurbopackRuleCondition`), and `@sentry/nextjs` supports `^14.0 || ^15.0.0-rc.0 || ^16.0.0-0`, so Next.js 14 is affected too — via `--turbo`, which bundler detection also matches. Also call out that the result can differ between environments: `next dev --turbopack` produces no spans while a webpack production build of the same app works, which reads as a broken integration rather than an uncovered bundler. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Cy8ky8AVsY8dxgUNzWQMMT
RulaKhaled
marked this pull request as ready for review
September 15, 2026 11:37
RulaKhaled
marked this pull request as draft
September 15, 2026 11:39
![sentry[bot]](https://avatars.githubusercontent.com/in/12637?s=60&v=4){kind=small}
|
|
||
| _Import name: `Sentry.SentryMastraExporter`_ | ||
|
|
||
| Register `SentryMastraExporter` yourself when the build-time transform doesn't run — on Next.js 15 with Turbopack, or when you've set `buildTimeInstrumentation: false`: |
Contributor
There was a problem hiding this comment.
Bug: The manual instrumentation header for Mastra on line 125 incorrectly omits Next.js 14, contradicting an alert on line 33 that correctly includes it.
Severity: MEDIUM
Suggested Fix
Update the header on line 125 to include both Next.js 14 and 15 to ensure consistency. Change the text from "on Next.js 15 with Turbopack" to "on Next.js 14 and 15 with Turbopack".
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: docs/platforms/javascript/common/agent-tracing/mastra.mdx#L125
Potential issue: The documentation for Mastra contains an internal inconsistency
regarding which Next.js versions require manual instrumentation with Turbopack. An alert
near the top of the file correctly states that it applies to `Next.js 14 and 15`.
However, the header for the manual instrumentation section further down only mentions
`Next.js 15`. This discrepancy can mislead users on Next.js 14 who navigate directly to
the section, causing them to skip the required setup. As a result, their Mastra
instrumentation would fail silently, capturing no spans.
Also affects:
docs/platforms/javascript/common/agent-tracing/mastra.mdx:31~39
Did we get this right? 👍 / 👎 to inform future reviews.
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
DESCRIBE YOUR PR
The JavaScript SDK now instruments Mastra natively (sentry-javascript#23823).
mastraIntegrationis a default integration in Node runtimes and registers a Sentry exporter on Mastra's observability pipeline. Both Mastra docs pages still described the community@mastra/sentryexporter, which callsSentry.init()itself, so this replaces them./platforms/javascript/guides/node/agent-tracing/mastra/@mastra/observability— the SDK bootstraps the pipeline when the app configured none, and attaches its exporter to an existingObservabilitywhen it did.SentryMastraExporteras the manual escape hatch for bundled server builds, with a<PlatformSection>warning on the meta-framework guides.workflow.run,workflow.step,ai.processorandai.span, none of which are produced; addedprovider_tool_call,client_tool_callandrag_embedding, and explained why unmapped types are dropped and their children re-parented.recordInputs,recordOutputsandbootstrapObservability, plus how to disable the integration.@mastra/sentryin place either replaces the configured client (losing release, environment, integrations, sampling) or starts a second SDK./platforms/javascript/guides/mastra/@sentry/nodesetup guide instead of a standalone-exporter walkthrough: install@sentry/node+@mastra/observability,instrument.mjswith--import, then nothing to change on the Mastra side. Same URL andStepConnectorstructure.Also
src/components/home.tsx).Note: both pages cite Sentry SDK
11.0.0as the minimum. This should go with v11 release.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-DDwith the due date. You can update this information later by editing the PR description.SLA
Thanks in advance for your help!
PRE-MERGE CHECKLIST
Make sure you've checked the following before merging your changes:
🤖 Generated with Claude Code
https://claude.ai/code/session_01Cy8ky8AVsY8dxgUNzWQMMT