WIP: POC to use orchestrion-js for instrumentation by mydea · Pull Request #20900 · getsentry/sentry-javascript

mydea · 2026-05-15T09:16:15Z

This is a WIP POC trying out usage of orchestrion-js for node SDK instrumentation.

Built a general plan document outlining how this can/should work
Implemented the generic utilities and building blocks needed
Implemented a example integration for mysql package using the new pieces

Honestly it seems pretty straightforward... Usage for this POC is:

node --import @sentry/node/orchestrion app.mjs

And then

// app.mjs
import * as Sentry from '@sentry/node';

const client = Sentry.init({
 // regular setup...
  _experimentalUseOrchestrion: true,
});

// Split this way for better tree shaking
Sentry._experimentalSetupOrchestrion(client);

This will disable the otel instrumentation that is already converted to orchestrion (in this PR, only Mysql) and add the respective orchestrion-based integrations instead. The exact API here is WIP and really just geared towards experimentation, so could change, and it's easy to see how this would be easier in v11 with this being the default.

Some general benefits of this approach:

preload becomes unnecessary as this approach generally behaves like preload - the --import script only registers the mappings for orchestrion, all actual code registering stuff etc. happens in Sentry.init(). This makes a bunch of things easier...
Not tested here, but this should generally work exactly the same if you add the respective vite (and others in the future) plugin, allowing you to skip the --import. This also works when deploying to e.g. cloudflare etc. as long as one of the bundler plugins is used.
The whole approach is much easier to reconcile with dual-system approaches where newer versions have native DC/TC support - just need to register different channel names mostly to get stuff working.

github-actions · 2026-05-15T09:30:30Z

size-limit report 📦

Path	Size	% Change	Change
@sentry/browser	27.21 kB	-	-
@sentry/browser - with treeshaking flags	25.65 kB	-	-
@sentry/browser (incl. Tracing)	45.51 kB	-	-
@sentry/browser (incl. Tracing + Span Streaming)	47.73 kB	-	-
@sentry/browser (incl. Tracing, Profiling)	50.28 kB	-	-
@sentry/browser (incl. Tracing, Replay)	84.71 kB	-	-
@sentry/browser (incl. Tracing, Replay) - with treeshaking flags	74.33 kB	-	-
@sentry/browser (incl. Tracing, Replay with Canvas)	89.41 kB	-	-
@sentry/browser (incl. Tracing, Replay, Feedback)	102.1 kB	-	-
@sentry/browser (incl. Feedback)	44.36 kB	-	-
@sentry/browser (incl. sendFeedback)	32.02 kB	-	-
@sentry/browser (incl. FeedbackAsync)	37.11 kB	-	-
@sentry/browser (incl. Metrics)	28.28 kB	-	-
@sentry/browser (incl. Logs)	28.52 kB	-	-
@sentry/browser (incl. Metrics & Logs)	29.22 kB	-	-
@sentry/react	29.02 kB	-	-
@sentry/react (incl. Tracing)	47.77 kB	-	-
@sentry/vue	32.22 kB	-	-
@sentry/vue (incl. Tracing)	47.4 kB	-	-
@sentry/svelte	27.23 kB	-	-
CDN Bundle	29.58 kB	-	-
CDN Bundle (incl. Tracing)	47.95 kB	-	-
CDN Bundle (incl. Logs, Metrics)	31.09 kB	-	-
CDN Bundle (incl. Tracing, Logs, Metrics)	49.2 kB	-	-
CDN Bundle (incl. Replay, Logs, Metrics)	70.37 kB	-	-
CDN Bundle (incl. Tracing, Replay)	85.33 kB	-	-
CDN Bundle (incl. Tracing, Replay, Logs, Metrics)	86.51 kB	-	-
CDN Bundle (incl. Tracing, Replay, Feedback)	91.16 kB	-	-
CDN Bundle (incl. Tracing, Replay, Feedback, Logs, Metrics)	92.33 kB	-	-
CDN Bundle - uncompressed	87.7 kB	-	-
CDN Bundle (incl. Tracing) - uncompressed	144.9 kB	-	-
CDN Bundle (incl. Logs, Metrics) - uncompressed	92.19 kB	-	-
CDN Bundle (incl. Tracing, Logs, Metrics) - uncompressed	148.65 kB	-	-
CDN Bundle (incl. Replay, Logs, Metrics) - uncompressed	217 kB	-	-
CDN Bundle (incl. Tracing, Replay) - uncompressed	263.76 kB	-	-
CDN Bundle (incl. Tracing, Replay, Logs, Metrics) - uncompressed	267.51 kB	-	-
CDN Bundle (incl. Tracing, Replay, Feedback) - uncompressed	277.46 kB	-	-
CDN Bundle (incl. Tracing, Replay, Feedback, Logs, Metrics) - uncompressed	281.2 kB	-	-
@sentry/nextjs (client)	50.26 kB	-	-
@sentry/sveltekit (client)	45.92 kB	-	-
@sentry/core/server	75.94 kB	-	-
@sentry/core/browser	63.09 kB	-	-
@sentry/node-core	61.7 kB	+0.01%	+2 B 🔺
@sentry/node	130.45 kB	+0.04%	+42 B 🔺
@sentry/node - without tracing	74.08 kB	+0.01%	+1 B 🔺
@sentry/aws-serverless	86.27 kB	+0.01%	+1 B 🔺
@sentry/cloudflare (withSentry) - minified	173.59 kB	-	-
@sentry/cloudflare (withSentry)	433.74 kB	-	-
@sentry/node (with Orchestrion)	131.53 kB	added	added
@sentry/node/orchestrion (ESM hook)	69.88 kB	added	added
@sentry/node/light	50.74 kB	added	added

