feat(nestjs): Automatic instrumentation of nestjs exception filters (#13230)

Adds automatic instrumentation of exception filters to `@sentry/nestjs`.
Exception filters in nest have a `@Catch` decorator and implement a
`catch` function. So we can use that to attach an instrumentation proxy.

Author: nicohrubec

dev-packages/e2e-tests/test-applications/nestjs-with-submodules/tests/transactions.test.ts

@@ -121,3 +121,77 @@ test('Sends an API route transaction from module', async ({ baseURL }) => {
     }),
   );
 });
+
+test('API route transaction includes exception filter span for global filter', async ({ baseURL }) => {
+  const transactionEventPromise = waitForTransaction('nestjs-with-submodules', transactionEvent => {
+    return (
+      transactionEvent?.contexts?.trace?.op === 'http.server' &&
+      transactionEvent?.transaction === 'GET /example-module/expected-exception' &&
+      transactionEvent?.request?.url?.includes('/example-module/expected-exception')
+    );
+  });
+
+  const response = await fetch(`${baseURL}/example-module/expected-exception`);
+  expect(response.status).toBe(400);
+
+  const transactionEvent = await transactionEventPromise;
+
+  expect(transactionEvent).toEqual(
+    expect.objectContaining({
+      spans: expect.arrayContaining([
+        {
+          span_id: expect.any(String),
+          trace_id: expect.any(String),
+          data: {
+            'sentry.op': 'middleware.nestjs',
+            'sentry.origin': 'auto.middleware.nestjs',
+          },
+          description: 'ExampleExceptionFilter',
+          parent_span_id: expect.any(String),
+          start_timestamp: expect.any(Number),
+          timestamp: expect.any(Number),
+          status: 'ok',
+          op: 'middleware.nestjs',
+          origin: 'auto.middleware.nestjs',
+        },
+      ]),
+    }),
+  );
+});
+
+test('API route transaction includes exception filter span for local filter', async ({ baseURL }) => {
+  const transactionEventPromise = waitForTransaction('nestjs-with-submodules', transactionEvent => {
+    return (
+      transactionEvent?.contexts?.trace?.op === 'http.server' &&
+      transactionEvent?.transaction === 'GET /example-module-local-filter/expected-exception' &&
+      transactionEvent?.request?.url?.includes('/example-module-local-filter/expected-exception')
+    );
+  });
+
+  const response = await fetch(`${baseURL}/example-module-local-filter/expected-exception`);
+  expect(response.status).toBe(400);
+
+  const transactionEvent = await transactionEventPromise;
+
+  expect(transactionEvent).toEqual(
+    expect.objectContaining({
+      spans: expect.arrayContaining([
+        {
+          span_id: expect.any(String),
+          trace_id: expect.any(String),
+          data: {
+            'sentry.op': 'middleware.nestjs',
+            'sentry.origin': 'auto.middleware.nestjs',
+          },
+          description: 'LocalExampleExceptionFilter',
+          parent_span_id: expect.any(String),
+          start_timestamp: expect.any(Number),
+          timestamp: expect.any(Number),
+          status: 'ok',
+          op: 'middleware.nestjs',
+          origin: 'auto.middleware.nestjs',
+        },
+      ]),
+    }),
+  );
+});

packages/nestjs/src/setup.ts

