fix(server-utils): Keep orchestrion instrumentation working in bundled servers - #23706
Closed
logaretm wants to merge 14 commits into
Closed
fix(server-utils): Keep orchestrion instrumentation working in bundled servers#23706logaretm wants to merge 14 commits into
logaretm wants to merge 14 commits into
Conversation
`@sentry/node`'s `init()` installs a runtime module-transform hook from `@sentry/server-utils/orchestrion/register`, which drives a vendored code transformer (meriyah/astring/source-map) and is designed to run from `node_modules`. If a downstream bundler inlines and tree-shakes `@sentry/server-utils`, that transformer is stripped to empty objects, so at runtime `parse`/`generate` are `undefined` and the first module the hook tries to transform throws `TypeError: parse is not a function` — deep in the loader, once per module, and only when `debug: true` (otherwise it fails silently). Detect this once, up front: run a throwaway in-memory transform over a synthetic snippet before installing any hook. A healthy build returns normally; a tree-shaken one throws a `TypeError`. On detection, emit a single, always-on, actionable warning (via `consoleSandbox`, deduped on a global marker) and skip installing hooks that can't work, instead of letting the cryptic per-module error surface. The existing registration `catch` is likewise upgraded to an always-on warning. All of this lives inside `registerDiagnosticsChannelInjection`, so it tree-shakes away with the whole block when `bundleSizeOptimizations.excludeChannelInjection` sets `__SENTRY_CHANNEL_INJECTION__` to `false`. Ref #23664 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…n plugin The runtime hook (reached via `@sentry/node`) must stay external so it resolves from `node_modules`; bundling it strips the transformer and breaks the `Module.register` self-reference. `@sentry/node` is a different package from the `@sentry/server-utils` barrel the plugin force-bundles (`ssr.noExternal`), so the vite plugin now also adds `@sentry/node` to `ssr.external`. Explicit `ssr.external` entries win over `noExternal`, so this holds even against a preset that sets `ssr.noExternal: true` — verified with a real vite SSR build. This covers the vite-based frameworks (SvelteKit, Astro, React Router, TanStack); the nitro/rollup frameworks (Nuxt, SolidStart) rely on the runtime warning above, with a nitro-level externalization guard as a follow-up. Ref #23664 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add a "Bundling your server" note to the Node README (and a Nuxt troubleshoot note) explaining that the runtime instrumentation hook must stay external, and pointing to the build-time bundler-plugin instrumentation as the alternative. Ref #23664 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Forcing `@sentry/node` into `ssr.external` broke Cloudflare/worker builds: the shared vite orchestrion plugin also runs under `@cloudflare/vite-plugin` (and frameworks deploying to workerd), where `@sentry/node` is unused and setting `resolve.external` on a worker environment is rejected outright — and the worker environment is even named `ssr`, so there's no reliable node-vs-worker discriminator in the `config()` hook. Vite already externalizes `@sentry/node` for node SSR by default anyway, and the runtime probe in `orchestrion/register` covers the cases where it does get bundled, so drop the forced externalization. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
… a bundled hook If `@sentry/server-utils` was bundled AND the build-time bundler plugin ran (a defined `__SENTRY_ORCHESTRION__.bundler` Set), instrumentation is already injected at build time and the runtime hook is redundant — a supported setup. In that case downgrade the "bundled" message to a debug log instead of an always-on warning. The always-on warning now fires only when nothing instrumented the app (bundled and no build-time plugin). Also corrects the Node README: bundling doesn't disable auto-instrumentation when the build-time plugin is used. Ref #23664 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…builds The code transformer reaches both through `require()`, so node-resolve picked their CJS builds and `@rollup/plugin-commonjs` emitted each as an empty `_virtual/<dep>.js` proxy populated from a separate module through a bare side-effect import. Downstream bundlers delete that import, leaving `parse` and `generate` undefined at runtime. Re-resolving the specifier without the `require` condition picks each package's ESM build instead, which the transformer then binds by value. It also drops the duplicate meriyah copy the build was shipping, ~324 kB per format.
…n away source-map 0.6.1 ships no ESM build, so it keeps the empty-proxy shape that a downstream bundler strips. A `sideEffects` allowlist pins it, but the value that actually governs the ESM build is the generated `build/esm/package.json`, which is nearer to those files than the package's own. Copying the root list verbatim would leave every glob pointing at a path that cannot match, so re-anchor the entries that belong to the output directory and drop the rest.
webpack compiles a `node:module` external to `createRequire(...)('node:module')`
and wraps the result in a synthetic namespace. Because `node:module` exports a
function, that wrapper carries only `default`, so `registerHooks` and `register`
both read as undefined and a webpack-bundled SDK gave up with "no available Node
API" before installing any hook.
Node's own ESM namespace exposes the same object under `default`, and the CJS
build has no `default` at all, so preferring it covers every shape.
…undle Re-bundles the built `orchestrion/register` entry the way a downstream bundler does, honouring `sideEffects`, then runs the result in a child process and asserts it installs hooks rather than reporting the transformer unavailable.
The app only grepped for a config string, which survives tree-shaking even when the code transformer has been stripped to an empty object. It now keeps graphql external, runs the bundle, and asserts channel-based graphql spans arrive.
Keeping the transformer alive costs ~53 kB gzip on every bundled Node entry, so the three affected size limits go up. The bundling notes lose the "keep it external" instruction, which no longer applies, and keep only the two cases that still need a choice.
Contributor
size-limit report 📦
|
The legacy registration path resolves against a path baked in at build time, so it also fails when a webpack bundle runs on a machine other than the one it was built on, not only when `node_modules` is absent.
mydea
force-pushed
the
fix/orchestrion-detect-bundling
branch
from
August 28, 2026 09:26
1bb710e to
da0de0d
Compare
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
2 participants
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.
Makes orchestrion's runtime channel injection survive a downstream bundler inlining
@sentry/server-utils, so a bundled Node server records auto-instrumented spans instead of silently recording none. Stacks on #23675, whose probe and warning stay on as the fallback.Three things had to change. meriyah and astring are reached through
require(), which resolves to their CJS builds, and@rollup/plugin-commonjssplits those into an empty object plus a bare side-effect import that tree-shakers delete; both also publish ESM builds, so resolving them without therequirecondition avoids the shape entirely and drops a duplicate meriyah copy the build was shipping twice. source-map has no ESM build, so it is pinned with asideEffectsallowlist, which has to land in the generatedbuild/esm/package.jsonrather than the package's own to have any effect at all.Separately, webpack-bundled apps installed no hook even with the transformer intact, because
node:moduleexports a function and webpack's synthetic namespace for it carries onlydefault.Verified against the repro from #23664 on esbuild, and the
node-orchestrion-webpacke2e now runs its bundle and asserts spans arrive instead of grepping for a string. On Node 24.13+ a bundle works with no@sentry/*on disk; below that #23675's warning still applies.Refs #23664