ref(server-utils, nestjs): move NestJS orchestrion configs out of server-utils

Introduce a dependency-injection approach to setting orchestrion
configuration from a standalone SDK that is not a part of the "normal"
tracing integrations reasonable to put in server-utils.

This also allows for better DRY sharing of reusable components between
the OTel and Orchestrion implementations of the NestJS integration.

The major change is that certain items like the list of Orchestrion
instrumentations, need to be fetched on demand with a method, rather
than being a static `as const` array.

Dependency cycle is still avoided, but all NestJS code is now in
packages/nest where it belongs.

Author: isaacs

packages/bun/src/plugin.ts

@@ -38,10 +38,11 @@ type UnknownPlugin = any;
 // module system.
 import codeTransformer from '@apm-js-collab/code-transformer-bundler-plugins/bun';
 import {
-  INSTRUMENTED_MODULE_NAMES,
+  instrumentedModuleNames,
   SENTRY_INSTRUMENTATIONS,
   withoutInstrumentedExternals,
 } from '@sentry/server-utils/orchestrion/config';
+import type { OrchestrionInstrumentation } from '@sentry/server-utils/orchestrion';
 
 const BUNDLER_MARKER_BANNER =
   ';(globalThis.__SENTRY_ORCHESTRION__=(globalThis.__SENTRY_ORCHESTRION__||{})).bundler=true;';
