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

timfish · timfish · commit 300820f33db8 · 2026-07-14T22:09:47.000+01:00
diff --git a/packages/core/src/utils/worldwide.ts b/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 */
diff --git a/packages/server-utils/package.json b/packages/server-utils/package.json
@@ -93,9 +93,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@apm-js-collab/code-transformer-bundler-plugins": "^0.5.0",
+    "@apm-js-collab/code-transformer-bundler-plugins": "^0.6.0",
     "@apm-js-collab/code-transformer": "^0.18.0",
-    "@apm-js-collab/tracing-hooks": "^0.11.0",
+    "@apm-js-collab/tracing-hooks": "^0.12.0",
     "@sentry/conventions": "^0.15.1",
     "@sentry/core": "10.65.0",
     "magic-string": "~0.30.0"
diff --git a/packages/server-utils/src/orchestrion/detect.ts b/packages/server-utils/src/orchestrion/detect.ts
@@ -1,11 +1,6 @@
-import { debug } from '@sentry/core';
+import { debug, GLOBAL_OBJ } 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;
-}
-
 /**
  * Whether orchestrion has injected the diagnostics channels into this process,
  * either by the runtime `--import` hook / init-time registration (`runtime`)
@@ -16,40 +11,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',
+  );
 }
diff --git a/packages/server-utils/src/orchestrion/runtime/register.ts b/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 || g.bundler) {
+  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 || [];
 }
diff --git a/yarn.lock b/yarn.lock
@@ -414,6 +414,16 @@
     magic-string "^0.30.21"
     module-details-from-path "^1.0.4"
 
+"@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==
+  dependencies:
+    "@apm-js-collab/code-transformer" "^0.18.0"
+    es-module-lexer "^2.1.0"
+    magic-string "^0.30.21"
+    module-details-from-path "^1.0.4"
+
 "@apm-js-collab/code-transformer@^0.15.0":
   version "0.15.0"
   resolved "https://registry.yarnpkg.com/@apm-js-collab/code-transformer/-/code-transformer-0.15.0.tgz#a3a1b6c7b92db16f8277636b4a72a1626e2fa52a"
@@ -426,18 +436,6 @@
     semifies "^1.0.0"
     source-map "^0.6.0"
 
-"@apm-js-collab/code-transformer@^0.16.0":
-  version "0.16.0"
-  resolved "https://registry.yarnpkg.com/@apm-js-collab/code-transformer/-/code-transformer-0.16.0.tgz#f49f3f88839907aea86a23c0a8102ad5038b8273"
-  integrity sha512-J3YRXRsxr/d48E7iDOAyVLrqQMCGU1iHWxXPKq7EeXQTRDDJ50piOfQNqxsM7u4XogJlirXvLHIznr0T33HTKw==
-  dependencies:
-    "@types/estree" "^1.0.8"
-    astring "^1.9.0"
-    esquery "^1.7.0"
-    meriyah "^6.1.4"
-    semifies "^1.0.0"
-    source-map "^0.6.0"
-
 "@apm-js-collab/code-transformer@^0.18.0":
   version "0.18.0"
   resolved "https://registry.yarnpkg.com/@apm-js-collab/code-transformer/-/code-transformer-0.18.0.tgz#722972c05f04bc37f4bbd5067f42ffd7a990eee9"
@@ -450,12 +448,12 @@
     semifies "^1.0.0"
     source-map "^0.6.0"
 
-"@apm-js-collab/tracing-hooks@^0.11.0":
-  version "0.11.0"
-  resolved "https://registry.yarnpkg.com/@apm-js-collab/tracing-hooks/-/tracing-hooks-0.11.0.tgz#4c9c378695d65e90574893c1faba3c13b5bdbd14"
-  integrity sha512-5hWEcCGF4hcNh9lyB70p58pXn4HyUAVCad44wK6j110Ky+ivG19TfKHLB2aIDgItabCj6VPZm0DMAMNRnJDNBw==
+"@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==
   dependencies:
-    "@apm-js-collab/code-transformer" "^0.16.0"
+    "@apm-js-collab/code-transformer" "^0.18.0"
     debug "^4.4.1"
     module-details-from-path "^1.0.4"
 
