Skip to content

WIP: POC to use orchestrion-js for instrumentation#20900

Open
mydea wants to merge 32 commits into
developfrom
experiment/orchestrionjs-auto-instrumentation
Open

WIP: POC to use orchestrion-js for instrumentation#20900
mydea wants to merge 32 commits into
developfrom
experiment/orchestrionjs-auto-instrumentation

Conversation

@mydea

@mydea mydea commented May 15, 2026

Copy link
Copy Markdown
Member

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

  1. Built a general plan document outlining how this can/should work
  2. Implemented the generic utilities and building blocks needed
  3. 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:

  1. 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...
  2. 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.
  3. 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.

Comment thread yarn.lock Outdated
Comment thread yarn.lock Outdated
Comment thread packages/node/src/orchestrion/runtime/require-hook.cjs Outdated
@github-actions

github-actions Bot commented May 15, 2026

Copy link
Copy Markdown
Contributor

size-limit report 📦

Path Size % Change Change
@sentry/browser 27.39 kB - -
@sentry/browser - with treeshaking flags 25.82 kB - -
@sentry/browser (incl. Tracing) 45.68 kB - -
@sentry/browser (incl. Tracing + Span Streaming) 47.92 kB - -
@sentry/browser (incl. Tracing, Profiling) 50.48 kB - -
@sentry/browser (incl. Tracing, Replay) 84.9 kB - -
@sentry/browser (incl. Tracing, Replay) - with treeshaking flags 74.51 kB - -
@sentry/browser (incl. Tracing, Replay with Canvas) 89.6 kB - -
@sentry/browser (incl. Tracing, Replay, Feedback) 102.28 kB - -
@sentry/browser (incl. Feedback) 44.55 kB - -
@sentry/browser (incl. sendFeedback) 32.19 kB - -
@sentry/browser (incl. FeedbackAsync) 37.3 kB - -
@sentry/browser (incl. Metrics) 28.46 kB - -
@sentry/browser (incl. Logs) 28.69 kB - -
@sentry/browser (incl. Metrics & Logs) 29.39 kB - -
@sentry/react 29.18 kB - -
@sentry/react (incl. Tracing) 47.98 kB - -
@sentry/vue 32.4 kB - -
@sentry/vue (incl. Tracing) 47.57 kB - -
@sentry/svelte 27.41 kB - -
CDN Bundle 29.78 kB - -
CDN Bundle (incl. Tracing) 48.16 kB - -
CDN Bundle (incl. Logs, Metrics) 31.32 kB - -
CDN Bundle (incl. Tracing, Logs, Metrics) 49.48 kB - -
CDN Bundle (incl. Replay, Logs, Metrics) 70.61 kB - -
CDN Bundle (incl. Tracing, Replay) 85.51 kB - -
CDN Bundle (incl. Tracing, Replay, Logs, Metrics) 86.75 kB - -
CDN Bundle (incl. Tracing, Replay, Feedback) 91.34 kB - -
CDN Bundle (incl. Tracing, Replay, Feedback, Logs, Metrics) 92.6 kB - -
CDN Bundle - uncompressed 88.46 kB - -
CDN Bundle (incl. Tracing) - uncompressed 145.67 kB - -
CDN Bundle (incl. Logs, Metrics) - uncompressed 93.17 kB - -
CDN Bundle (incl. Tracing, Logs, Metrics) - uncompressed 149.65 kB - -
CDN Bundle (incl. Replay, Logs, Metrics) - uncompressed 217.99 kB - -
CDN Bundle (incl. Tracing, Replay) - uncompressed 264.54 kB - -
CDN Bundle (incl. Tracing, Replay, Logs, Metrics) - uncompressed 268.5 kB - -
CDN Bundle (incl. Tracing, Replay, Feedback) - uncompressed 278.24 kB - -
CDN Bundle (incl. Tracing, Replay, Feedback, Logs, Metrics) - uncompressed 282.19 kB - -
@sentry/nextjs (client) 50.43 kB - -
@sentry/sveltekit (client) 46.1 kB - -
@sentry/core/server 76.05 kB - -
@sentry/core/browser 63.19 kB - -
@sentry/node-core 61.73 kB - -
@sentry/node 130.52 kB +0.04% +41 B 🔺
@sentry/node - without tracing 74.1 kB - -
@sentry/aws-serverless 86.29 kB - -
@sentry/cloudflare (withSentry) - minified 173.69 kB - -
@sentry/cloudflare (withSentry) 433.85 kB - -
@sentry/node (with Orchestrion) 131.63 kB added added
@sentry/node/orchestrion (ESM hook) 69.88 kB added added
@sentry/node/light 50.77 kB added added

