feat(server-utils): Capture and log orchestrion stats (#22269)

Author: timfish

dev-packages/deno-integration-tests/suites/orchestrion-mysql/test.ts

@@ -92,7 +92,7 @@ Deno.test('@sentry/deno/import: transforms mysql so it publishes the orchestrion
   // ...with the real SQL forwarded through the channel context.
   assert(line.includes('statement=SELECT 1 AS solution'), `expected forwarded SQL, got: ${line}`);
   // The runtime hook set its detection marker at boot.
-  assert(line.includes('"runtime":true'), `expected runtime marker, got: ${line}`);
+  assert(line.includes('"runtime":["mysql"]'), `expected runtime marker, got: ${line}`);
 });
 
 // Exercises the SDK path end-to-end: `init()` wires `denoMysqlIntegration`

dev-packages/deno-integration-tests/suites/orchestrion-postgres/test.ts

@@ -92,7 +92,7 @@ Deno.test('@sentry/deno/import: transforms pg so it publishes the orchestrion ch
   // ...with the real SQL forwarded through the channel context.
   assert(line.includes('statement=SELECT 1 AS solution'), `expected forwarded SQL, got: ${line}`);
   // The runtime hook set its detection marker at boot.
-  assert(line.includes('"runtime":true'), `expected runtime marker, got: ${line}`);
+  assert(line.includes('"runtime":["pg","pg-pool"]'), `expected runtime marker, got: ${line}`);
 });
 
 // Exercises the SDK path end-to-end: `init()` wires `denoPostgresIntegration`

packages/bun/package.json

@@ -49,7 +49,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@apm-js-collab/code-transformer-bundler-plugins": "^0.6.0",
+    "@apm-js-collab/code-transformer-bundler-plugins": "^0.6.1",
     "@sentry/core": "10.65.0",
     "@sentry/node": "10.65.0",
     "@sentry/server-utils": "10.65.0"

packages/core/src/utils/worldwide.ts

@@ -55,6 +55,15 @@ export type InternalGlobal = {
   _sentryModuleMetadata?: Record<string, any>;
   _sentryEsmLoaderHookRegistered?: boolean;
   _sentryWrappedDepth?: number;
+  /**
+   * Orchestrion bundler and runtime detection.
+   */
+  __SENTRY_ORCHESTRION__?: {
+    /** Empty array signifies runtime hooked */
+    runtime?: string[];
+    /** Empty array signifies bundler plugin ran */
+    bundler?: string[];
+  };
 } & Carrier;
 
 /** Get's the global object for the current JavaScript runtime */

packages/server-utils/package.json

@@ -116,9 +116,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@apm-js-collab/code-transformer-bundler-plugins": "^0.6.0",
+    "@apm-js-collab/code-transformer-bundler-plugins": "^0.6.1",
     "@apm-js-collab/code-transformer": "^0.18.0",
-    "@apm-js-collab/tracing-hooks": "^0.12.0",
+    "@apm-js-collab/tracing-hooks": "^0.13.0",
     "@sentry/conventions": "^0.16.0",
     "@sentry/core": "10.65.0"
   },

packages/server-utils/src/orchestrion/bundler/options.ts

