feat(node): Only setup orchestrion channel listeners when needed

Author: mydea

packages/bun/src/plugin.ts

@@ -44,7 +44,7 @@ import {
 } from '@sentry/server-utils/orchestrion/config';
 
 const BUNDLER_MARKER_BANNER =
-  ';(globalThis.__SENTRY_ORCHESTRION__=(globalThis.__SENTRY_ORCHESTRION__||{})).bundler=true;';
+  ';(globalThis.__SENTRY_ORCHESTRION__=(globalThis.__SENTRY_ORCHESTRION__||{})).bundler=[];';
 
 // Minimal shape of Bun's `PluginBuilder` that we touch. Typed locally instead
 // of depending on `bun-types`, which would pull Bun's globals.
@@ -57,7 +57,7 @@ interface BunPluginBuilder {
  * with the central `SENTRY_INSTRUMENTATIONS`. The plugin injects
  * `diagnostics_channel.tracingChannel` calls into the instrumented libraries as
  * `bun build` bundles them, and injects a banner that sets
- * `globalThis.__SENTRY_ORCHESTRION__.bundler = true` when the bundle boots
+ * `globalThis.__SENTRY_ORCHESTRION__.bundler = []` when the bundle boots
  *
  * Pass the result to `Bun.build({ plugins: [...] })`.
  *

packages/core/src/client.ts

@@ -927,6 +927,16 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
    */
   public on(hook: 'stopUIProfiler', callback: () => void): () => void;
 
+  /**
+   * A hook that is called when the orchestrion runtime hook injects diagnostics
+   * channels into a module as it is loaded.
+   *
+   * The callback receives the name of the instrumented module.
+   *
+   * @returns {() => void} A function that, when executed, removes the registered callback.
+   */
+  public on(hook: 'orchestrion.module-runtime-injected', callback: (moduleName: string) => void): () => void;
+
   /**
    * Register a hook on this client.
    */
@@ -1188,6 +1198,12 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
    */
   public emit(hook: 'stopUIProfiler'): void;
 
+  /**
+   * Emit a hook event when the orchestrion runtime hook injects diagnostics
+   * channels into a module as it is loaded.
+   */
+  public emit(hook: 'orchestrion.module-runtime-injected', moduleName: string): void;
+
   /**
    * Emit a hook that was previously registered via `on()`.
    */

packages/server-utils/src/integrations/tracing-channel/express/index.ts

@@ -3,24 +3,35 @@ import type { IntegrationFn } from '@sentry/core';
 import { defineIntegration, waitForTracingChannelBinding } from '@sentry/core';
 import type { ExpressIntegrationOptions } from './types';
 import { instrumentExpress } from './instrumentation';
+import { expressModuleNames } from '../../../orchestrion/config/express';
+import { instrumentOrchestrion, instrumentOrchestrionLazy } from '../../../orchestrion/instrumentation';
 
 // NOTE: this uses the same name as the OTel integration by design.
 // When enabled, the OTel 'Express' integration is omitted from the default set.
 const INTEGRATION_NAME = 'Express' as const;
 
 const _expressChannelIntegration = ((options: ExpressIntegrationOptions = {}) => {
+  // `tracingChannel` is unavailable before Node 18.19 so do nothing in that case.
+  if (!diagnosticsChannel.tracingChannel) {
+    return {
+      name: INTEGRATION_NAME,
+    };
+  }
+
+  const instrumentFn = () => {
+    instrumentExpress(options, diagnosticsChannel.tracingChannel);
+  };
+
   return {
     name: INTEGRATION_NAME,
     setupOnce() {
-      // `tracingChannel` is unavailable before Node 18.19 so do nothing in that case.
-      if (!diagnosticsChannel.tracingChannel) {
-        return;
-      }
-
       waitForTracingChannelBinding(() => {
-        instrumentExpress(options, diagnosticsChannel.tracingChannel);
+        instrumentOrchestrion(expressModuleNames, instrumentFn);
       });
     },
+    setup(client) {
+      instrumentOrchestrionLazy(client, expressModuleNames, instrumentFn);
+    },
   };
 }) satisfies IntegrationFn;
 

packages/server-utils/src/orchestrion/config/express.ts

@@ -1,4 +1,5 @@
 import type { InstrumentationConfig } from '@apm-js-collab/code-transformer';
+import { uniq } from '@sentry/core';
 
 export const expressConfig = [
   // Express funnels every middleware/route handler through a single method on
@@ -54,7 +55,9 @@ export const expressConfig = [
     module: { name: 'router', versionRange: '>=2.0.0 <3', filePath: 'index.js' },
     functionQuery: { expressionName: 'use', kind: 'Sync' },
   },
-] satisfies InstrumentationConfig[];
+] as const satisfies InstrumentationConfig[];
+
+export const expressModuleNames = uniq(expressConfig.map(config => config.module.name));
 
 export const expressChannels = {
   // Express v4 runs each layer's handler through `Layer.prototype.handle_request`

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

@@ -50,3 +50,11 @@ export function detectOrchestrionSetup(): void {
       : '[Sentry] Bundler plugin did not run',
   );
 }