@@ -61,18 +62,25 @@ interface BunPluginBuilder {
  *
  * Pass the result to `Bun.build({ plugins: [...] })`.
  *
+ * A framework SDK that owns its own instrumentation can inject its
+ * `OrchestrionInstrumentation` descriptor via the `instrumentations` option, merged with the
+ * built-in configs.
+ *
  * @example
  * ```ts
  * import { sentryBunPlugin } from '@sentry/bun/plugin';
  * await Bun.build({ entrypoints: ['./app.ts'], plugins: [sentryBunPlugin()] });
  * ```
  */
-export function sentryBunPlugin(): UnknownPlugin {
+export function sentryBunPlugin(options?: { instrumentations?: OrchestrionInstrumentation[] }): UnknownPlugin {
+  const instrumentations = [...SENTRY_INSTRUMENTATIONS, ...(options?.instrumentations ?? []).flatMap(i => i.configs)];
+  const moduleNames = instrumentedModuleNames(instrumentations);
+
   // Typed upstream as an esbuild `Plugin`, but Bun passes its own
   // `PluginBuilder` (which has the `onLoad` the transform uses) to `setup`.
   // Cast to the Bun-compatible shape so we can forward Bun's builder to its
   // `setup`.
-  const transformer = codeTransformer({ instrumentations: SENTRY_INSTRUMENTATIONS }) as unknown as {
+  const transformer = codeTransformer({ instrumentations }) as unknown as {
     setup: (build: BunPluginBuilder) => void;
   };
 
@@ -91,7 +99,7 @@ export function sentryBunPlugin(): UnknownPlugin {
         // the transform's `onLoad`, so its diagnostics_channel calls would
         // be silently never injected. Bun has no runtime fallback here, so
         // bundling is the only injection path.
-        build.config.external = withoutInstrumentedExternals(build.config.external);
+        build.config.external = withoutInstrumentedExternals(build.config.external, moduleNames);
 
         // A blanket externalization strategy like `packages: 'external'` or
         // `'*'` in `external` externalizes instrumented packages too, and
@@ -113,7 +121,7 @@ export function sentryBunPlugin(): UnknownPlugin {
           console.warn(
             `[Sentry] This Bun build externalizes all dependencies (${blanketExternal}), so Sentry ` +
               'cannot instrument bundled libraries. Instrumentation will be missing for any of ' +
-              `these packages your app uses: ${INSTRUMENTED_MODULE_NAMES.join(', ')}. To instrument them, ` +
+              `these packages your app uses: ${moduleNames.join(', ')}. To instrument them, ` +
               'externalize only the specific packages you need external instead of all of them.',
           );
         }

packages/bun/src/sdk.ts

@@ -22,7 +22,7 @@ import {
   onUnhandledRejectionIntegration,
   processSessionIntegration,
 } from '@sentry/node';
-import { channelIntegrations, isOrchestrionInjected } from '@sentry/server-utils/orchestrion';
+import { getChannelIntegrations, isOrchestrionInjected } from '@sentry/server-utils/orchestrion';
 import { bunServerIntegration } from './integrations/bunserver';
 import { makeFetchTransport } from './transports';
 import type { BunOptions } from './types';
@@ -31,8 +31,8 @@ import type { BunOptions } from './types';
  * The orchestrion channel-subscriber integrations, listening on the diagnostics
  * channels that `@sentry/bun/plugin` injects at build time.
  */
-function getChannelIntegrations(): Integration[] {
-  return Object.values(channelIntegrations).map(integrationFactory => integrationFactory());
+function getChannelIntegrationInstances(): Integration[] {
+  return getChannelIntegrations().map(integrationFactory => integrationFactory());
 }
 
 /**
@@ -53,7 +53,7 @@ function getPerformanceIntegrations(options: Options): Integration[] {
     return autoPerformanceIntegrations;
   }
 
-  const channelIntegrationInstances = getChannelIntegrations();
+  const channelIntegrationInstances = getChannelIntegrationInstances();
   // The OTel integrations these channel subscribers replace, keyed by the name they share with them.
   const replacedOtelIntegrationNames = new Set(channelIntegrationInstances.map(integration => integration.name));
 

packages/nestjs/package.json

@@ -38,6 +38,11 @@
         "types": "./setup.d.ts",
         "default": "./build/cjs/setup.js"
       }
+    },
+    "./import": {
+      "import": {
+        "default": "./build/import.mjs"
+      }
     }
   },
   "publishConfig": {
@@ -48,7 +53,8 @@
     "@opentelemetry/instrumentation": "^0.220.0",
     "@sentry/conventions": "^0.15.1",
     "@sentry/core": "10.64.0",
-    "@sentry/node": "10.64.0"
+    "@sentry/node": "10.64.0",
+    "@sentry/server-utils": "10.64.0"
   },
   "devDependencies": {
     "@nestjs/common": "^10.0.0",

packages/nestjs/rollup.npm.config.mjs

@@ -1,7 +1,29 @@
+import { defineConfig } from 'rollup';
 import { makeBaseNPMConfig, makeNPMConfigVariants } from '@sentry-internal/rollup-utils';
 
-export default makeNPMConfigVariants(
-  makeBaseNPMConfig({
-    entrypoints: ['src/index.ts', 'src/setup.ts'],
+// EXPERIMENTAL: NestJS orchestrion `--import` runtime hook. A hand-written
+// `.mjs` shim referenced via `node --import @sentry/nestjs/import`. We pass it
+// through rollup only to copy it into `build/import.mjs` at the path the
+// package.json `exports` map expects; `external: /.*/` keeps every import (e.g.
+// `@sentry/nestjs/orchestrion`) as a runtime resolution against the installed
+// package.
+const orchestrionRuntimeHooks = [
+  defineConfig({
+    input: 'src/import.mjs',
+    external: /.*/,
+    output: { format: 'esm', file: 'build/import.mjs' },
   }),
-);
+];
+
+export default [
+  ...orchestrionRuntimeHooks,
+  ...makeNPMConfigVariants(
+    makeBaseNPMConfig({
+      // `src/orchestrion/index.ts` is internal (NOT a public export). It's listed
+      // as an entrypoint only to guarantee a stable `build/esm/orchestrion/index.js`
+      // output path, which the `build/import.mjs` `--import` hook references via a
+      // relative import to register the `nestjsOrchestrion` descriptor.
+      entrypoints: ['src/index.ts', 'src/setup.ts', 'src/orchestrion/index.ts'],
+    }),
+  ),
+];

packages/nestjs/src/debug-build.ts

@@ -0,0 +1,8 @@
+declare const __DEBUG_BUILD__: boolean;
+
+/**
+ * This serves as a build time flag that will be true by default, but false in non-debug builds or if users replace `__SENTRY_DEBUG__` in their generated code.
+ *
+ * ATTENTION: This constant must never cross package boundaries (i.e. be exported) to guarantee that it can be used for tree shaking.
+ */
+export const DEBUG_BUILD = __DEBUG_BUILD__;

packages/nestjs/src/import.mjs

@@ -0,0 +1,20 @@
+// EXPERIMENTAL: NestJS diagnostics-channel injection runtime hook. The
+// side-effecting `--import` entry (e.g. `node --import @sentry/nestjs/import app.js`)
+// that injects the @nestjs channels unconditionally before the app loads.
+//
+// Order matters and static ESM imports are hoisted: we import the register
+// FUNCTION (not a side-effecting base hook) and call it AFTER registering the
+// NestJS instrumentation, so the transform config includes the @nestjs configs.
+// The `nestjsOrchestrion` descriptor is an internal detail (not a public export),
+// so we reach it via a relative path into this package's own build output;
+// importing it has no side effects. It only defines the descriptor.
+//
+// This file ships verbatim to `build/import.mjs`; the relative import below
+// resolves to `build/esm/orchestrion/index.js` at runtime.
+
+import { registerOrchestrionInstrumentation } from '@sentry/server-utils/orchestrion';
+import { registerDiagnosticsChannelInjection } from '@sentry/server-utils/orchestrion/register';
+import { nestjsOrchestrion } from './esm/orchestrion/index.js';
+
+registerOrchestrionInstrumentation(nestjsOrchestrion);
+registerDiagnosticsChannelInjection();

packages/nestjs/src/integrations/helpers.ts

@@ -5,42 +5,87 @@ import {
   SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
   withActiveSpan,
 } from '@sentry/core';
+import { isOrchestrionInjected } from '@sentry/server-utils/orchestrion';
 import type { CatchTarget, InjectableTarget, NextFunction, Observable, Subscription } from './types';
 
-const sentryPatched = 'sentryPatched';
+/** A function of unknown signature, matching the methods/handlers we wrap. */
+export type AnyFn = (this: unknown, ...args: unknown[]) => unknown;
 
 /**
- * Helper checking if a concrete target class is already patched.
+ * Marks a function as already wrapped so repeated subscriptions/decoration
+ * don't double-wrap it. Shared by the OTel and orchestrion paths.
+ */
+const SENTRY_WRAPPED = Symbol.for('sentry.nestjs.wrapped');
+
+/** Whether `fn` has already been wrapped by this integration. */
+export function isWrapped(fn: AnyFn): boolean {
+  return !!(fn as AnyFn & Record<symbol, unknown>)[SENTRY_WRAPPED];
+}
+
+/** Mark `fn` as wrapped (see {@link isWrapped}). */
+export function markWrapped(fn: AnyFn): void {
+  (fn as AnyFn & Record<symbol, unknown>)[SENTRY_WRAPPED] = true;
+}
+
+/**
+ * Mark a target class as patched (for the given pass) so it's instrumented only
+ * once, and to stay idempotent across repeated subscriptions/decoration.
  *
- * We already guard duplicate patching with isWrapped. However, isWrapped checks whether a file has been patched, whereas we use this check for concrete target classes.
- * This check might not be necessary, but better to play it safe.
+ * The `@Injectable` and `@Catch` passes use *separate* flags on purpose: they
+ * wrap disjoint method sets (use/canActivate/transform/intercept vs catch), and
+ * a class can be decorated with both (an exception filter that also uses DI).
+ * A single shared flag would let whichever pass fired first latch it and block
+ * the other, dropping that pass's spans regardless of ordering.
  */
-export function isPatched(target: InjectableTarget | CatchTarget): boolean {
-  if (target.sentryPatched) {
+export function isTargetPatched(target: object, flag: 'sentryPatchedInjectable' | 'sentryPatchedCatch'): boolean {
+  if ((target as Record<string, unknown>)[flag]) {
     return true;
   }
-
-  addNonEnumerableProperty(target, sentryPatched, true);
+  addNonEnumerableProperty(target, flag, true);
   return false;
 }
 
+// The instrumentation path is reflected in the span origin: orchestrion-created
+// spans carry an `orchestrion` segment so they're distinguishable from OTel.
+// Only one path is ever live in a process (the OTel `Nest` integration is
+// swapped out whenever orchestrion is injected), so the global injection flag
+// reliably selects the right origin. Everything else about the span is identical.
+
+/** Origin for middleware/guard/pipe/interceptor/exception_filter spans. */
+function middlewareOrigin(componentType?: string): string {
+  const base = isOrchestrionInjected() ? 'auto.middleware.orchestrion.nestjs' : 'auto.middleware.nestjs';
+  return componentType ? `${base}.${componentType}` : base;
+}
+
+/** Origin for the app-creation / request-context / request-handler HTTP spans. */
+export function httpOrigin(): string {
+  return isOrchestrionInjected() ? 'auto.http.orchestrion.nestjs' : 'auto.http.otel.nestjs';
+}
+
+/** Origin for `@OnEvent` spans. */
+function eventOrigin(): string {
+  return isOrchestrionInjected() ? 'auto.event.orchestrion.nestjs' : 'auto.event.nestjs';
+}
+
+/** Origin for BullMQ `@Processor` `process` spans. */
+function bullmqOrigin(): string {
+  return isOrchestrionInjected() ? 'auto.queue.orchestrion.nestjs.bullmq' : 'auto.queue.nestjs.bullmq';
+}
+
 /**
  * Returns span options for nest middleware spans.
+ * name = provided name or class name.
  */
-// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 export function getMiddlewareSpanOptions(
-  target: InjectableTarget | CatchTarget,
+  target: InjectableTarget | CatchTarget | { name?: string },
   name: string | undefined = undefined,
   componentType: string | undefined = undefined,
-) {
-  const span_name = name ?? target.name; // fallback to class name if no name is provided
-  const origin = componentType ? `auto.middleware.nestjs.${componentType}` : 'auto.middleware.nestjs';
-
+): { name: string; attributes: Record<string, string> } {
   return {
-    name: span_name,
+    name: name ?? target.name ?? 'unknown',
     attributes: {
       [SEMANTIC_ATTRIBUTE_SENTRY_OP]: 'middleware.nestjs',
-      [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: origin,
+      [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: middlewareOrigin(componentType),
     },
   };
 }
@@ -57,7 +102,7 @@ export function getEventSpanOptions(event: string): {
     name: `event ${event}`,
     attributes: {
       [SEMANTIC_ATTRIBUTE_SENTRY_OP]: 'event.nestjs',
-      [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.event.nestjs',
+      [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: eventOrigin(),
     },
     forceTransaction: true,
   };
@@ -75,7 +120,7 @@ export function getBullMQProcessSpanOptions(queueName: string): {
     name: `${queueName} process`,
     attributes: {
       [SEMANTIC_ATTRIBUTE_SENTRY_OP]: 'queue.process',
-      [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.queue.nestjs.bullmq',
+      [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: bullmqOrigin(),
       'messaging.system': 'bullmq',
       'messaging.destination.name': queueName,
     },

packages/nestjs/src/integrations/sentry-nest-bullmq-instrumentation.ts

@@ -5,9 +5,9 @@ import {
   InstrumentationNodeModuleFile,
   isWrapped,
 } from '@opentelemetry/instrumentation';
-import { captureException, SDK_VERSION, startSpan, withIsolationScope } from '@sentry/core';
-import { getBullMQProcessSpanOptions } from './helpers';
+import { SDK_VERSION } from '@sentry/core';
 import type { ProcessorDecoratorTarget } from './types';
+import { extractQueueName, patchProcessorTarget } from './wrap-handlers';
 
 const supportedVersions = ['>=10.0.0'];
 const COMPONENT = '@nestjs/bullmq';
@@ -18,6 +18,9 @@ const COMPONENT = '@nestjs/bullmq';
  * This hooks into the `@Processor` class decorator, which is applied on queue processor classes.
  * It wraps the `process` method on the decorated class to fork the isolation scope for each job
  * invocation, create a span, and capture errors.
+ *
+ * The `process`-wrapping logic lives in `./wrappers` and is shared with the orchestrion
+ * (diagnostics-channel) path.
  */
 export class SentryNestBullMQInstrumentation extends InstrumentationBase {
   public constructor(config: InstrumentationConfig = {}) {
@@ -62,50 +65,13 @@ export class SentryNestBullMQInstrumentation extends InstrumentationBase {
     return function wrapProcessor(original: any) {
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       return function wrappedProcessor(...decoratorArgs: any[]) {
-        // Extract queue name from decorator args
-        // @Processor('queueName') or @Processor({ name: 'queueName' })
-        const queueName =
-          // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
-          typeof decoratorArgs[0] === 'string' ? decoratorArgs[0] : decoratorArgs[0]?.name || 'unknown';
+        const queueName = extractQueueName(decoratorArgs[0]);
 
-        // Get the original class decorator
         // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
         const classDecorator = original(...decoratorArgs);
 
-        // Return a new class decorator that wraps the process method
         return function (target: ProcessorDecoratorTarget) {
-          const originalProcess = target.prototype.process;
-
-          if (
-            originalProcess &&
-            typeof originalProcess === 'function' &&
-            !target.__SENTRY_INTERNAL__ &&
-            !originalProcess.__SENTRY_INSTRUMENTED__
-          ) {
-            target.prototype.process = new Proxy(originalProcess, {
-              apply: (originalProcessFn, thisArg, args) => {
-                return withIsolationScope(() => {
-                  return startSpan(getBullMQProcessSpanOptions(queueName), async () => {
-                    try {
-                      return await originalProcessFn.apply(thisArg, args);
-                    } catch (error) {
-                      captureException(error, {
-                        mechanism: {
-                          handled: false,
-                          type: 'auto.queue.nestjs.bullmq',
-                        },
-                      });
-                      throw error;
-                    }
-                  });
-                });
-              },
-            });
-
-            target.prototype.process.__SENTRY_INSTRUMENTED__ = true;
-          }
-
-          // Apply the original class decorator
+          patchProcessorTarget(target, queueName);
           // eslint-disable-next-line @typescript-eslint/no-unsafe-return
           return classDecorator(target);
         };