ref(nestjs): extract shared span helpers

Pull the span-emitting/patching logic out of the OTel
`InstrumentationBase` classes into `wrap-components`, `wrap-handlers`,
and `wrap-route` so it can be reused by the diagnostics-channel
integration.

Refactor only. There is still only the OTel implementation, which still
emits the same spans as before. However, this will be needed when the
next implementation is added.

Author: isaacs

packages/nestjs/src/integrations/helpers.ts

@@ -7,40 +7,103 @@ import {
 } from '@sentry/core';
 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.
- *
- * 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.
+ * Marks a function as already wrapped so repeated subscriptions/decoration
+ * don't double-wrap it.
  */
-export function isPatched(target: InjectableTarget | CatchTarget): boolean {
-  if (target.sentryPatched) {
-    return true;
+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;
+}
+
+/**
+ * The subset of `reflect-metadata`'s `Reflect` augmentation that NestJS
+ * relies on. Methods are optional because `reflect-metadata` may not be
+ * loaded; guard each before use.
+ */
+export interface ReflectWithMetadata {
+  getMetadataKeys?: (target: object) => unknown[];
+  getMetadata?: (key: unknown, target: object) => unknown;
+  defineMetadata?: (key: unknown, value: unknown, target: object) => void;
+}
+
+/**
+ * Copy NestJS reflect-metadata from one object onto another so decorators
+ * (param decorators, guards, `@EventPattern`, ...) that read it keep working
+ * No-op when `reflect-metadata` isn't loaded.
+ */
+export function copyReflectMetadata(from: object, to: object): void {
+  const R = Reflect as unknown as ReflectWithMetadata;
+  if (
+    typeof R.getMetadataKeys !== 'function' ||
+    typeof R.getMetadata !== 'function' ||
+    typeof R.defineMetadata !== 'function'
+  ) {
+    return;
   }
+  for (const key of R.getMetadataKeys(from)) {
+    R.defineMetadata(key, R.getMetadata(key, from), to);
+  }
+}
 
-  addNonEnumerableProperty(target, sentryPatched, 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.
+ */
+export function isTargetPatched(target: object, flag: 'sentryPatchedInjectable' | 'sentryPatchedCatch'): boolean {
+  if ((target as Record<string, unknown>)[flag]) {
+    return true;
+  }
+  addNonEnumerableProperty(target, flag, true);
   return false;
 }
 
+/** Origin for middleware/guard/pipe/interceptor/exception_filter spans. */
+function middlewareOrigin(componentType?: string): string {
+  return componentType ? `auto.middleware.nestjs.${componentType}` : 'auto.middleware.nestjs';
+}
+
+/**
+ * Origin for the app-creation / request-context / request-handler HTTP spans.
+ */
+export function httpOrigin(): string {
+  return 'auto.http.otel.nestjs';
+}
+
+/** Origin for `@OnEvent` spans. */
+function eventOrigin(): string {
+  return 'auto.event.nestjs';
+}
+
+/** Origin for BullMQ `@Processor` `process` spans. */
+function bullmqOrigin(): string {
+  return '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 +120,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 +138,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,19 +5,18 @@ 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';
 
 /**
  * Custom instrumentation for nestjs bullmq module.
  *
- * 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.
+ * This hooks into the `@Processor` class decorator, which is applied on queue
+ * processor classes.
  */
 export class SentryNestBullMQInstrumentation extends InstrumentationBase {
   public constructor(config: InstrumentationConfig = {}) {
@@ -62,50 +61,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);
         };

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

@@ -5,9 +5,10 @@ import {
   InstrumentationNodeModuleFile,
   isWrapped,
 } from '@opentelemetry/instrumentation';
-import { isObjectLike, captureException, SDK_VERSION, startSpan, withIsolationScope } from '@sentry/core';
-import { getEventSpanOptions } from './helpers';
+import { SDK_VERSION } from '@sentry/core';
+import type { AnyFn } from './helpers';
 import type { OnEventTarget } from './types';
+import { patchMethodDescriptor, wrapEventHandler } from './wrap-handlers';
 
 const supportedVersions = ['>=2.0.0'];
 const COMPONENT = '@nestjs/event-emitter';
@@ -16,9 +17,6 @@ const COMPONENT = '@nestjs/event-emitter';
  * Custom instrumentation for nestjs event-emitter
  *
  * This hooks into the `OnEvent` decorator, which is applied on event handlers.
- * Wrapped handlers run inside a forked isolation scope to ensure event-scoped data
- * (breadcrumbs, tags, etc.) does not leak between concurrent event invocations
- * or into subsequent HTTP requests.
  */
 export class SentryNestEventInstrumentation extends InstrumentationBase {
   public constructor(config: InstrumentationConfig = {}) {
@@ -62,87 +60,10 @@ export class SentryNestEventInstrumentation extends InstrumentationBase {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     return function wrapOnEvent(original: any) {
       return function wrappedOnEvent(event: unknown, options?: unknown) {
-        // Get the original decorator result
         const decoratorResult = original(event, options);
 
-        // Return a new decorator function that wraps the handler
         return (target: OnEventTarget, propertyKey: string | symbol, descriptor: PropertyDescriptor) => {
-          if (
-            !descriptor.value ||
-            typeof descriptor.value !== 'function' ||
-            target.__SENTRY_INTERNAL__ ||
-            // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
-            descriptor.value.__SENTRY_INSTRUMENTED__
-          ) {
-            return decoratorResult(target, propertyKey, descriptor);
-          }
-
-          function eventNameFromEvent(event: unknown): string {
-            if (typeof event === 'string') {
-              return event;
-            } else if (Array.isArray(event)) {
-              return event.map(eventNameFromEvent).join(',');
-            } else return String(event);
-          }
-
-          const originalHandler = descriptor.value;
-          // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
-          const handlerName = originalHandler.name || propertyKey;
-          let eventName = eventNameFromEvent(event);
-
-          // Instrument the actual handler
-          descriptor.value = async function (...args: unknown[]) {
-            // When multiple @OnEvent decorators are used on a single method, we need to get all event names
-            // from the reflector metadata as there is no information during execution which event triggered it
-            // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-            // @ts-ignore - reflect-metadata of nestjs adds these methods to Reflect
-            if (Reflect.getMetadataKeys(descriptor.value).includes('EVENT_LISTENER_METADATA')) {
-              // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-              // @ts-ignore - reflect-metadata of nestjs adds these methods to Reflect
-              const eventData = Reflect.getMetadata('EVENT_LISTENER_METADATA', descriptor.value);
-              if (Array.isArray(eventData)) {
-                eventName = eventData
-                  .map((data: unknown) => {
-                    if (isObjectLike(data) && 'event' in data && data.event) {
-                      return eventNameFromEvent(data.event);
-                    }
-                    return '';
-                  })
-                  .reverse() // decorators are evaluated bottom to top
-                  .join('|');
-              }
-            }
-
-            return withIsolationScope(() => {
-              return startSpan(getEventSpanOptions(eventName), async () => {
-                try {
-                  // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
-                  const result = await originalHandler.apply(this, args);
-                  return result;
-                } catch (error) {
-                  // exceptions from event handlers are not caught by global error filter
-                  captureException(error, {
-                    mechanism: {
-                      handled: false,
-                      type: 'auto.event.nestjs',
-                    },
-                  });
-                  throw error;
-                }
-              });
-            });
-          };
-
-          // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
-          descriptor.value.__SENTRY_INSTRUMENTED__ = true;
-
-          // Preserve the original function name
-          Object.defineProperty(descriptor.value, 'name', {
-            value: handlerName,
-            configurable: true,
-          });
-
-          // Apply the original decorator
+          patchMethodDescriptor(target, propertyKey, descriptor, (handler: AnyFn) => wrapEventHandler(handler, event));
           return decoratorResult(target, propertyKey, descriptor);
         };
       };