View base workflow run

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

mydea commented May 15, 2026

Copy link
Copy Markdown
Member Author

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

Comment thread packages/node/src/orchestrion/runtime/import-hook.mjs Outdated
@mydea mydea force-pushed the experiment/orchestrionjs-auto-instrumentation branch from b1b6ed6 to 9e8b070 Compare May 18, 2026 07:29
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 mydea force-pushed the experiment/orchestrionjs-auto-instrumentation branch from 9e8b070 to 26ccdf4 Compare May 18, 2026 09:03
Comment thread packages/node/src/orchestrion/setup.ts
@mydea mydea force-pushed the experiment/orchestrionjs-auto-instrumentation branch from 26ccdf4 to c8be420 Compare May 18, 2026 13:34
Comment thread packages/node/src/orchestrion/setup.ts
Comment thread packages/node/src/orchestrion/runtime/import-hook.mjs Outdated
Comment thread packages/node/src/orchestrion/runtime/import-hook.mjs Outdated
@mydea mydea force-pushed the experiment/orchestrionjs-auto-instrumentation branch from a38481b to c095626 Compare May 19, 2026 07:20
Comment thread packages/node/src/orchestrion/setup.ts Outdated
Comment thread packages/server-utils/src/integrations/tracing-channel/mysql.ts
Comment thread packages/node/src/orchestrion/runtime/import-hook.mjs Outdated
Comment thread packages/server-utils/src/orchestrion/detect.ts
Comment thread packages/node/src/orchestrion/bundler/vite.ts Outdated
Comment thread packages/node/src/orchestrion/runtime/require-hook.cjs Outdated
@mydea mydea force-pushed the experiment/orchestrionjs-auto-instrumentation branch from 5d957bf to 12ac21c Compare May 21, 2026 11:02
@mydea

mydea commented May 21, 2026

Copy link
Copy Markdown
Member Author

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.

Comment thread packages/server-utils/src/orchestrion/detect.ts
@mydea mydea force-pushed the experiment/orchestrionjs-auto-instrumentation branch from 7d6f1f7 to 3de78da Compare May 26, 2026 09:40
Comment thread packages/node/src/orchestrion/runtime/import-hook.mjs Outdated
Comment thread dev-packages/e2e-tests/test-applications/node-express-orchestrion-cjs/src/app.js Dismissed
Comment thread dev-packages/e2e-tests/test-applications/node-express-orchestrion-vite/src/app.ts Dismissed
Comment thread dev-packages/e2e-tests/test-applications/node-express-orchestrion/src/app.mjs Dismissed
Comment thread packages/node/src/sdk/index.ts

@isaacs isaacs left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread packages/server-utils/src/integrations/tracing-channel/mysql.ts
Comment thread packages/node/src/orchestrion/runtime/import-hook.mjs Outdated
@mydea

mydea commented May 27, 2026

Copy link
Copy Markdown
Member Author

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 isaacs force-pushed the experiment/orchestrionjs-auto-instrumentation branch from 0157d09 to 25bfdaa Compare June 10, 2026 19:33

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Fix All in Cursor

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

Reviewed by Cursor Bugbot for commit 25bfdaa. Configure here.

Comment thread packages/server-utils/src/orchestrion/runtime/import-hook.mjs
Comment thread packages/server-utils/src/integrations/tracing-channel/mysql.ts
@isaacs isaacs force-pushed the experiment/orchestrionjs-auto-instrumentation branch from 25bfdaa to 7a8b730 Compare June 10, 2026 19:37
isaacs added 7 commits June 10, 2026 12:46
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.
@isaacs isaacs force-pushed the experiment/orchestrionjs-auto-instrumentation branch from 7a8b730 to 7b69e3b Compare June 10, 2026 20:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants