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.32 kB	-	-
@sentry/browser - with treeshaking flags	25.74 kB	-	-
@sentry/browser (incl. Tracing)	45.31 kB	-	-
@sentry/browser (incl. Tracing + Span Streaming)	47.55 kB	-	-
@sentry/browser (incl. Tracing, Profiling)	50.3 kB	-	-
@sentry/browser (incl. Tracing, Replay)	84.92 kB	-	-
@sentry/browser (incl. Tracing, Replay) - with treeshaking flags	74.43 kB	-	-
@sentry/browser (incl. Tracing, Replay with Canvas)	89.64 kB	-	-
@sentry/browser (incl. Tracing, Replay, Feedback)	102.24 kB	-	-
@sentry/browser (incl. Feedback)	44.51 kB	-	-
@sentry/browser (incl. sendFeedback)	32.13 kB	-	-
@sentry/browser (incl. FeedbackAsync)	37.25 kB	-	-
@sentry/browser (incl. Metrics)	28.41 kB	-	-
@sentry/browser (incl. Logs)	28.64 kB	-	-
@sentry/browser (incl. Metrics & Logs)	29.33 kB	-	-
@sentry/react	29.05 kB	-	-
@sentry/react (incl. Tracing)	47.55 kB	-	-
@sentry/vue	32.24 kB	-	-
@sentry/vue (incl. Tracing)	47.17 kB	-	-
@sentry/svelte	27.35 kB	-	-
CDN Bundle	29.73 kB	-	-
CDN Bundle (incl. Tracing)	47.84 kB	-	-
CDN Bundle (incl. Logs, Metrics)	31.21 kB	-	-
CDN Bundle (incl. Tracing, Logs, Metrics)	49.09 kB	-	-
CDN Bundle (incl. Replay, Logs, Metrics)	70.53 kB	-	-
CDN Bundle (incl. Tracing, Replay)	85.34 kB	-	-
CDN Bundle (incl. Tracing, Replay, Logs, Metrics)	86.5 kB	-	-
CDN Bundle (incl. Tracing, Replay, Feedback)	91.2 kB	-	-
CDN Bundle (incl. Tracing, Replay, Feedback, Logs, Metrics)	92.37 kB	-	-
CDN Bundle - uncompressed	87.8 kB	-	-
CDN Bundle (incl. Tracing) - uncompressed	144.29 kB	-	-
CDN Bundle (incl. Logs, Metrics) - uncompressed	92.29 kB	-	-
CDN Bundle (incl. Tracing, Logs, Metrics) - uncompressed	148.05 kB	-	-
CDN Bundle (incl. Replay, Logs, Metrics) - uncompressed	217.02 kB	-	-
CDN Bundle (incl. Tracing, Replay) - uncompressed	263.07 kB	-	-
CDN Bundle (incl. Tracing, Replay, Logs, Metrics) - uncompressed	266.81 kB	-	-
CDN Bundle (incl. Tracing, Replay, Feedback) - uncompressed	276.77 kB	-	-
CDN Bundle (incl. Tracing, Replay, Feedback, Logs, Metrics) - uncompressed	280.5 kB	-	-
@sentry/nextjs (client)	50.03 kB	-	-
@sentry/sveltekit (client)	45.8 kB	-	-
@sentry/core/server	76.41 kB	-	-
@sentry/core/browser	63.16 kB	-	-
@sentry/node-core	62.59 kB	+0.01%	+2 B 🔺
@sentry/node	164.39 kB	+0.03%	+42 B 🔺
@sentry/node - without tracing	75.02 kB	-0.01%	-1 B 🔽
@sentry/aws-serverless	87.24 kB	-	-
@sentry/cloudflare (withSentry) - minified	173 kB	-	-
@sentry/cloudflare (withSentry)	432.17 kB	-	-
@sentry/node (with Orchestrion)	165.62 kB	added	added
@sentry/node/orchestrion (ESM hook)	70.36 kB	added	added
@sentry/node/light	51.43 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

cursor · 2026-05-19T07:49:33Z

+            code: SPAN_STATUS_ERROR,
+            message: ctx.error instanceof Error ? ctx.error.message : 'unknown_error',
+          });
+        },


Missing captureException call in error handling paths

Low Severity

The startInactiveSpan call's error paths (both the channel error handler and the streamable Query's 'error' event listener) set span status to SPAN_STATUS_ERROR but never call captureException. Per the review rules, when using any startSpan API (including startInactiveSpan), error cases need to be checked and it may make sense to call captureException. This may be intentional for DB query errors (to avoid noise), but worth flagging per the rules.