View base workflow run

mydea · 2026-05-15T09:45:20Z

Note: dependency warning stuff should be addressed when this is merged/released: apm-js-collab/code-transformer-bundler-plugins#2

mydea · 2026-05-21T11:43:48Z

I also added an e2e test app using the vite plugin, however this is failing, will need to wait on v0.2.0 of the plugins as this updates to the latest version of the code transformer, which we need here.

isaacs

This is looking very good!

My only concern/suggestion is that it should really not be node-specific. Deno and Bun are both supported by orchestrion now, so it'd be good to move this logic into a shared location so they can all benefit from it as we add instrumentations.

I'm not sure if it's best to (a) land this first, and then refactor this and the other @sentry/core/server stuff into @sentry-internal/server-utils, or (b) if we should bite that bullet first and then move this implementation on top of it. If we go with (a), then the move would be to land this now, and do server-utils as a second step. If (b), then it'd be good to get that done, and port this on top of it.

mydea · 2026-05-27T07:58:31Z

This is looking very good!

My only concern/suggestion is that it should really not be node-specific. Deno and Bun are both supported by orchestrion now, so it'd be good to move this logic into a shared location so they can all benefit from it as we add instrumentations.

I'm not sure if it's best to (a) land this first, and then refactor this and the other @sentry/core/server stuff into @sentry-internal/server-utils, or (b) if we should bite that bullet first and then move this implementation on top of it. If we go with (a), then the move would be to land this now, and do server-utils as a second step. If (b), then it'd be good to get that done, and port this on top of it.

jup, eventually this should go into a new server-utils package or similar I guess - we can move this up any time!

isaacs · 2026-06-07T19:32:44Z

Added two commits:

Migrate the orchestrion machinery into server-utils, the better to use with Deno, Bun (in build mode only), and Cloudflare (with vite only) as well.
Update the plan to reflect this new approach.

