feat(nestjs): add orchestrion diagnostics-channel instrumentation (#22176)

Add the NestJS channel subscriber in `@sentry/nestjs`, plus its
code-transform config and channel names in `@sentry/server-utils`.

`nestIntegration` now uses the diagnostics-channel path when orchestrion
is injected and the vendored OTel path otherwise. Only the span origin
differs between the two implementations.

Fix: #20947
Fix: #20904
Fix: #20905
Fix: #20906
Fix: #20907
Fix: JS-2519
Fix: JS-2477
Fix: JS-2478
Fix: JS-2479
Fix: JS-2480

Author: isaacs

dev-packages/e2e-tests/test-applications/nestjs-orchestrion/.gitignore

@@ -0,0 +1,56 @@
+# compiled output
+/dist
+/node_modules
+/build
+
+# Logs
+logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+# OS
+.DS_Store
+
+# Tests
+/coverage
+/.nyc_output
+
+# IDEs and editors
+/.idea
+.project
+.classpath
+.c9/
+*.launch
+.settings/
+*.sublime-workspace
+
+# IDE - VSCode
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+
+# dotenv environment variable files
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# temp directory
+.temp
+.tmp
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json

dev-packages/e2e-tests/test-applications/nestjs-orchestrion/README.md

@@ -0,0 +1,31 @@
+# nestjs-orchestrion
+
+E2E test app for the **orchestrion** (diagnostics-channel
+injection) NestJS instrumentation. It is a normal
+`@sentry/nestjs` app whose only difference from `nestjs-basic` is
+that `src/instrument.ts` calls
+`Sentry.experimentalUseDiagnosticsChannelInjection()` before
+`Sentry.init()`. That swaps the OTel `Nest` integration for the
+orchestrion subscriber (`@sentry/server-utils/orchestrion`) and
+injects the diagnostics channels into `@nestjs/*` at load time.
+
+The tests assert the **same** span tree the OTel path produces
+(`nestjs-basic`), so this app is the opt-in side of an A/B
+against that baseline:
+
+- `transactions.test.ts`: `app_creation`, `request_context`,
+  `handler`, and the
+  `middleware.nestjs[.guard|.pipe|.interceptor|.exception_filter]`
+  spans.
+- `schedule.test.ts`: `@Cron`/`@Interval`/`@Timeout` error
+  mechanisms.
+- `events.test.ts`: the `@OnEvent` `event.nestjs` transaction.
+
+The spans that reassign the value a decorator factory / route
+handler returns (`request_context`,
+`@Cron`/`@Interval`/`@Timeout`, `@OnEvent`) rely on the
+transformer returning the (mutated) `ctx.result`. That is the
+default for `Sync`/`Async` transforms as of
+`@apm-js-collab/code-transformer` `0.16.0` (no `mutableResult`
+opt-in), which `@sentry/node`/`@sentry/server-utils` depend on,
+so this app runs against the published transformer.

dev-packages/e2e-tests/test-applications/nestjs-orchestrion/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-orchestrion/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "nestjs-orchestrion",
+  "version": "0.0.1",
+  "private": true,
+  "scripts": {
+    "build": "nest build",
+    "start": "nest start",
+    "start:prod": "node dist/main",
+    "clean": "npx rimraf node_modules pnpm-lock.yaml",
+    "test": "playwright test",
+    "test:build": "pnpm install",
+    "test:assert": "pnpm test"
+  },
+  "dependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "@nestjs/event-emitter": "^2.0.0",
+    "@nestjs/platform-express": "^11.0.0",
+    "@nestjs/schedule": "^4.1.0",
+    "@sentry/nestjs": "file:../../packed/sentry-nestjs-packed.tgz",
+    "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/express": "^5.0.0",
+    "@types/node": "^18.19.1",
+    "typescript": "~5.5.0"
+  },
+  "volta": {
+    "extends": "../../package.json"
+  }
+}

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

@@ -0,0 +1,7 @@
+import { getPlaywrightConfig } from '@sentry-internal/test-utils';
+
+const config = getPlaywrightConfig({
+  startCommand: `pnpm start`,
+});
+
+export default config;

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