Additional Locations (1)

packages/node/src/integrations/tracing-channel/mysql.ts#L177-L187

^{Triggered by project rule: PR Review Guidelines for Cursor Bot}

^{Reviewed by Cursor Bugbot for commit 5d957bf. Configure here.}

I think the agent is wrong about this, and I've previously run into issues where they seem to get in fights with each other over it.

We should only captureException when we are sure that the user has not handled the error, and also when we are sure that the exception will not be handled by our top-level uncaughtException/unhandledRejection instrumentations. Otherwise, we end up with a duplicate event, or reporting errors for normal user-handled flow control.

To prevent this popping up again, it might be a good idea to add a comment indicating why captureException is not appropriate in this situation.

timfish · 2026-05-21T09:13:17Z

+  return [bundlerMarkerPlugin(), ...codeTransformerArray];
+}
+
+function bundlerMarkerPlugin(): UnknownPlugin {


None of this is required!

timfish · 2026-05-21T09:16:38Z

@@ -0,0 +1,33 @@
+// EXPERIMENTAL — entry point for `node --require @sentry/node/orchestrion app.js`.


We probably don't need to care about supplying a hook that works with --require

ah, you mean it is good enough if everybody uses --import, even if their app is cjs?

Yeah, @isaacs did some testing came up with this ESM code that can register all the hooks:
https://github.com/apm-js-collab/tracing-hooks/#usage

--import and --require just tell Node which kind of file you are passing after the flag and we can hook everything from ESM.

changed it to import only!

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.

cursor

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

There are 3 total unresolved issues (including 2 from previous reviews).

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

^{Reviewed by Cursor Bugbot for commit b089fd9. Configure 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.

isaacs · 2026-05-26T18:03:58Z

+            code: SPAN_STATUS_ERROR,
+            message: ctx.error instanceof Error ? ctx.error.message : 'unknown_error',
+          });
+        },


I think the agent is wrong about this, and I've previously run into issues where they seem to get in fights with each other over it.

We should only captureException when we are sure that the user has not handled the error, and also when we are sure that the exception will not be handled by our top-level uncaughtException/unhandledRejection instrumentations. Otherwise, we end up with a duplicate event, or reporting errors for normal user-handled flow control.

To prevent this popping up again, it might be a good idea to add a comment indicating why captureException is not appropriate in this situation.

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/node/src/integrations/tracing-channel/mysql.ts

Comment thread packages/node/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/node/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

timfish reviewed May 21, 2026

View reviewed changes

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

timfish reviewed May 21, 2026

View reviewed changes

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/node/src/orchestrion/detect.ts

mydea added 6 commits May 26, 2026 11:38

add orchestrion plan

f1b19b9

add the plan

b43285e

Add general utils and exports to node SDK

7ad96c3

add mysql example

4808081

fixes

4c389b8

fix lockfile

9495752

mydea added 18 commits May 26, 2026 11:38

fix lint

c3d91c0

fix exports

738c40f

fix types build

86ef742

fix import

900c91b

better handle sync errors

3a3075b

tests

afb47bb

mysql fixes

62cb744

remove unused file

73471c3

be defensive

9a95e7c

improvements

267ab75

add custom output

a90566e

add some more size limit scenarios

69c82b9

add test app

ce7d043

bump transformer plugin

eb8e8e6

fixes

9f4a6f6

add other test app

6018e89

add noExternal

8d52dc6

fix and cjs

3de78da

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

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

View reviewed changes

mydea added 2 commits May 26, 2026 12:46

bump tracing hooks

d148f83

streamline detect

b089fd9

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

		@@ -0,0 +1,33 @@
		// EXPERIMENTAL — entry point for `node --require @sentry/node/orchestrion app.js`.

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!

cursor Bot May 19, 2026

Choose a reason for hiding this comment

Missing captureException call in error handling paths

Uh oh!

isaacs May 26, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

timfish May 21, 2026

Choose a reason for hiding this comment

Uh oh!

timfish May 21, 2026

Choose a reason for hiding this comment

Uh oh!

mydea May 21, 2026

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mydea May 26, 2026

Choose a reason for hiding this comment

Uh oh!

mydea commented May 21, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

isaacs left a comment

Choose a reason for hiding this comment

Uh oh!

isaacs May 26, 2026

Choose a reason for hiding this comment

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

Missing `captureException` call in error handling paths

timfish May 21, 2026 •

edited

Loading