I did not add the integrations for Bun and Deno yet, but I do have another branch that integrates this for Bun. (Unfortunately this only works in bun build mode, not bun run. Fixed by oven-sh/bun#31770.)

We ought to land this, and then for next steps:

consider renaming the user-facing orchestrion naming to something more descriptive and less branded, like autoInjectChannels or something.
Address the proliferation of import/plugin/loader/init type plugins that we should try to bring some order to, especially in the Node SDK.
Wire up orchestrion integrations for Bun, Deno, and Cloudflare, as much as we can.
Add more orchestrion-based integrations.

Also, fix the `import ... from 'node:module'` in the import-hook.mjs, which was broken.

The test was loading the import hook via `import`, which would get converted to a `require()` when testing CommonJS. This, obviously, would break, because the import loader is ESM only. Update the test to register the import loader in the traditional way, with `--import`, so that we can verify it covers both CJS and ESM. Update the Orchestrion Plan so that the agents don't get confused when the require hook is missing.

Also, disable the `Module.register()` path on Deno and Bun, because the function is present but no-opped on those platforms.

Older versions of TS do not find this from package.json submodule exports.

The AI agents reviewing the code are concerned that we're not warning in production, but that would be a bad idea in this case, so put a comment to make the intent clearer.

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 4bc9c5b. Configure here.}

semgrep-code-getsentry Bot reviewed May 15, 2026

View reviewed changes

Comment thread yarn.lock Outdated

semgrep-code-getsentry Bot reviewed May 15, 2026

View reviewed changes

Comment thread yarn.lock Outdated

cursor Bot reviewed May 15, 2026

View reviewed changes

Comment thread packages/node/src/orchestrion/runtime/require-hook.cjs Outdated

cursor Bot reviewed May 15, 2026

View reviewed changes

Comment thread packages/server-utils/src/integrations/tracing-channel/mysql.ts

Comment thread packages/server-utils/src/integrations/tracing-channel/mysql.ts

isaacs reviewed May 16, 2026

View reviewed changes

Comment thread packages/node/src/orchestrion/runtime/import-hook.mjs Outdated

mydea force-pushed the experiment/orchestrionjs-auto-instrumentation branch from b1b6ed6 to 9e8b070 Compare May 18, 2026 07:29

cursor Bot reviewed May 18, 2026

View reviewed changes

Comment thread packages/server-utils/src/integrations/tracing-channel/mysql.ts

Comment thread dev-packages/node-integration-tests/suites/tracing/mysql/scenario-orchestrion.mjs Outdated

mydea force-pushed the experiment/orchestrionjs-auto-instrumentation branch from 9e8b070 to 26ccdf4 Compare May 18, 2026 09:03

cursor Bot reviewed May 18, 2026

View reviewed changes

Comment thread packages/node/src/orchestrion/setup.ts

mydea force-pushed the experiment/orchestrionjs-auto-instrumentation branch from 26ccdf4 to c8be420 Compare May 18, 2026 13:34

cursor Bot reviewed May 18, 2026

View reviewed changes

Comment thread packages/node/src/orchestrion/setup.ts

cursor Bot reviewed May 19, 2026

View reviewed changes

Comment thread packages/node/src/orchestrion/runtime/import-hook.mjs Outdated

Comment thread packages/node/src/orchestrion/runtime/import-hook.mjs Outdated

mydea force-pushed the experiment/orchestrionjs-auto-instrumentation branch from a38481b to c095626 Compare May 19, 2026 07:20

cursor Bot reviewed May 19, 2026

View reviewed changes

Comment thread packages/node/src/orchestrion/setup.ts Outdated

cursor Bot reviewed May 19, 2026

View reviewed changes

Comment thread packages/server-utils/src/integrations/tracing-channel/mysql.ts

Comment thread packages/node/src/orchestrion/runtime/import-hook.mjs Outdated

timfish reviewed May 21, 2026

View reviewed changes

Comment thread packages/server-utils/src/orchestrion/detect.ts

timfish reviewed May 21, 2026

View reviewed changes

Comment thread packages/node/src/orchestrion/bundler/vite.ts Outdated

timfish reviewed May 21, 2026

View reviewed changes