@@ -0,0 +1,74 @@
+import { Controller, Get, Param, ParseIntPipe, UseGuards, UseInterceptors } from '@nestjs/common';
+import { AppService } from './app.service';
+import { ExampleException } from './example.exception';
+import { ExampleGuard } from './example.guard';
+import { ExampleInterceptor } from './example.interceptor';
+import { ScheduleService } from './schedule.service';
+
+@Controller()
+export class AppController {
+  public constructor(
+    private readonly appService: AppService,
+    private readonly scheduleService: ScheduleService,
+  ) {}
+
+  @Get('test-transaction')
+  public testTransaction(): unknown {
+    return this.appService.testSpan();
+  }
+
+  @Get('test-middleware')
+  public testMiddleware(): unknown {
+    return this.appService.testSpan();
+  }
+
+  @Get('test-guard')
+  @UseGuards(ExampleGuard)
+  public testGuard(): unknown {
+    return {};
+  }
+
+  @Get('test-interceptor')
+  @UseInterceptors(ExampleInterceptor)
+  public testInterceptor(): unknown {
+    return this.appService.testSpan();
+  }
+
+  @Get('test-pipe/:id')
+  public testPipe(@Param('id', ParseIntPipe) id: number): unknown {
+    return { value: id };
+  }
+
+  @Get('test-exception')
+  public testException(): never {
+    throw new ExampleException();
+  }
+
+  @Get('test-event')
+  public testEvent(): unknown {
+    this.appService.emitEvent();
+    return { message: 'emitted' };
+  }
+
+  // Triggers the `@Timeout`-decorated handler directly (its real delay is long
+  // so it never fires on its own during the test).
+  @Get('trigger-timeout-error')
+  public triggerTimeoutError(): unknown {
+    try {
+      this.scheduleService.handleTimeoutError();
+    } catch {
+      // Swallow, the error is captured by the schedule instrumentation; the
+      // route itself should still succeed.
+    }
+    return { message: 'triggered' };
+  }
+
+  // Stop the auto-firing scheduled jobs so they don't keep throwing after the
+  // assertions have run.
+  @Get('kill-schedules')
+  public killSchedules(): unknown {
+    this.scheduleService.killCron('test-cron-error');
+    this.scheduleService.killInterval('test-interval-error');
+    return { message: 'killed' };
+  }
+}

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

@@ -0,0 +1,31 @@
+import { MiddlewareConsumer, Module } from '@nestjs/common';
+import { APP_FILTER } from '@nestjs/core';
+import { EventEmitterModule } from '@nestjs/event-emitter';
+import { ScheduleModule } from '@nestjs/schedule';
+import { AppController } from './app.controller';
+import { AppService } from './app.service';
+import { EventsService } from './events.service';
+import { ExampleExceptionFilter } from './example.filter';
+import { ExampleMiddleware } from './example.middleware';
+import { ScheduleService } from './schedule.service';
+
+@Module({
+  imports: [EventEmitterModule.forRoot(), ScheduleModule.forRoot()],
+  controllers: [AppController],
+  providers: [
+    AppService,
+    EventsService,
+    ScheduleService,
+    // Global exception filter
+    // exercises the `@Catch` (exception_filter) instrumentation.
+    {
+      provide: APP_FILTER,
+      useClass: ExampleExceptionFilter,
+    },
+  ],
+})
+export class AppModule {
+  configure(consumer: MiddlewareConsumer): void {
+    consumer.apply(ExampleMiddleware).forRoutes('test-middleware');
+  }
+}

dev-packages/e2e-tests/test-applications/nestjs-orchestrion/src/app.service.ts

@@ -0,0 +1,17 @@
+import { Injectable } from '@nestjs/common';
+import { EventEmitter2 } from '@nestjs/event-emitter';
+import * as Sentry from '@sentry/nestjs';
+
+@Injectable()
+export class AppService {
+  public constructor(private readonly eventEmitter: EventEmitter2) {}
+
+  public testSpan(): void {
+    // A child span, to verify request handling nests under the nestjs spans.
+    Sentry.startSpan({ name: 'test-controller-span' }, () => undefined);
+  }
+
+  public emitEvent(): void {
+    this.eventEmitter.emit('test.event', { hello: 'world' });
+  }
+}

dev-packages/e2e-tests/test-applications/nestjs-orchestrion/src/events.service.ts

@@ -0,0 +1,12 @@
+import { Injectable } from '@nestjs/common';
+import { OnEvent } from '@nestjs/event-emitter';
+import * as Sentry from '@sentry/nestjs';
+
+@Injectable()
+export class EventsService {
+  // `@OnEvent` opens an `event.nestjs` transaction per handled event.
+  @OnEvent('test.event')
+  public handleTestEvent(): void {
+    Sentry.startSpan({ name: 'test-event-child-span' }, () => undefined);
+  }
+}

dev-packages/e2e-tests/test-applications/nestjs-orchestrion/src/example.exception.ts

@@ -0,0 +1,5 @@
+export class ExampleException extends Error {
+  public constructor() {
+    super('Example exception handled by the example filter');
+  }
+}