+
+/**
+ * Get a list of all module names (e.g. express, @nestjs/core, ...) that have been injected by orchestrion, either at runtime or via a bundler plugin.
+ */
+export function getOrchestrionInjectedModules(): string[] {
+  const { runtime, bundler } = GLOBAL_OBJ.__SENTRY_ORCHESTRION__ ?? {};
+  return [...(runtime ?? []), ...(bundler ?? [])];
+}

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

@@ -0,0 +1,53 @@
+import type { Client } from '@sentry/core';
+import { addNonEnumerableProperty } from '@sentry/core';
+import { getOrchestrionInjectedModules } from './detect';
+
+const INSTRUMENTATION_FN_SYMBOL = Symbol.for('InstrumentationFn');
+type InstrumentationFn = (() => void) & { [INSTRUMENTATION_FN_SYMBOL]?: boolean };
+
+/**
+ * Instrument the provided callback to run when one of the provided module names has been orchestrion-injected already.
+ * Make sure to pass the same callback instance to this as is passed to `instrumentOrchestrionLazy`.
+ */
+export function instrumentOrchestrion(moduleNames: string[], callback: InstrumentationFn) {
+  if (hasBeenInjected(callback)) {
+    return;
+  }
+
+  const modules = getOrchestrionInjectedModules();
+  if (moduleNames.some(name => modules.includes(name))) {
+    callback();
+    markAsInjected(callback);
+  }
+}
+
+/**
+ * Run the provided instrumentation callback when one of the provided module names has been orchestrion-injected at runtime.
+ * This listens to the `orchestrion.module-runtime-injected` event and runs the callback when the event is emitted.
+ * Make sure to pass the same callback instance to this as is passed to `instrumentOrchestrion`.
+ */
+export function instrumentOrchestrionLazy(client: Client, moduleNames: string[], callback: InstrumentationFn) {
+  if (hasBeenInjected(callback)) {
+    return;
+  }
+
+  const cleanup = client.on('orchestrion.module-runtime-injected', (moduleName: string) => {
+    if (moduleNames.includes(moduleName)) {
+      if (hasBeenInjected(callback)) {
+        cleanup();
+        return;
+      }
+      callback();
+      markAsInjected(callback);
+      cleanup();
+    }
+  });
+}
+
+function hasBeenInjected(callback: InstrumentationFn) {
+  return callback[INSTRUMENTATION_FN_SYMBOL] ?? false;
+}
+
+function markAsInjected(callback: InstrumentationFn) {
+  addNonEnumerableProperty(callback, INSTRUMENTATION_FN_SYMBOL, true);
+}

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

@@ -1,4 +1,4 @@
-import { debug, GLOBAL_OBJ } from '@sentry/core';
+import { debug, getClient, GLOBAL_OBJ } from '@sentry/core';
 import { createRequire } from 'node:module';
 import * as Module from 'node:module';
 import { pathToFileURL } from 'node:url';
@@ -115,6 +115,8 @@ export function registerDiagnosticsChannelInjection(options?: RegisterDiagnostic
         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);
+
+        getClient()?.emit('orchestrion.module-runtime-injected', event.moduleName);
       });
 
       initialize({ instrumentations: SENTRY_INSTRUMENTATIONS });