Comment thread packages/node/src/orchestrion/runtime/require-hook.cjs Outdated

mydea force-pushed the experiment/orchestrionjs-auto-instrumentation branch from 5d957bf to 12ac21c Compare May 21, 2026 11:02

mydea mentioned this pull request May 21, 2026

feat(node): Implement registerModuleWrapper as alternative IITM/RITM wrapping method #20188

Closed

cursor Bot reviewed May 21, 2026

View reviewed changes

Comment thread packages/server-utils/src/orchestrion/detect.ts

mydea force-pushed the experiment/orchestrionjs-auto-instrumentation branch from 7d6f1f7 to 3de78da Compare May 26, 2026 09:40

cursor Bot reviewed May 26, 2026

View reviewed changes

Comment thread packages/node/src/orchestrion/runtime/import-hook.mjs Outdated

github-advanced-security AI found potential problems May 26, 2026

View reviewed changes

cursor Bot reviewed May 26, 2026

View reviewed changes

Comment thread packages/node/src/sdk/index.ts

isaacs reviewed May 26, 2026

View reviewed changes

Comment thread packages/server-utils/src/integrations/tracing-channel/mysql.ts

Comment thread packages/node/src/orchestrion/runtime/import-hook.mjs Outdated

isaacs requested review from JPeer264 and andreiborza June 7, 2026 19:09

sentry Bot reviewed Jun 7, 2026

View reviewed changes

Comment thread packages/server-utils/src/orchestrion/detect.ts

sentry Bot reviewed Jun 7, 2026

View reviewed changes

Comment thread packages/server-utils/src/integrations/tracing-channel/mysql.ts

sentry Bot reviewed Jun 7, 2026

View reviewed changes

Comment thread packages/node/src/orchestrion/setup.ts

mydea and others added 19 commits June 7, 2026 12:51

mysql fixes

be61e17

remove unused file

d272501

be defensive

f13d910

improvements

0cda451

add custom output

795aed9

add some more size limit scenarios

d3fb9ba

add test app

c8c5fde

bump transformer plugin

f653065

fixes

f462eb7

add other test app

acc51a1

add noExternal

f7c0353

fix and cjs

f3e690f

bump tracing hooks

7824aff

streamline detect

b4e161d

feat(orchestrion): move into server-utils

39f139c

Also, fix the `import ... from 'node:module'` in the import-hook.mjs, which was broken.

fix(orchestrion): enable import hook on deno 2.8+

28db8dc

Also, disable the `Module.register()` path on Deno and Bun, because the function is present but no-opped on those platforms.

fix(server-utils): add ./orchestrion shim for submodule export

9c94bea

Older versions of TS do not find this from package.json submodule exports.

fix(server-utils): add note about not warning in production

4bc9c5b

The AI agents reviewing the code are concerned that we're not warning in production, but that would be a bad idea in this case, so put a comment to make the intent clearer.

isaacs force-pushed the experiment/orchestrionjs-auto-instrumentation branch from ea56069 to 4bc9c5b Compare June 7, 2026 19:51

cursor Bot reviewed Jun 7, 2026

View reviewed changes

Comment thread packages/server-utils/src/orchestrion/runtime/import-hook.mjs Outdated

fix(server-utils): add double-load guard to orchestrion import hook

0834516

sentry Bot reviewed Jun 7, 2026

View reviewed changes

Comment thread packages/server-utils/src/orchestrion/runtime/import-hook.mjs

fixup! fix(server-utils): add ./orchestrion shim for submodule export

42dcfd2

Uh oh!

Conversation

mydea commented May 15, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

size-limit report 📦

Uh oh!

Uh oh!

Uh oh!

mydea commented May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mydea commented May 21, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

isaacs left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mydea commented May 27, 2026

Uh oh!

Uh oh!

isaacs commented Jun 7, 2026

Uh oh!

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

github-actions Bot commented May 15, 2026 •

edited

Loading

mydea commented May 15, 2026 •

edited

Loading