feat(nestjs): add orchestrion integration

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,45 @@
+# 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.
+
+> [!WARNING]
+>
+> ## ⚠️ Not yet runnable in CI
+>
+> This app installs `@apm-js-collab/code-transformer` from npm (a
+> transitive dep of `@sentry/node`/`@sentry/server-utils`).
+> Several spans depend on the `mutableResult` transform option,
+> which is **not in the published version yet**:
+>
+> - `request_context` (wraps the handler returned by
+>   `RouterExecutionContext.create`)
+> - `@Cron`/`@Interval`/`@Timeout`, `@OnEvent` (wrap the
+>   decorator the factory returns)
+>
+> `app_creation`, `request_handler`, and the
+> `@Injectable`/`@Catch` spans only need `astQuery` + argument
+> mutation (already published), so they should pass first.
+>
+> **Enable in CI once** the `@apm-js-collab/code-transformer`
+> changes (`mutableResult` + documented `astQuery`) are published
+> and pulled in. Until then keep this app out of the e2e run
+> list.

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,40 @@
+{
+  "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"
+  },
+  "sentryTest": {
+    "// skip": "Keep out of CI until @apm-js-collab/code-transformer (mutableResult + astQuery) is published. See README.md.",
+    "skip": true
+  }
+}

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');
+  }
+}

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

@@ -0,0 +1,12 @@
+import { ArgumentsHost, Catch, ExceptionFilter } from '@nestjs/common';
+import { Response } from 'express';
+import { ExampleException } from './example.exception';
+
+// `@Catch` exercises the exception_filter instrumentation.
+@Catch(ExampleException)
+export class ExampleExceptionFilter implements ExceptionFilter {
+  public catch(_exception: ExampleException, host: ArgumentsHost): void {
+    const response = host.switchToHttp().getResponse<Response>();
+    response.status(400).json({ message: 'handled by example filter' });
+  }
+}

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

@@ -0,0 +1,12 @@
+import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';
+import * as Sentry from '@sentry/nestjs';
+
+@Injectable()
+export class ExampleGuard implements CanActivate {
+  public canActivate(_context: ExecutionContext): boolean {
+    // Child span
+    // should nest under the guard span (middleware.nestjs / .guard).
+    Sentry.startSpan({ name: 'test-guard-span' }, () => undefined);
+    return true;
+  }
+}

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

@@ -0,0 +1,19 @@
+import { CallHandler, ExecutionContext, Injectable, NestInterceptor } from '@nestjs/common';
+import * as Sentry from '@sentry/nestjs';
+import { tap } from 'rxjs';
+
+@Injectable()
+export class ExampleInterceptor implements NestInterceptor {
+  public intercept(_context: ExecutionContext, next: CallHandler): ReturnType<CallHandler['handle']> {
+    // Runs before `next.handle()`
+    // nests under the interceptor "before" span.
+    Sentry.startSpan({ name: 'test-interceptor-span-before' }, () => undefined);
+    return next.handle().pipe(
+      tap(() => {
+        // Runs after the route
+        // nests under the "Interceptors - After Route" span.
+        Sentry.startSpan({ name: 'test-interceptor-span-after' }, () => undefined);
+      }),
+    );
+  }
+}

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

@@ -0,0 +1,13 @@
+import { Injectable, NestMiddleware } from '@nestjs/common';
+import * as Sentry from '@sentry/nestjs';
+import { NextFunction, Request, Response } from 'express';
+
+@Injectable()
+export class ExampleMiddleware implements NestMiddleware {
+  public use(_req: Request, _res: Response, next: NextFunction): void {
+    // Child span
+    // should nest under the middleware span.
+    Sentry.startSpan({ name: 'test-middleware-span' }, () => undefined);
+    next();
+  }
+}

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

@@ -0,0 +1,17 @@
+import * as Sentry from '@sentry/nestjs';
+
+// Opt into diagnostics-channel injection BEFORE `Sentry.init()`. This swaps
+// the OTel `Nest` instrumentation for the orchestrion (diagnostics-channel)
+// one and synchronously installs the module hooks that inject the channels
+Sentry.experimentalUseDiagnosticsChannelInjection();
+
+Sentry.init({
+  environment: 'qa', // dynamic sampling bias to keep transactions
+  dsn: process.env.E2E_TEST_DSN,
+  tunnel: 'http://localhost:3031/', // proxy server
+  tracesSampleRate: 1,
+  transportOptions: {
+    // We expect the app to send a lot of events in a short time
+    bufferSize: 1000,
+  },
+});

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

@@ -0,0 +1,16 @@
+// Import this first. It opts into diagnostics-channel injection and installs
+// the module hooks before any `@nestjs/*` module is loaded below.
+import './instrument';
+
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from './app.module';
+
+const PORT = 3030;
+
+async function bootstrap(): Promise<void> {
+  const app = await NestFactory.create(AppModule);
+  await app.listen(PORT);
+}
+
+// eslint-disable-next-line @typescript-eslint/no-floating-promises
+bootstrap();