feat(nestjs): Instrument @nestjs/bullmq (#19759)

Add automatic instrumentation for BullMQ queue processors in NestJS via
the `@Processor` decorator from `@nestjs/bullmq`. Wraps the `process()`
method on `@Processor` decorated classes to fork an isolation scope per
job, create a `queue.process` transaction, and capture unhandled
exceptions. Also adds a dedicated `nestjs-bullmq` e2e test application
to test this setup.

Note: `@OnWorkerEvent` lifecycle handlers (e.g. `completed`, `failed`)
run outside the isolation scope created by `process()`. Breadcrumbs/tags
set in these handlers leak to the default isolation scope. This is
documented with a test and might be addressed in a follow-up.

Closes #12823

Author: nicohrubec

CHANGELOG.md

@@ -4,6 +4,16 @@
 
 - "You miss 100 percent of the chances you don't take. — Wayne Gretzky" — Michael Scott
 
+- **feat(nestjs): Instrument `@nestjs/bullmq` `@Processor` decorator**
+
+  Automatically capture exceptions and create transactions for BullMQ queue processors in NestJS applications.
+
+  When using the `@Processor` decorator from `@nestjs/bullmq`, the SDK now automatically wraps the `process()` method
+  to create `queue.process` transactions with proper isolation scopes, preventing breadcrumb and scope leakage between
+  jobs and HTTP requests. Errors thrown in processors are captured with the `auto.queue.nestjs.bullmq` mechanism type.
+
+  Requires `@nestjs/bullmq` v10.0.0 or later.
+
 - **feat(node): Expose `headersToSpanAttributes` option on `nativeNodeFetchIntegration()` ([#19770](https://github.com/getsentry/sentry-javascript/pull/19770))**
 
   Response headers like `http.response.header.content-length` were previously captured automatically on outgoing

dev-packages/e2e-tests/test-applications/nestjs-bullmq/.npmrc

@@ -0,0 +1,2 @@
+@sentry:registry=http://127.0.0.1:4873
+@sentry-internal:registry=http://127.0.0.1:4873

dev-packages/e2e-tests/test-applications/nestjs-bullmq/docker-compose.yml

@@ -0,0 +1,7 @@
+services:
+  redis:
+    image: redis:8
+    restart: always
+    container_name: e2e-tests-nestjs-bullmq-redis
+    ports:
+      - '6379:6379'

dev-packages/e2e-tests/test-applications/nestjs-bullmq/global-setup.mjs

@@ -0,0 +1,13 @@
+import { execSync } from 'child_process';
+import { dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export default async function globalSetup() {
+  // Start Redis via Docker Compose
+  execSync('docker compose up -d --wait', {
+    cwd: __dirname,
+    stdio: 'inherit',
+  });
+}

dev-packages/e2e-tests/test-applications/nestjs-bullmq/global-teardown.mjs

@@ -0,0 +1,13 @@
+import { execSync } from 'child_process';
+import { dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export default async function globalTeardown() {
+  // Stop Redis and remove containers
+  execSync('docker compose down --volumes', {
+    cwd: __dirname,
+    stdio: 'inherit',
+  });
+}

dev-packages/e2e-tests/test-applications/nestjs-bullmq/nest-cli.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/nest-cli",
+  "collection": "@nestjs/schematics",
+  "sourceRoot": "src",
+  "compilerOptions": {
+    "deleteOutDir": true
+  }
+}

dev-packages/e2e-tests/test-applications/nestjs-bullmq/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "nestjs-bullmq",
+  "version": "0.0.1",
+  "private": true,
+  "scripts": {
+    "build": "nest build",
+    "start": "nest start",
+    "start:dev": "nest start --watch",
+    "start:prod": "node dist/main",
+    "clean": "npx rimraf node_modules pnpm-lock.yaml",
+    "test": "playwright test",
+    "test:build": "pnpm install && pnpm build",
+    "test:assert": "pnpm test"
+  },
+  "dependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "@nestjs/platform-express": "^11.0.0",
+    "@nestjs/bullmq": "^11.0.0",
+    "bullmq": "^5.0.0",
+    "@sentry/nestjs": "latest || *",
+    "reflect-metadata": "^0.2.0",
+    "rxjs": "^7.8.1"
+  },
+  "devDependencies": {
+    "@playwright/test": "~1.56.0",
+    "@sentry-internal/test-utils": "link:../../../test-utils",
+    "@nestjs/cli": "^11.0.0",
+    "@nestjs/schematics": "^11.0.0",
+    "@types/node": "^18.19.1",
+    "typescript": "~5.0.0"
+  },
+  "volta": {
+    "extends": "../../package.json"
+  }
+}

dev-packages/e2e-tests/test-applications/nestjs-bullmq/playwright.config.mjs

@@ -0,0 +1,11 @@
+import { getPlaywrightConfig } from '@sentry-internal/test-utils';
+
+const config = getPlaywrightConfig({
+  startCommand: `pnpm start`,
+});
+
+export default {
+  ...config,
+  globalSetup: './global-setup.mjs',
+  globalTeardown: './global-teardown.mjs',
+};

dev-packages/e2e-tests/test-applications/nestjs-bullmq/src/app.controller.ts

@@ -0,0 +1,21 @@
+import { Controller, Get, Param } from '@nestjs/common';
+import { InjectQueue } from '@nestjs/bullmq';
+import { Queue } from 'bullmq';
+
+@Controller()
+export class AppController {
+  constructor(@InjectQueue('test-queue') private readonly queue: Queue) {}
+
+  @Get('enqueue/:name')
+  async enqueue(@Param('name') name: string) {
+    await this.queue.add(name, { timestamp: Date.now() });
+    return { queued: true };
+  }
+
+  @Get('check-isolation')
+  checkIsolation() {
+    // This endpoint is called after the processor adds a breadcrumb.
+    // The test verifies that breadcrumbs from the processor do NOT leak here.
+    return { message: 'ok' };
+  }
+}

dev-packages/e2e-tests/test-applications/nestjs-bullmq/src/app.module.ts

@@ -0,0 +1,25 @@
+import { Module } from '@nestjs/common';
+import { APP_FILTER } from '@nestjs/core';
+import { BullModule } from '@nestjs/bullmq';
+import { SentryGlobalFilter, SentryModule } from '@sentry/nestjs/setup';
+import { AppController } from './app.controller';
+import { TestProcessor } from './jobs/test.processor';
+
+@Module({
+  imports: [
+    SentryModule.forRoot(),
+    BullModule.forRoot({
+      connection: { host: 'localhost', port: 6379 },
+    }),
+    BullModule.registerQueue({ name: 'test-queue' }),
+  ],
+  controllers: [AppController],
+  providers: [
+    TestProcessor,
+    {
+      provide: APP_FILTER,
+      useClass: SentryGlobalFilter,
+    },
+  ],
+})
+export class AppModule {}