@@ -64,6 +64,8 @@ export { SentryTracingInterceptor };
  * Global filter to handle exceptions and report them to Sentry.
  */
 class SentryGlobalFilter extends BaseExceptionFilter {
+  public static readonly __SENTRY_INTERNAL__ = true;
+
   /**
    * Catches exceptions and reports them to Sentry unless they are expected errors.
    */
@@ -84,6 +86,8 @@ export { SentryGlobalFilter };
  * Service to set up Sentry performance tracing for Nest.js applications.
  */
 class SentryService implements OnModuleInit {
+  public static readonly __SENTRY_INTERNAL__ = true;
+
   /**
    * Initializes the Sentry service and registers span attributes.
    */

packages/node/src/integrations/tracing/nest/helpers.ts

@@ -1,6 +1,6 @@
 import { SEMANTIC_ATTRIBUTE_SENTRY_OP, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN } from '@sentry/core';
 import { addNonEnumerableProperty } from '@sentry/utils';
-import type { InjectableTarget } from './types';
+import type { CatchTarget, InjectableTarget } from './types';
 
 const sentryPatched = 'sentryPatched';
 
@@ -10,7 +10,7 @@ const sentryPatched = 'sentryPatched';
  * 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.
  */
-export function isPatched(target: InjectableTarget): boolean {
+export function isPatched(target: InjectableTarget | CatchTarget): boolean {
   if (target.sentryPatched) {
     return true;
   }
@@ -23,7 +23,7 @@ export function isPatched(target: InjectableTarget): boolean {
  * Returns span options for nest middleware spans.
  */
 // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
-export function getMiddlewareSpanOptions(target: InjectableTarget) {
+export function getMiddlewareSpanOptions(target: InjectableTarget | CatchTarget) {
   return {
     name: target.name,
     attributes: {

packages/node/src/integrations/tracing/nest/sentry-nest-instrumentation.ts

@@ -9,7 +9,7 @@ import { getActiveSpan, startSpan, startSpanManual, withActiveSpan } from '@sent
 import type { Span } from '@sentry/types';
 import { SDK_VERSION } from '@sentry/utils';
 import { getMiddlewareSpanOptions, isPatched } from './helpers';
-import type { InjectableTarget } from './types';
+import type { CatchTarget, InjectableTarget } from './types';
 
 const supportedVersions = ['>=8.0.0 <11'];
 
@@ -34,7 +34,10 @@ export class SentryNestInstrumentation extends InstrumentationBase {
   public init(): InstrumentationNodeModuleDefinition {
     const moduleDef = new InstrumentationNodeModuleDefinition(SentryNestInstrumentation.COMPONENT, supportedVersions);
 
-    moduleDef.files.push(this._getInjectableFileInstrumentation(supportedVersions));
+    moduleDef.files.push(
+      this._getInjectableFileInstrumentation(supportedVersions),
+      this._getCatchFileInstrumentation(supportedVersions),
+    );
     return moduleDef;
   }
 
@@ -58,10 +61,28 @@ export class SentryNestInstrumentation extends InstrumentationBase {
     );
   }
 
+  /**
+   * Wraps the @Catch decorator.
+   */
+  private _getCatchFileInstrumentation(versions: string[]): InstrumentationNodeModuleFile {
+    return new InstrumentationNodeModuleFile(
+      '@nestjs/common/decorators/core/catch.decorator.js',
+      versions,
+      (moduleExports: { Catch: CatchTarget }) => {
+        if (isWrapped(moduleExports.Catch)) {
+          this._unwrap(moduleExports, 'Catch');
+        }
+        this._wrap(moduleExports, 'Catch', this._createWrapCatch());
+        return moduleExports;
+      },
+      (moduleExports: { Catch: CatchTarget }) => {
+        this._unwrap(moduleExports, 'Catch');
+      },
+    );
+  }
+
   /**
    * Creates a wrapper function for the @Injectable decorator.
-   *
-   * Wraps the use method to instrument nest class middleware.
    */
   private _createWrapInjectable() {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -177,4 +198,33 @@ export class SentryNestInstrumentation extends InstrumentationBase {
       };
     };
   }
+
+  /**
+   * Creates a wrapper function for the @Catch decorator. Used to instrument exception filters.
+   */
+  private _createWrapCatch() {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return function wrapCatch(original: any) {
+      return function wrappedCatch(...exceptions: unknown[]) {
+        return function (target: CatchTarget) {
+          if (typeof target.prototype.catch === 'function' && !target.__SENTRY_INTERNAL__) {
+            // patch only once
+            if (isPatched(target)) {
+              return original(...exceptions)(target);
+            }
+
+            target.prototype.catch = new Proxy(target.prototype.catch, {
+              apply: (originalCatch, thisArgCatch, argsCatch) => {
+                return startSpan(getMiddlewareSpanOptions(target), () => {
+                  return originalCatch.apply(thisArgCatch, argsCatch);
+                });
+              },
+            });
+          }
+
+          return original(...exceptions)(target);
+        };
+      };
+    };
+  }
 }

packages/node/src/integrations/tracing/nest/types.ts

@@ -55,3 +55,15 @@ export interface InjectableTarget {
     intercept?: (context: unknown, next: CallHandler, ...args: any[]) => Observable<any>;
   };
 }
+
+/**
+ * Represents a target class in NestJS annotated with @Catch.
+ */
+export interface CatchTarget {
+  name: string;
+  sentryPatched?: boolean;
+  __SENTRY_INTERNAL__?: boolean;
+  prototype: {
+    catch?: (...args: any[]) => any;
+  };
+}