@@ -13,16 +13,16 @@ export type PluginOptions = {
  * The `@apm-js-collab/code-transformer-bundler-plugins` options shared by every
  * orchestrion bundler plugin.
  *
- * `injectDiagnostics` sets `globalThis.__SENTRY_ORCHESTRION__.bundler = true` at
+ * `injectDiagnostics` sets `globalThis.__SENTRY_ORCHESTRION__.bundler = ["mysql"]` at
  * app boot so the `_experimentalSetupOrchestrion()` detector can confirm the
  * bundler path ran (rather than relying on a build-time flag that wouldn't be
  * visible to the runtime).
  */
 export function orchestrionTransformOptions(options: PluginOptions): Parameters<typeof codeTransformer>[0] {
   return {
     instrumentations: [...SENTRY_INSTRUMENTATIONS, ...(options.instrumentations || [])],
-    injectDiagnostics: () => {
-      return '(globalThis.__SENTRY_ORCHESTRION__=globalThis.__SENTRY_ORCHESTRION__||{}).bundler=true;';
+    injectDiagnostics: (diag: { transformedModules: string[]; failedModules: string[] }) => {
+      return `(globalThis.__SENTRY_ORCHESTRION__=globalThis.__SENTRY_ORCHESTRION__||{}).bundler=${JSON.stringify(diag.transformedModules)};`;
     },
   };
 }

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

@@ -1,10 +1,4 @@
-import { debug } from '@sentry/core';
-import { DEBUG_BUILD } from '../debug-build';
-
-declare global {
-  // eslint-disable-next-line no-var
-  var __SENTRY_ORCHESTRION__: { runtime?: boolean; bundler?: boolean } | undefined;
-}
+import { debug, GLOBAL_OBJ } from '@sentry/core';
 
 /**
  * Whether orchestrion has injected the diagnostics channels into this process,
@@ -16,40 +10,43 @@ declare global {
  * will ever publish to those channels.
  */
 export function isOrchestrionInjected(): boolean {
-  const marker = globalThis.__SENTRY_ORCHESTRION__;
-  return !!(marker?.runtime || marker?.bundler);
+  return !!GLOBAL_OBJ.__SENTRY_ORCHESTRION__;
 }
 
 /**
  * Verifies that the diagnostics channels have been injected either by the
  * runtime `--import` hook (or init-time registration), a bundler plugin, or
- * both, and warns if not.
+ * both, and warns if not. When at least one injector is active, logs for each
+ * mechanism whether it hooked (a defined array, even empty, means it did) and
+ * which libraries it injected.
  *
  * Both injectors being active at once is fine: they operate on disjoint module
  * sets (a module is either loaded through Node's loader and transformed by the
  * runtime hook, or inlined by the bundler and transformed by the plugin), so
  * a single module can't be double-wrapped. A hybrid setup, with some deps
  * external and runtime-instrumented, others bundled and plugin-instrumented,
  * is fine.
- *
- * Note: intentionally does NOT warn in production, only in debug builds,
- * because production warnings are reserved for truly critical issues.
  */
 export function detectOrchestrionSetup(): void {
-  if (!DEBUG_BUILD) return;
+  const { runtime, bundler } = GLOBAL_OBJ.__SENTRY_ORCHESTRION__ ?? {};
 
-  const marker = globalThis.__SENTRY_ORCHESTRION__;
-  const runtime = !!marker?.runtime;
-  const bundler = !!marker?.bundler;
-
-  DEBUG_BUILD && debug.log(`[orchestrion] detect: runtime=${runtime} bundler=${bundler}`);
-
-  if (!isOrchestrionInjected()) {
-    DEBUG_BUILD &&
-      debug.warn(
-        '[Sentry] No diagnostics-channel injection detected. Channel-based integrations ' +
-          '(mysql, …) will not record spans. Make sure the diagnostics channels are injected ' +
-          'via the runtime `--import` hook or a bundler plugin before the instrumented modules load.',
-      );
+  if (!runtime && !bundler) {
+    debug.warn(
+      '[Sentry] No diagnostics-channel injection detected. Channel-based integrations ' +
+        'will not record spans. Make sure the diagnostics channels are injected ' +
+        'via the runtime `--import` hook or a bundler plugin before the instrumented modules load.',
+    );
+    return;
   }
+
+  debug.log(
+    runtime
+      ? `[Sentry] Runtime hook registered, injected libraries=${JSON.stringify(runtime)}`
+      : '[Sentry] Runtime hook not registered',
+  );
+  debug.log(
+    bundler
+      ? `[Sentry] Bundler plugin ran, injected libraries=${JSON.stringify(bundler)}`
+      : '[Sentry] Bundler plugin did not run',
+  );
 }

packages/server-utils/src/orchestrion/runtime/register.ts

@@ -1,9 +1,23 @@
-import { debug } from '@sentry/core';
+import { debug, GLOBAL_OBJ } from '@sentry/core';
 import { createRequire } from 'node:module';
 import * as Module from 'node:module';
 import { pathToFileURL } from 'node:url';
 import { DEBUG_BUILD } from '../../debug-build';
 import { SENTRY_INSTRUMENTATIONS } from '../config';
+import type { InstrumentationConfig } from '@apm-js-collab/code-transformer';
+import type { register } from 'node:module';
+
+type TracingHooksSync = {
+  initialize: (opts: { instrumentations: InstrumentationConfig[] }) => void;
+  resolve: Function;
+  load: Function;
+  setDiagnosticsHook: (callback: (event: { url: string; moduleName: string; error: Error }) => void) => void;
+};
+
+type NodeModule = {
+  registerHooks?: (options: unknown) => { deregister: () => void };
+  register?: typeof register;
+};
 
 export interface RegisterDiagnosticsChannelInjectionOptions {
   /**
@@ -17,11 +31,6 @@ export interface RegisterDiagnosticsChannelInjectionOptions {
   tracingHooksDir?: string;
 }
 
-declare global {
-  // eslint-disable-next-line no-var
-  var __SENTRY_ORCHESTRION__: { runtime?: boolean; bundler?: boolean } | undefined;
-}
-
 /** `Module.registerHooks` only became stable in Node 24.13 / 25.1 and Deno 2.8. */
 function hasStableSyncModuleHooks(denoVersionString: string | undefined): boolean {
   const parseVersion = (v: string): number[] => v.split('.').map(n => parseInt(n, 10));
@@ -47,15 +56,9 @@ function hasStableSyncModuleHooks(denoVersionString: string | undefined): boolea
  *
  * Libraries imported *after* this call publish the `tracingChannel` events that
  * the channel-based integrations subscribe to.
- *
- * Idempotent via `globalThis.__SENTRY_ORCHESTRION__` — a no-op if the runtime
- * `--import` hook or a bundler plugin already injected the channels.
  */
 export function registerDiagnosticsChannelInjection(options?: RegisterDiagnosticsChannelInjectionOptions): void {
-  const g = (globalThis.__SENTRY_ORCHESTRION__ ??= {});
-
-  // Already injected (runtime --import hook or bundler plugin) — nothing to do.
-  if (g.runtime) {
+  if (GLOBAL_OBJ?.__SENTRY_ORCHESTRION__?.runtime) {
     return;
   }
 
@@ -89,10 +92,7 @@ export function registerDiagnosticsChannelInjection(options?: RegisterDiagnostic
 
   // `Module.registerHooks` / `Module.register` are newer than the @types/node
   // we build against, hence the cast.
-  const mod = Module as unknown as {
-    registerHooks?: (hooks: unknown) => void;
-    register?: (specifier: string, options: unknown) => void;
-  };
+  const mod = Module as NodeModule;
 
   // runs both at `--import` time and (synchronously) inside `Sentry.init()`,
   // so an unguarded throw would either abort startup or make `init()` throw.
@@ -105,15 +105,18 @@ export function registerDiagnosticsChannelInjection(options?: RegisterDiagnostic
       // We require() the module here so that we can synchronously load it,
       // including from a CommonJS Sentry build, without bundlers pulling in.
       // All versions in stableSyncHooks support this.
-      const { initialize, resolve, load } = (
+      const { initialize, resolve, load, setDiagnosticsHook } = (
         requireFromHooksDir
           ? requireFromHooksDir(`${tracingHooksDir}/hook-sync.mjs`)
           : nodeRequire('@apm-js-collab/tracing-hooks/hook-sync.mjs')
-      ) as {
-        initialize: (opts: { instrumentations: unknown }) => void;
-        resolve: unknown;
-        load: unknown;
-      };
+      ) as TracingHooksSync;
+
+      setDiagnosticsHook(event => {
+        GLOBAL_OBJ.__SENTRY_ORCHESTRION__ = GLOBAL_OBJ.__SENTRY_ORCHESTRION__ || {};
+        GLOBAL_OBJ.__SENTRY_ORCHESTRION__.runtime = GLOBAL_OBJ.__SENTRY_ORCHESTRION__.runtime || [];
+        GLOBAL_OBJ.__SENTRY_ORCHESTRION__.runtime.push(event.moduleName);
+      });
+
       initialize({ instrumentations: SENTRY_INSTRUMENTATIONS });
       mod.registerHooks({ resolve, load });
       DEBUG_BUILD && debug.log('[orchestrion] registered diagnostics-channel injection via Module.registerHooks()');
@@ -161,5 +164,6 @@ export function registerDiagnosticsChannelInjection(options?: RegisterDiagnostic
     return;
   }
 
-  g.runtime = true;
+  GLOBAL_OBJ.__SENTRY_ORCHESTRION__ = GLOBAL_OBJ.__SENTRY_ORCHESTRION__ || {};
+  GLOBAL_OBJ.__SENTRY_ORCHESTRION__.runtime = GLOBAL_OBJ.__SENTRY_ORCHESTRION__.runtime || [];
 }

yarn.lock

@@ -404,10 +404,10 @@
   dependencies:
     json-schema-to-ts "^3.1.1"
 
-"@apm-js-collab/code-transformer-bundler-plugins@^0.6.0":
-  version "0.6.0"
-  resolved "https://registry.yarnpkg.com/@apm-js-collab/code-transformer-bundler-plugins/-/code-transformer-bundler-plugins-0.6.0.tgz#ed64bae9e1871366eadc1ef6dabc9ee6ccc53e57"
-  integrity sha512-Hys7LDskIB/BNrd87GAfYWHRE3mWgcPYonK4W9uxjho4N0JnPKk2YQyOLlqmkyVhj2UzwLRpmbJ4D6uR9O7wyw==
+"@apm-js-collab/code-transformer-bundler-plugins@^0.6.1":
+  version "0.6.1"
+  resolved "https://registry.yarnpkg.com/@apm-js-collab/code-transformer-bundler-plugins/-/code-transformer-bundler-plugins-0.6.1.tgz#29bf79167411b8607f02db177250b8f7c16d93e1"
+  integrity sha512-TDvypsLUk/W202Y1JBE6I2enQalWjbYXKnxpELWEZn6GLoIcGFii69ljh948hdAzKZJ/wg0Uwivz72a/szoOBQ==
   dependencies:
     "@apm-js-collab/code-transformer" "^0.18.0"
     es-module-lexer "^2.1.0"
@@ -426,10 +426,10 @@
     semifies "^1.0.0"
     source-map "^0.6.0"
 
-"@apm-js-collab/tracing-hooks@^0.12.0":
-  version "0.12.0"
-  resolved "https://registry.yarnpkg.com/@apm-js-collab/tracing-hooks/-/tracing-hooks-0.12.0.tgz#b65505d1d075fc8d8f4fa1973c37eaa9a9975b3f"
-  integrity sha512-U1cDbHOFbeToq5VWNcroBtQpz3hfH39uLkzJ5lorBFVNhHbTNj5MQvP+jODDwxBkG6A/agbQelG15rEoDgnjWg==
+"@apm-js-collab/tracing-hooks@^0.13.0":
+  version "0.13.0"
+  resolved "https://registry.yarnpkg.com/@apm-js-collab/tracing-hooks/-/tracing-hooks-0.13.0.tgz#20b2f77ec7a0e5dfd9fbf2215b56e2c2b7f41e4b"
+  integrity sha512-mTvWz9rnQwx1U3h0XPTHaX7bgfkpipLLTQyjlC2cdhQpQEuoLT0AGzoydeoq2NxfEVv6fWOOETcSbb2nptleyw==
   dependencies:
     "@apm-js-collab/code-transformer" "^0.18.0"
     debug "^4.4.1"