nestjs-boost 0.0.0-stage → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (87) hide show
  1. package/CHANGELOG.md +68 -0
  2. package/LICENSE +21 -0
  3. package/NOTICE.md +6 -0
  4. package/README.md +168 -2
  5. package/bin/nestjs-boost.mjs +148 -0
  6. package/guidelines/core.md +64 -0
  7. package/lib/agents.mjs +137 -0
  8. package/lib/installer.mjs +450 -0
  9. package/lib/prompt.mjs +131 -0
  10. package/lib/setup.mjs +60 -0
  11. package/manifest.json +676 -0
  12. package/package.json +67 -6
  13. package/scripts/postinstall.mjs +49 -0
  14. package/skills/nestjs-ai/SKILL.md +145 -0
  15. package/skills/nestjs-ai/references/ai-reference.md +143 -0
  16. package/skills/nestjs-architecture/SKILL.md +83 -0
  17. package/skills/nestjs-architecture/references/dynamic-modules.md +92 -0
  18. package/skills/nestjs-architecture/references/scopes-lifecycle.md +98 -0
  19. package/skills/nestjs-architecture/references/troubleshooting.md +77 -0
  20. package/skills/nestjs-authentication/SKILL.md +115 -0
  21. package/skills/nestjs-authentication/references/flows.md +180 -0
  22. package/skills/nestjs-authorization/SKILL.md +104 -0
  23. package/skills/nestjs-caching/SKILL.md +109 -0
  24. package/skills/nestjs-cli-tooling/SKILL.md +94 -0
  25. package/skills/nestjs-cli-tooling/references/nest-cli-json.md +91 -0
  26. package/skills/nestjs-configuration/SKILL.md +109 -0
  27. package/skills/nestjs-cqrs/SKILL.md +124 -0
  28. package/skills/nestjs-database-drizzle/SKILL.md +117 -0
  29. package/skills/nestjs-database-mikro-orm/SKILL.md +109 -0
  30. package/skills/nestjs-database-mongoose/SKILL.md +124 -0
  31. package/skills/nestjs-database-prisma/SKILL.md +126 -0
  32. package/skills/nestjs-database-sequelize/SKILL.md +88 -0
  33. package/skills/nestjs-database-typeorm/SKILL.md +110 -0
  34. package/skills/nestjs-deployment/SKILL.md +133 -0
  35. package/skills/nestjs-deployment/references/serverless-and-systemd.md +133 -0
  36. package/skills/nestjs-events/SKILL.md +78 -0
  37. package/skills/nestjs-file-storage/SKILL.md +111 -0
  38. package/skills/nestjs-file-storage/references/storage-reference.md +82 -0
  39. package/skills/nestjs-graphql/SKILL.md +119 -0
  40. package/skills/nestjs-graphql/references/federation.md +110 -0
  41. package/skills/nestjs-graphql/references/schema-features.md +133 -0
  42. package/skills/nestjs-health-checks/SKILL.md +114 -0
  43. package/skills/nestjs-http-client/SKILL.md +118 -0
  44. package/skills/nestjs-http-client/references/http-client-reference.md +116 -0
  45. package/skills/nestjs-http-platform/SKILL.md +104 -0
  46. package/skills/nestjs-http-platform/references/adapters.md +88 -0
  47. package/skills/nestjs-http-web-features/SKILL.md +113 -0
  48. package/skills/nestjs-http-web-features/references/uploads-streaming.md +108 -0
  49. package/skills/nestjs-i18n/SKILL.md +113 -0
  50. package/skills/nestjs-idempotency/SKILL.md +112 -0
  51. package/skills/nestjs-locks/SKILL.md +108 -0
  52. package/skills/nestjs-logging/SKILL.md +123 -0
  53. package/skills/nestjs-mail/SKILL.md +125 -0
  54. package/skills/nestjs-mail/references/mail-reference.md +90 -0
  55. package/skills/nestjs-mcp-server/SKILL.md +152 -0
  56. package/skills/nestjs-mcp-server/references/mcp-reference.md +146 -0
  57. package/skills/nestjs-microservices/SKILL.md +108 -0
  58. package/skills/nestjs-microservices/references/transports.md +117 -0
  59. package/skills/nestjs-observability/SKILL.md +108 -0
  60. package/skills/nestjs-observability/references/apm-and-otel.md +106 -0
  61. package/skills/nestjs-openapi/SKILL.md +90 -0
  62. package/skills/nestjs-openapi/references/swagger-reference.md +180 -0
  63. package/skills/nestjs-outbox/SKILL.md +119 -0
  64. package/skills/nestjs-outbox/references/outbox-reference.md +74 -0
  65. package/skills/nestjs-passport-auth/SKILL.md +125 -0
  66. package/skills/nestjs-queues/SKILL.md +118 -0
  67. package/skills/nestjs-queues/references/bull-legacy.md +75 -0
  68. package/skills/nestjs-request-pipeline/SKILL.md +146 -0
  69. package/skills/nestjs-request-pipeline/references/filters-interceptors.md +114 -0
  70. package/skills/nestjs-request-pipeline/references/pipes-decorators.md +80 -0
  71. package/skills/nestjs-resilience/SKILL.md +116 -0
  72. package/skills/nestjs-resilience/references/resilience-reference.md +74 -0
  73. package/skills/nestjs-scheduling/SKILL.md +100 -0
  74. package/skills/nestjs-security-hardening/SKILL.md +99 -0
  75. package/skills/nestjs-security-hardening/references/throttler-advanced.md +78 -0
  76. package/skills/nestjs-standalone-apps/SKILL.md +78 -0
  77. package/skills/nestjs-testing/SKILL.md +118 -0
  78. package/skills/nestjs-testing/references/advanced-testing.md +62 -0
  79. package/skills/nestjs-upgrading/SKILL.md +82 -0
  80. package/skills/nestjs-upgrading/references/esm-switch.md +114 -0
  81. package/skills/nestjs-validation-serialization/SKILL.md +124 -0
  82. package/skills/nestjs-validation-serialization/references/validation-options.md +84 -0
  83. package/skills/nestjs-webhooks/SKILL.md +116 -0
  84. package/skills/nestjs-webhooks/references/webhooks-reference.md +132 -0
  85. package/skills/nestjs-websockets/SKILL.md +108 -0
  86. package/skills/nestjs-workflows/SKILL.md +123 -0
  87. package/skills/nestjs-workflows/references/workflows-reference.md +85 -0
@@ -0,0 +1,146 @@
1
+ # @nestjs/mcp reference
2
+
3
+ ## Contents
4
+ - Module options
5
+ - Decorator options
6
+ - HTTP endpoint hardening
7
+ - stdio client configuration
8
+ - Observability
9
+ - Production checklist
10
+ - Testing
11
+ - Migrating from @rekog/mcp-nest
12
+
13
+ ## Module options
14
+
15
+ | Option | Default | Notes |
16
+ | --- | --- | --- |
17
+ | `name`, `version` | | Required; the server's identity |
18
+ | `title`, `description`, `websiteUrl`, `icons` | | Shown by clients |
19
+ | `instructions` | | How the model should use the server |
20
+ | `include` | every module | Modules scanned for primitives |
21
+ | `path` | `'mcp'` | `false` = no HTTP endpoint. Must be at the top level of `forRootAsync()` |
22
+ | `endpointVersion` | | With versioning on; `VERSION_NEUTRAL` keeps `/mcp`. Top level of `forRootAsync()` |
23
+ | `decorators` | `[]` | Class decorators on the endpoint controller (`Public()`, `UseGuards(...)`). Top level of `forRootAsync()` |
24
+ | `imports` | `[]` | Modules a verifier class injects from. Top level of `forRootAsync()` |
25
+ | `http.legacy` | `'stateless'` | `'reject'` serves 2026-07-28 only |
26
+ | `http.responseMode` | `'auto'` | `'json'` (drops progress notifications) / `'sse'` |
27
+ | `http.allowedOrigins` | localhost, 127.0.0.1, [::1] | Hostnames allowed in `Origin`; requests without `Origin` pass; `false` turns the check off |
28
+ | `http.allowedHosts` | not checked | Required `Host` names (DNS-rebinding defence) |
29
+ | `http.maxRequestBodySize` | 4 MiB | For bodies the platform didn't parse |
30
+ | `auth.verifier` | | A class or instance with `verifyAccessToken(token)` |
31
+ | `auth.resource` | | Canonical URL and token audience |
32
+ | `auth.authorizationServers` | | Accepted issuers |
33
+ | `auth.scopesSupported`, `auth.requiredScopes` | | Advertised scopes / scopes every request needs |
34
+ | `auth.resourceName`, `auth.resourceDocumentation` | | Extra protected-resource metadata |
35
+ | `stdio.legacy` | `'serve'` | `'reject'` refuses connections that use the 2025 handshake |
36
+
37
+ `forRootAsync()` accepts `useFactory`, `useClass` or `useExisting`. A verifier returned from the factory must be an instance.
38
+
39
+ ## Decorator options
40
+
41
+ | Decorator | Options |
42
+ | --- | --- |
43
+ | `@Tool()` | `name`, `title`, `description`, `inputSchema`, `outputSchema`, `annotations`, `icons`, `_meta`, `scopes` |
44
+ | `@Resource()` | `uri`, `name`, `title`, `description`, `mimeType`, `size`, `annotations`, `icons`, `_meta`, `cacheHint`, `scopes` |
45
+ | `@ResourceTemplate()` | `uriTemplate` (RFC 6570) plus the `@Resource()` options |
46
+ | `@Prompt()` | `name`, `title`, `description`, `argsSchema`, `icons`, `_meta`, `scopes` |
47
+
48
+ ## HTTP endpoint hardening
49
+
50
+ ```typescript
51
+ McpModule.forRoot({
52
+ name: 'cat-store', version: '1.0.0',
53
+ http: { allowedOrigins: ['support.catstore.example'], allowedHosts: ['api.catstore.example'] },
54
+ });
55
+
56
+ const app = await NestFactory.create<NestExpressApplication>(AppModule);
57
+ app.useBodyParser('json', { limit: '4mb' }); // Express defaults to 100 KB
58
+ app.enableCors({
59
+ origin: ['https://support.catstore.example'],
60
+ allowedHeaders: ['Authorization', 'Content-Type', 'Mcp-Protocol-Version', 'Mcp-Method', 'Mcp-Name'],
61
+ exposedHeaders: ['WWW-Authenticate'],
62
+ });
63
+ ```
64
+
65
+ - If a browser-based client is served from another origin, list it in **both** `allowedOrigins` (by hostname) and CORS.
66
+ - Global prefix: `app.setGlobalPrefix('api')` puts the endpoint at `/api/mcp`. Use `exclude: ['mcp']` to keep it at `/mcp`.
67
+ - API-key guards in `decorators` reject requests with 403 before any MCP message is read.
68
+
69
+ ## stdio client configuration
70
+
71
+ ```json
72
+ { "mcpServers": { "cat-store": { "command": "node", "args": ["/path/to/cat-store/dist/stdio.js"], "env": { "CAT_STORE_API_KEY": "..." } } } }
73
+ ```
74
+
75
+ One build can serve both transports: `main.ts` (HTTP) and `stdio.ts`. Set `path: false` if the app serves stdio only. `listen()` resolves when the client closes stdin.
76
+
77
+ ## Observability
78
+
79
+ With `@nestjs/observe`, MCP calls are named by operation (`tools/call find-order`, `resources/read orders://{orderId}`) instead of `POST /mcp`. No configuration is needed.
80
+
81
+ ## Production checklist
82
+
83
+ - `auth` is configured on network-reachable servers, with `resource` set to the public URL.
84
+ - `allowedHosts` is set on servers bound to localhost.
85
+ - Browser clients are listed in `allowedOrigins` and in CORS.
86
+ - The body parser limit exceeds your largest tool arguments.
87
+ - Descriptions are written for the model; `readOnlyHint` is set on non-mutating tools.
88
+ - The stdio entry point uses `McpStdioLogger`.
89
+
90
+ ## Testing
91
+
92
+ ```typescript
93
+ // test/test-token.verifier.ts: tokens need the server's resource and a future expiresAt
94
+ @Injectable()
95
+ export class TestTokenVerifier implements McpTokenVerifier {
96
+ async verifyAccessToken(token: string): Promise<AuthInfo | null> {
97
+ const t = TOKENS[token];
98
+ return t ? { token, clientId: t.clientId, scopes: t.scopes, resource: new URL(RESOURCE), expiresAt: Math.floor(Date.now() / 1000) + 3600, extra: { team: t.team } } : null;
99
+ }
100
+ }
101
+
102
+ moduleRef = await Test.createTestingModule({ imports: [AppModule] })
103
+ .overrideProvider(IdentityProviderTokenVerifier).useClass(TestTokenVerifier).compile();
104
+ client = await connectMcpClient(moduleRef, { token: 'support-token' }); // from '@nestjs/mcp/testing'; no HTTP server
105
+ const { tools } = await client.listTools();
106
+ const result = await client.callTool({ name: 'change-address', arguments: { orderId: 'ord_123', address: '12 Whisker Lane, Leeds' } });
107
+ expect(result.structuredContent).toEqual({ orderId: 'ord_123', address: '12 Whisker Lane, Leeds', status: 'pending' });
108
+ // afterAll: await client.close(); await moduleRef.close();
109
+ ```
110
+
111
+ - **Tool failures** come back as results: `isError: true`, with text such as `Input validation error` or `Forbidden resource`.
112
+ - **Resource and prompt failures** throw: `await expect(client.readResource({ uri: 'orders://ord_404' })).rejects.toThrow()`.
113
+ - **Scopes:** a missing scope throws `InsufficientScopeError` (`requiredScope`), and connecting without a token rejects with `SdkHttpError`. Both come from `@modelcontextprotocol/client`.
114
+ - **Options:**
115
+ - `headers` sends extra headers; guards read them lowercased from `ctx.request.headers`.
116
+ - `era: 'legacy'` tests a 2025-revision client (`client.getProtocolEra()`).
117
+ - **In-memory limits:** the in-memory client skips middleware and the endpoint's `decorators` guards, and `ctx.request` is a plain `{ method, url, headers }`. Test the route itself (401 + `resource_metadata=` challenge, 403 for a foreign `Origin`) over a socket. Use `app.listen(0)` and `fetch` to POST a `tools/list` JSON-RPC request with `accept: 'application/json, text/event-stream'`.
118
+ - **Registry rules:** `moduleRef.get(McpRegistry).tools` lets you enforce rules such as minimum description length. Call `moduleRef.init()` first if you haven't connected a client.
119
+ - **stdio:** build the app, then launch `dist/stdio.js` with the SDK's stdio client transport.
120
+
121
+ ## Migrating from @rekog/mcp-nest
122
+
123
+ ```bash
124
+ npm uninstall @rekog/mcp-nest @modelcontextprotocol/sdk # 2.x: also @modelcontextprotocol/core, @modelcontextprotocol/node, @rekog/mcp-nest-auth
125
+ npm i @nestjs/mcp @modelcontextprotocol/server zod
126
+ ```
127
+
128
+ | @rekog/mcp-nest | @nestjs/mcp |
129
+ | --- | --- |
130
+ | `transport` | HTTP unless `path: false`; stdio via `McpStdioServer` |
131
+ | `mcpEndpoint`, `apiPrefix` | `path` (under the global prefix) |
132
+ | `guards` | `decorators: [UseGuards(...)]` |
133
+ | `streamableHttp` | nothing to set (stateless); `http.responseMode` |
134
+ | `forFeature()` | one server per application |
135
+ | 2.x `McpStrategy` + `connectMicroservice` + `setHttpAdapter` | remove; `app.listen()` serves the route |
136
+ | `@McpController()` classes in `controllers` | `@Injectable()` providers in `providers`; remove `MCP_STRATEGY` |
137
+ | `parameters` | `inputSchema` (tools) / `argsSchema` (prompts) |
138
+ | `(args, context, request)` / `@Payload()` `@Ctx()` | `(input, ctx)`: `ctx.request`, `ctx.authInfo` |
139
+ | `context.reportProgress({ progress, total })` | `ctx.reportProgress(progress, total)` |
140
+ | `context.mcpServer.server.elicitInput()` | return `inputRequired()` |
141
+ | resource `({ uri })` | `ctx.uri`; templates receive their variables as input |
142
+ | `{ contents: [...] }` boilerplate | return the value; the module builds the result |
143
+ | `Scope.REQUEST` providers | singletons; read per-call data from `ctx` |
144
+ | `McpRegistryService.registerTool()` | not supported; use decorators |
145
+
146
+ Types such as `CallToolResult` now come from `@modelcontextprotocol/server`.
@@ -0,0 +1,108 @@
1
+ ---
2
+ name: nestjs-microservices
3
+ description: Builds message-based services with NestJS 12 @nestjs/microservices — NestFactory.createMicroservice, hybrid apps with connectMicroservice with inheritAppConfig, @MessagePattern request-response and @EventPattern events, @Payload/@Ctx with transport contexts, ClientsModule/ClientProxy send and emit, timeouts, TCP with TLS, Redis, MQTT, NATS v3 (@nats-io/transport-node), RabbitMQ with manual acks, Kafka (reply topics, retriable exceptions, offset commits), gRPC (protos, @GrpcMethod, streaming, GrpcException status codes, reflection, health), custom transporters and serializers, RpcException filters, pipes, guards, interceptors and pre-request hooks. Use when splitting a system into services, consuming or producing messages on a broker, exposing gRPC, connecting a microservice to an HTTP app, or debugging lost messages, missing replies, UNKNOWN gRPC errors or enhancers not running on message handlers. Not for reliable publish-after-commit (nestjs-outbox) or job queues (nestjs-queues).
4
+ compatibility: NestJS 12.x; @nestjs/microservices plus the transport driver (ioredis, mqtt, @nats-io/transport-node, amqplib + amqp-connection-manager, kafkajs, @grpc/grpc-js + @grpc/proto-loader)
5
+ metadata:
6
+ version: "0.1.0"
7
+ nestjs-major: "12"
8
+ docs-crawled: "2026-11-05"
9
+ ---
10
+
11
+ # NestJS microservices
12
+
13
+ ```bash
14
+ npm i @nestjs/microservices # + the driver for your transport (see table)
15
+ ```
16
+
17
+ | Transport | Driver | Pick when |
18
+ | --- | --- | --- |
19
+ | TCP (default) | built in | simple service-to-service RPC in a private network; TLS via `tlsOptions` |
20
+ | Redis | `ioredis` | already have Redis; fire-and-forget pub/sub (no persistence) |
21
+ | NATS | `@nats-io/transport-node` (v12 targets NATS v3; remove `nats`) | low-latency messaging, queue groups, wildcards |
22
+ | MQTT | `mqtt` | IoT, QoS levels |
23
+ | RabbitMQ | `amqplib amqp-connection-manager` | durable queues, acks, work distribution |
24
+ | Kafka | `kafkajs` | event streams, partitions, replay |
25
+ | gRPC | `@grpc/grpc-js @grpc/proto-loader` | typed contracts, streaming, polyglot clients |
26
+
27
+ TCP, Redis and core NATS deliver at most once ("published" = left the process). For must-not-lose events, use the outbox (nestjs-outbox) and/or an acknowledging broker.
28
+
29
+ ## Server
30
+
31
+ ```typescript
32
+ // standalone microservice — config from DI
33
+ const app = await NestFactory.createMicroservice<AsyncMicroserviceOptions>(AppModule, {
34
+ useFactory: (config: ConfigService) => ({ transport: Transport.NATS, options: { servers: [config.getOrThrow('NATS_URL')] } }),
35
+ inject: [ConfigService],
36
+ });
37
+ app.enableShutdownHooks();
38
+ await app.listen();
39
+
40
+ // hybrid: HTTP + transport
41
+ const app = await NestFactory.create(AppModule);
42
+ app.useGlobalPipes(new ValidationPipe({ transform: true })); // BEFORE connectMicroservice when inheriting
43
+ app.connectMicroservice<MicroserviceOptions>({ transport: Transport.TCP, options: { port: 3001 } }, { inheritAppConfig: true });
44
+ await app.listen(3000); // run lifecycle hooks first…
45
+ await app.startAllMicroservices(); // …then start consuming
46
+ ```
47
+
48
+ - Without `inheritAppConfig: true`, global pipes/guards/interceptors/filters (including `APP_*` providers) don't apply to connected microservices.
49
+ - `startAllMicroservices()` before `listen()/init()` consumes messages before `onModuleInit/onApplicationBootstrap` finish.
50
+ - Bind a handler to one transport in hybrids: `@MessagePattern('time.us.*', Transport.NATS)`.
51
+
52
+ ## Handlers (in controllers)
53
+
54
+ ```typescript
55
+ @Controller()
56
+ export class MathController {
57
+ @MessagePattern({ cmd: 'sum' }) // request-response; may return value, Promise or Observable
58
+ sum(@Payload() data: number[]): number { return data.reduce((a, b) => a + b, 0); }
59
+
60
+ @EventPattern('user_created') // fire-and-forget; several handlers run in parallel
61
+ async onUserCreated(@Payload() event: UserCreatedEvent, @Ctx() ctx: NatsContext) { … }
62
+ }
63
+ ```
64
+
65
+ - `@Payload('id')`, transport contexts (`NatsContext.getSubject()`, `RmqContext`, `KafkaContext`, `MqttContext`, `RedisContext`, `TcpContext`).
66
+ - Request-scoped providers: `@Inject(CONTEXT) ctx: RequestContext` (`pattern`, `data`, `context`).
67
+ - Make event handlers idempotent; brokers redeliver (`@Idempotent({ keyFrom: { payload: 'eventId' } })` — nestjs-idempotency).
68
+
69
+ ## Client
70
+
71
+ ```typescript
72
+ ClientsModule.registerAsync([{
73
+ name: 'MATH_SERVICE', imports: [ConfigModule], inject: [ConfigService],
74
+ useFactory: (config: ConfigService) => ({ transport: Transport.TCP, options: { host: config.get('MATH_HOST'), port: config.get('MATH_PORT') } }),
75
+ }]),
76
+
77
+ constructor(@Inject('MATH_SERVICE') private readonly client: ClientProxy) {}
78
+ sum(values: number[]) { return firstValueFrom(this.client.send<number>({ cmd: 'sum' }, values).pipe(timeout(5000))); } // cold: runs on subscribe
79
+ publish(event: UserCreatedEvent) { this.client.emit('user_created', event); } // hot: sent immediately
80
+ ```
81
+
82
+ - Clients connect lazily; `await this.client.connect()` in `onApplicationBootstrap` to fail fast.
83
+ - Always add `timeout()` to `send()`.
84
+ - `client.status` / `server.status` streams, `client.on('error', …)`, `unwrap<T>()` for the driver.
85
+ - Custom error/response handling: `customClass: ErrorHandlingProxy` extending `ClientTCP` and overriding `serializeError` / `serializeResponse`.
86
+
87
+ ## Errors, validation, enhancers
88
+
89
+ - Throw `RpcException('msg' | object)` → `{ status: 'error', message }`. RPC filters implement `RpcExceptionFilter` and **return an Observable** (`throwError(() => exception.getError())`); extend `BaseRpcExceptionFilter` to customize.
90
+ - Event handlers have no response channel: handle errors inside the filter.
91
+ - Pipes: `new ValidationPipe({ exceptionFactory: (errors) => new RpcException(errors) })`, or `@Payload({ schema })` + `StandardSchemaValidationPipe({ exceptionFactory: (issues) => new RpcException(issues) })`.
92
+ - Guards read metadata/user from `context.switchToRpc().getContext()` / `getData()`; throw `RpcException` (not `HttpException`).
93
+ - Pre-request hooks run before guards: `app.registerPreRequestHook((ctx, next) => new Observable((s) => als.run({ correlationId }, () => next().subscribe(s))))` — register before `listen()/init()` (hybrids: `connectMicroservice(opts, { deferInitialization: true })`).
94
+ - gRPC: throw `GrpcNotFoundException`, `GrpcAlreadyExistsException`, … or `new GrpcException(msg, GrpcStatus.X)`, and register `GrpcExceptionFilter`, otherwise clients get `UNKNOWN`.
95
+
96
+ ## Workflow
97
+
98
+ - [ ] 1. Choose the transport by delivery guarantees; install driver; configure server (async options) and clients from config.
99
+ - [ ] 2. Message/event handlers in controllers with validated payloads (`RpcException` factories).
100
+ - [ ] 3. Hybrid: `inheritAppConfig`, global enhancers before connecting, start order.
101
+ - [ ] 4. Timeouts on `send()`, idempotent consumers, acks/commits for brokers, trace propagation (nestjs-observability).
102
+ - [ ] 5. Tests: unit-test controllers directly; integration with a real broker (Testcontainers) or a TCP client against `app.listen()`. Build, lint, run tests, start both services.
103
+
104
+ ## Reference files
105
+
106
+ - `references/transports.md`: per-transport options, contexts, record builders, wildcards and quirks (Redis, MQTT QoS, NATS queue groups and headers, RabbitMQ acks and exchanges, Kafka reply topics, naming, retriable exceptions, offsets, regex patterns), gRPC protos/assets, client, streaming, reflection, health checks, metadata, TLS, and custom transporters. Read when configuring a specific transport.
107
+
108
+ Sources: [Overview](https://docs.nestjs.com/microservices/basics) · [Redis](https://docs.nestjs.com/microservices/redis) · [MQTT](https://docs.nestjs.com/microservices/mqtt) · [NATS](https://docs.nestjs.com/microservices/nats) · [RabbitMQ](https://docs.nestjs.com/microservices/rabbitmq) · [Kafka](https://docs.nestjs.com/microservices/kafka) · [gRPC](https://docs.nestjs.com/microservices/grpc) · [Custom transporters](https://docs.nestjs.com/microservices/custom-transport) · [Exception filters](https://docs.nestjs.com/microservices/exception-filters) · [Pipes](https://docs.nestjs.com/microservices/pipes) · [Pre-request hooks](https://docs.nestjs.com/microservices/pre-request-hooks) · [Guards](https://docs.nestjs.com/microservices/guards) · [Interceptors](https://docs.nestjs.com/microservices/interceptors) · [Hybrid application](https://docs.nestjs.com/faq/hybrid-application)
@@ -0,0 +1,117 @@
1
+ # Transport reference
2
+
3
+ ## Contents
4
+ - TCP (TLS)
5
+ - Redis
6
+ - MQTT
7
+ - NATS
8
+ - RabbitMQ
9
+ - Kafka
10
+ - gRPC
11
+ - Custom transporters
12
+
13
+ ## TCP (TLS)
14
+
15
+ Default transport. Server: `{ transport: Transport.TCP, options: { host, port, tlsOptions: { key, cert } } }`. Client: same with `tlsOptions: { ca: [caCert] }`. Status: `TcpStatus`; events `TcpEvents`; `unwrap<net.Socket>()` / `unwrap<net.Server>()`. From v12.1.1 client `on()` listeners survive reconnects until `close()`.
16
+
17
+ ## Redis
18
+
19
+ `npm i ioredis`. `{ transport: Transport.REDIS, options: { host, port, retryAttempts (0), retryDelay (5000), wildcards (false → psubscribe), …ioredis options } }`. Context: `RedisContext.getChannel()`. Pub/sub only — no persistence or acks; offline consumers miss messages.
20
+
21
+ ## MQTT
22
+
23
+ `npm i mqtt`. `{ transport: Transport.MQTT, options: { url: 'mqtt://localhost:1883', subscribeOptions: { qos: 2 }, …MQTT.js options } }`. Per-pattern QoS: `@EventPattern('critical-events', { qos: 2 })`. Wildcards `+`/`#` in patterns. `MqttRecordBuilder` for QoS/retain/properties per message; `MqttContext.getTopic()`, `getPacket()`.
24
+
25
+ ## NATS
26
+
27
+ `npm i @nats-io/transport-node` (v12 targets NATS v3; uninstall `nats`). Options: NATS connection options plus `queue` (queue group for load balancing), `gracefulShutdown` (unsubscribe, wait `gracePeriod` 10000 ms, close), `headers` (client default headers), custom `serializer`/`deserializer`.
28
+
29
+ ```typescript
30
+ const headers = nats.headers(); // from '@nats-io/nats-core'
31
+ headers.set('x-version', '1.0.0');
32
+ this.client.send('replace-emoji', new NatsRecordBuilder(':cat:').setHeaders(headers).build());
33
+ // server: context.getHeaders()?.get('x-version'); context.getSubject()
34
+ ```
35
+
36
+ Wildcards: `time.us.*`. Core NATS is at most once.
37
+
38
+ ## RabbitMQ
39
+
40
+ `npm i amqplib amqp-connection-manager`.
41
+
42
+ | Option | Notes |
43
+ | --- | --- |
44
+ | `urls`, `queue`, `queueOptions` (`durable`, …) | |
45
+ | `prefetchCount`, `isGlobalPrefetchCount` | flow control |
46
+ | `noAck` | default `true`; set `false` for manual acks |
47
+ | `persistent` | survive broker restarts (with a durable queue) |
48
+ | `noAssert` | skip `assertQueue` |
49
+ | `wildcards`, `exchange`, `exchangeType` (`topic` default), `exchangeArguments`, `routingKey` | topic routing with `*`/`#` |
50
+ | `headers` (producer), `replyQueue` (`amq.rabbitmq.reply-to`), `socketOptions`, `consumerTag`, `maxConnectionAttempts` (-1) | |
51
+
52
+ Manual ack:
53
+
54
+ ```typescript
55
+ @MessagePattern('notifications')
56
+ handle(@Payload() data: number[], @Ctx() ctx: RmqContext) {
57
+ ctx.getChannelRef().ack(ctx.getMessage()); // nack/reject for failures
58
+ }
59
+ ```
60
+
61
+ `RmqRecordBuilder(payload).setOptions({ headers, priority }).build()` for per-message options.
62
+
63
+ ## Kafka
64
+
65
+ `npm i kafkajs`. Options: `client` (KafkaJS client: `clientId`, `brokers`, SSL/SASL), `consumer` (`groupId`, …), `run`, `subscribe` (not topics), `producer`, `send`, `producerOnlyMode`, `postfixId`.
66
+
67
+ - Naming: Nest appends `-server` / `-client` to `clientId` and `groupId` (change with `postfixId`).
68
+ - Request-response needs reply topics: `client.subscribeToResponseOf('hero.kill.dragon')` in `onModuleInit` before `connect()`. Messages without `kafka_correlationId`/`kafka_replyTopic` headers (other producers) are treated as events.
69
+ - Patterns may be `RegExp` (v12): `@EventPattern(/^hero\..+$/)`.
70
+ - `KafkaContext`: `getMessage()`, `getPartition()`, `getTopic()`, `getConsumer()`, `getProducer()`, `getHeartbeat()`.
71
+ - Errors: unhandled errors in **event** handlers are retriable by default (kafkajs retries); in message handlers throw `KafkaRetriableException` to retry. Build max-retry/skip logic in an exception filter that republishes with a retry header and commits the offset when exhausted.
72
+ - Manual commits: `await ctx.getConsumer().commitOffsets([{ topic, partition, offset: (Number(offset) + 1).toString() }])` (disable auto-commit in `run`).
73
+ - Key messages (`{ key, value }`) to keep per-entity order within a partition.
74
+
75
+ ## gRPC
76
+
77
+ `npm i @grpc/grpc-js @grpc/proto-loader`; copy protos with `"assets": ["**/*.proto"], "watchAssets": true` in `nest-cli.json`.
78
+
79
+ ```typescript
80
+ // server
81
+ { transport: Transport.GRPC, options: { package: 'hero', protoPath: join(import.meta.dirname, 'hero/hero.proto'), url: '0.0.0.0:5000', loader: { keepCase: true } } }
82
+
83
+ @Controller()
84
+ export class HeroesController {
85
+ @GrpcMethod('HeroesService', 'FindOne')
86
+ findOne(data: HeroById, metadata: Metadata, call: ServerUnaryCall<any, any>): Hero { … }
87
+ }
88
+
89
+ // client
90
+ ClientsModule.register([{ name: 'HERO_PACKAGE', transport: Transport.GRPC, options: { package: 'hero', protoPath } }]);
91
+ onModuleInit() { this.heroes = this.client.getService<HeroesService>('HeroesService'); } // methods return Observables
92
+ ```
93
+
94
+ - Without `loader.keepCase: true`, fields with underscores aren't sent.
95
+ - Errors: status exceptions (`GrpcNotFoundException`, `GrpcInvalidArgumentException`, `GrpcPermissionDeniedException`, `GrpcResourceExhaustedException`, `GrpcDeadlineExceededException`, …) or `new GrpcException(msg, GrpcStatus.X)` + `app.useGlobalFilters(new GrpcExceptionFilter())`. `RpcException` with a numeric `code`/`status` also maps.
96
+ - Streaming: `@GrpcStreamMethod()` receives an `Observable` of requests and returns an `Observable` (Subject strategy); `@GrpcStreamCall()` gets the raw duplex stream. Generate interfaces with `ts-proto`.
97
+ - Metadata: read the 2nd argument; send with `call.sendMetadata(new Metadata())`.
98
+ - Reflection: `npm i @grpc/reflection`; `onLoadPackageDefinition: (pkg, server) => new ReflectionService(pkg).addToServer(server)`.
99
+ - Health: `npm i grpc-health-check`; include its proto in `protoPath` and in `onLoadPackageDefinition` create `HealthImplementation`, `addToServer(server)`, `setStatus('', 'SERVING')`.
100
+ - Multiple packages: `package: ['hero', 'hero2']`, `protoPath: [...]`.
101
+
102
+ ## Custom transporters
103
+
104
+ ```typescript
105
+ class GoogleCloudPubSubServer extends Server implements CustomTransportStrategy {
106
+ listen(callback: () => void) { /* subscribe; for each message: this.messageHandlers.get(pattern)?.(data, ctx) */ callback(); }
107
+ close() {}
108
+ on() { throw new Error('Method not implemented.'); }
109
+ unwrap<T>(): T { throw new Error('Method not implemented.'); }
110
+ }
111
+ NestFactory.createMicroservice(AppModule, { strategy: new GoogleCloudPubSubServer() });
112
+ ```
113
+
114
+ - `this.getHandlerByPattern(pattern)`, handler `isEventHandler` flag; report event handler errors yourself.
115
+ - Client side: extend `ClientProxy` (`connect`, `close`, `publish`, `dispatchEvent`, `unwrap`) and register with `ClientsModule.register([{ name, customClass: MyClientProxy, options }])`.
116
+ - Serialization: `serializer`/`deserializer` options, or override `serializeResponse()` / `serializeError()` in a `ClientProxy` subclass.
117
+ - If you don't need `@MessagePattern`/`@EventPattern`, a standalone app consuming the broker SDK directly may be simpler.
@@ -0,0 +1,108 @@
1
+ ---
2
+ name: nestjs-observability
3
+ description: Instruments NestJS 12 applications for production observability — the official @nestjs/observe SDK (createObserveModule, ObserveModule.forRoot/forRootAsync, the instrument option of NestFactory, npx @nestjs/observe link), automatic tracing of controllers, providers, guards, queues, database drivers, outbound HTTP and LLM calls, TracerService spans, captured errors, request-scoped attributes and custom metrics, trace propagation over HTTP, gRPC, microservices, GraphQL and BullMQ, users, tags, sampling, redaction and log correlation, @Objective SLOs, production rules, the Observe MCP server; and OpenTelemetry (zero-code auto-instrumentation, NodeSDK, OTLP export, W3C traceparent) and choosing an APM. Use when adding tracing, APM, error monitoring, metrics or SLOs, propagating trace ids between services, connecting OpenTelemetry/Jaeger/Tempo, or diagnosing slow requests in production. Not for application logging setup (nestjs-logging) or health endpoints (nestjs-health-checks).
4
+ compatibility: NestJS 12.x (@nestjs/core ≥11.1.4 for the instrument option); @nestjs/observe; optional @opentelemetry/* packages
5
+ metadata:
6
+ version: "0.1.0"
7
+ nestjs-major: "12"
8
+ docs-crawled: "2026-11-05"
9
+ ---
10
+
11
+ # NestJS observability
12
+
13
+ ## Choose
14
+
15
+ | Situation | Use |
16
+ | --- | --- |
17
+ | Nest services, want traces in Nest's vocabulary (`OrdersService.create`) with no collector to run | `@nestjs/observe` (hosted; free tier) |
18
+ | Mixed-language system or vendor-neutral standard | OpenTelemetry (optionally beside Observe with `openTelemetry: true`) |
19
+ | Frontend + backend error tracking first | Sentry |
20
+ | One platform for many languages and infrastructure | Datadog / New Relic |
21
+ | Data must stay on your infrastructure | Elastic APM or OTel → self-hosted backend |
22
+
23
+ Detect what the project already uses before adding another agent. Read `references/apm-and-otel.md` for the OpenTelemetry setups.
24
+
25
+ ## @nestjs/observe in three edits
26
+
27
+ ```bash
28
+ npx @nestjs/observe link # writes OBSERVE_APP_KEY/SECRET to .env, installs and wires the SDK (or do it by hand: npm i @nestjs/observe)
29
+ ```
30
+
31
+ ```typescript
32
+ // app.module.ts
33
+ export const { ObserveModule, ObserveInstrument } = createObserveModule(); // options: sourceContext, traceIdGenerator, skipInstrumentation…
34
+
35
+ @Module({
36
+ imports: [
37
+ ObserveModule.forRootAsync({ // FIRST import (before BullModule) so shutdown flushes running jobs
38
+ inject: [ConfigService],
39
+ useFactory: (config: ConfigService) => ({
40
+ enabled: config.get('NODE_ENV') === 'production', // sends nothing in dev/CI; TracerService still injectable
41
+ appKey: config.get('OBSERVE_APP_KEY', ''),
42
+ appSecret: config.get('OBSERVE_APP_SECRET', ''),
43
+ serviceId: 'orders-api',
44
+ http: { getUserId: (req) => req.user?.id ?? 'anonymous', ignore: ['/health'] },
45
+ }),
46
+ }),
47
+ ],
48
+ })
49
+ export class AppModule {}
50
+
51
+ // main.ts
52
+ const app = await NestFactory.create(AppModule, { instrument: ObserveInstrument });
53
+ // with an adapter, options move to the THIRD argument: NestFactory.create(AppModule, new FastifyAdapter(), { instrument: ObserveInstrument })
54
+ app.enableShutdownHooks(); // flush the last batch on SIGTERM
55
+ ```
56
+
57
+ - Works for `createMicroservice()` and application contexts too. Requires `@nestjs/graphql` ≥13.4.4 for GraphQL.
58
+ - Keys are credentials: env/secret manager only. `serviceVersion` is inferred from CI/platform/`.git`; in Docker pass `OBSERVE_SERVICE_VERSION=$GIT_SHA`.
59
+ - Automatic: requests (HTTP, GraphQL, gRPC, microservices, WebSockets), BullMQ/Bull jobs with queue wait and attempts, cron runs, provider methods, `pg`/`mysql2`/`mssql`/`mongodb` queries, `fetch`/undici/`node:http` calls (not billed), model calls via `fetch` (tokens only), runtime metrics, errors with source context.
60
+ - Tests booting with real credentials: `shutdownFlushTimeout: 0`.
61
+
62
+ ## Manual instrumentation (TracerService)
63
+
64
+ ```typescript
65
+ constructor(private readonly tracer: TracerService) {}
66
+
67
+ findOne(id: string) {
68
+ return this.tracer.createSpan('orders.findOne', async (span) => { // name the work, not the caller
69
+ span.addTags({ orderId: id });
70
+ return this.repo.findOne(id);
71
+ });
72
+ }
73
+ catch (e) { await this.tracer.captureError(e as Error, { accountId }); } // handled errors
74
+ this.tracer.setAttribute('tenantId', tenant.id); // request-scoped context store
75
+ this.tracer.counter('orders.placed', { description: 'Orders placed' }).increment(); // also gauge(), summary()
76
+ ```
77
+
78
+ `currentTraceId()` works anywhere; `activeSpan()` tags the enclosing span.
79
+
80
+ ## Propagation
81
+
82
+ - HTTP: automatic via `x-request-id` in and out (`fetch`, undici, `@nestjs/http-client`; `node:http` clients on Node ≥22.12). Older Node + axios: add the header in an interceptor with `tracer.currentTraceId()`.
83
+ - Microservices (TCP, Redis, NATS…), gRPC, GraphQL and BullMQ jobs inherit the trace (both sides need the SDK). Hybrid apps: write `traceIdGenerator` for both HTTP and RPC contexts.
84
+ - W3C `traceparent` interop and OTLP export: `openTelemetry: true`, `otlp: { endpoint }` or `otlp: true` (reads `OTEL_*`).
85
+
86
+ ## Shaping data
87
+
88
+ `tracesSampleRate` (number or predicate; errors and slow traces matter most), `http.capture` (extra headers/body for failed/slow requests), `redaction` (on by default; add `keys`, `patterns`), `forwardLogs`, `attachTraceIdToLogs` (default true, `ConsoleLogger` lines carry the trace id), `tags`, `setAttributes`, per-transport `ignore`, `outgoing: { database, http: { ignore, propagateTraceId }, llm }`, `spanCollapse`.
89
+
90
+ ## Objectives, rules, agents
91
+
92
+ - `@Objective({ availability: 99.9, latency: { underMs: 300, target: 99 } })` on a handler creates an SLO (targets 90–99.999, ≤10 per handler, `windowDays`).
93
+ - Production rules (dashboard): bound calls per execution, e.g. "`POST /checkout` calls `PaymentsService.charge` exactly once", "at most N LLM calls".
94
+ - MCP server for coding agents: `claude mcp add observe --transport http https://observe-api.nestjs.com/mcp` (Cursor/VS Code: same URL in `mcp.json`); query failures, traces and releases from the agent.
95
+
96
+ ## Workflow
97
+
98
+ - [ ] 1. Detect existing APM/OTel; choose per the table.
99
+ - [ ] 2. Observe: link or install; `createObserveModule()`; `ObserveModule` first in imports; `instrument` in `main.ts` (third arg with adapters); `enabled` by environment; shutdown hooks.
100
+ - [ ] 3. Add `getUserId`, ignore health checks, redaction keys; custom spans/metrics only where auto-instrumentation lacks business meaning.
101
+ - [ ] 4. Propagation across services; `openTelemetry: true` if other services use OTel.
102
+ - [ ] 5. Objectives for key routes; alerts. Build, lint, run tests, start the app (with `debug: true` once to confirm the SDK attached).
103
+
104
+ ## Reference files
105
+
106
+ - `references/apm-and-otel.md`: OpenTelemetry zero-code and NodeSDK setups for ESM/CJS, what OTel records on Nest 12, OTLP export details, Observe option reference, and APM comparison notes. Read when using OpenTelemetry or tuning SDK options.
107
+
108
+ Sources: [Overview](https://docs.nestjs.com/observability/overview) · [SDK](https://docs.nestjs.com/observability/sdk) · [Manual instrumentation](https://docs.nestjs.com/observability/manual-instrumentation) · [Distributed tracing](https://docs.nestjs.com/observability/distributed-tracing) · [Error monitoring](https://docs.nestjs.com/observability/error-monitoring) · [Dashboard](https://docs.nestjs.com/observability/dashboard) · [Production rules](https://docs.nestjs.com/observability/production-rules) · [MCP server](https://docs.nestjs.com/observability/mcp-server) · [OpenTelemetry](https://docs.nestjs.com/observability/opentelemetry) · [Choosing an APM](https://docs.nestjs.com/observability/choosing-an-apm)
@@ -0,0 +1,106 @@
1
+ # OpenTelemetry, Observe options and APM notes
2
+
3
+ ## Contents
4
+ - OpenTelemetry zero-code setup
5
+ - OpenTelemetry NodeSDK in code
6
+ - What OpenTelemetry records on NestJS 12
7
+ - Custom OpenTelemetry spans
8
+ - Observe beside OpenTelemetry and OTLP export
9
+ - Observe configuration reference
10
+ - Using more than one tool
11
+
12
+ ## OpenTelemetry zero-code setup
13
+
14
+ ```bash
15
+ npm i @opentelemetry/api @opentelemetry/auto-instrumentations-node
16
+
17
+ # CommonJS build
18
+ OTEL_SERVICE_NAME=orders-api OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
19
+ node --require @opentelemetry/auto-instrumentations-node/register dist/main.js
20
+
21
+ # ES module build (nest new default on v12) — the loader hook is required
22
+ OTEL_SERVICE_NAME=orders-api OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
23
+ node --experimental-loader=@opentelemetry/instrumentation/hook.mjs \
24
+ --import @opentelemetry/auto-instrumentations-node/register dist/main.js
25
+ ```
26
+
27
+ Can't change the command? Put the flags in `NODE_OPTIONS`. Instrumentation must load before Nest and the patched libraries.
28
+
29
+ ## OpenTelemetry NodeSDK in code
30
+
31
+ ```bash
32
+ npm i @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node @opentelemetry/exporter-trace-otlp-http
33
+ ```
34
+
35
+ ```typescript
36
+ // src/instrumentation.ts
37
+ export const otelSdk = new NodeSDK({
38
+ serviceName: 'orders-api',
39
+ traceExporter: new OTLPTraceExporter(), // OTEL_EXPORTER_OTLP_ENDPOINT, default http://localhost:4318
40
+ instrumentations: [getNodeAutoInstrumentations()],
41
+ });
42
+ otelSdk.start();
43
+ ```
44
+
45
+ Load it with `--require ./dist/instrumentation.js` (CJS) or `--experimental-loader=@opentelemetry/instrumentation/hook.mjs --import ./dist/instrumentation.js` (ESM). Importing it on the first line of `main.ts` only works for CommonJS builds. Call `otelSdk.shutdown()` after Nest shuts down (e.g. from `onApplicationShutdown()`).
46
+
47
+ ## What OpenTelemetry records on NestJS 12
48
+
49
+ - Auto-instrumentations: incoming/outgoing HTTP (incl. `fetch`), Express, `pg`, `mysql2`, `mongodb`, Mongoose.
50
+ - `@opentelemetry/instrumentation-nestjs-core` emits `Create Nest App`, `<Controller>.<method>` and `<method>` spans — **but at the time of writing supports `@nestjs/core` < 12**, so on Nest 12 those spans are missing.
51
+ - Spans stop at the controller: services, repositories, guards, interceptors and pipes aren't traced automatically — add spans yourself.
52
+
53
+ ## Custom OpenTelemetry spans
54
+
55
+ ```typescript
56
+ const tracer = trace.getTracer('orders-api');
57
+ return tracer.startActiveSpan('PricingService.quote', async (span) => {
58
+ try { span.setAttribute('cart.items', cart.items.length); return await this.calculate(cart); }
59
+ catch (e) { span.recordException(e as Error); span.setStatus({ code: SpanStatusCode.ERROR }); throw e; }
60
+ finally { span.end(); }
61
+ });
62
+ ```
63
+
64
+ ## Observe beside OpenTelemetry and OTLP export
65
+
66
+ ```typescript
67
+ ObserveModule.forRoot({ /* … */ openTelemetry: true, otlp: { endpoint: 'http://localhost:4318' } }); // or otlp: true → OTEL_* env vars
68
+ ```
69
+
70
+ - Incoming `traceparent` sets the trace id; outbound calls send `traceparent` (+ `x-request-id`), passing `tracestate` and sampling.
71
+ - An OTel SDK in the same process sets the trace; queue jobs and microservice messages stay in the request's trace in both tools (≥0.3.23).
72
+ - OTLP export (≥0.3.23) sends Observe's spans (requests as server spans, jobs as consumer spans, providers as internal, queries/calls as client spans) to any OTLP backend; paid plans export everything, Free exports what Observe keeps.
73
+ - Both hook DB drivers — tested with `pg`; verify other drivers in staging.
74
+
75
+ ## Observe configuration reference
76
+
77
+ `createObserveModule({ … })`: `sourceContext` (`linesOfContext` 5, `maxFrames` 5, `sourceMaps` false, or `false`), `traceIdKey` (`'traceId'`), `traceIdGenerator` (adopts well-formed `x-request-id`, else UUIDv7), `attachTraceIdToLogs` (true), `skipInstrumentation`.
78
+
79
+ `ObserveModule.forRoot({ … })`:
80
+
81
+ | Option | Notes |
82
+ | --- | --- |
83
+ | `appKey`, `appSecret` | or `OBSERVE_APP_KEY`/`OBSERVE_APP_SECRET` (env read when options resolve) |
84
+ | `endpoint` | default `https://observe-api.nestjs.com` (or `OBSERVE_ENDPOINT`) |
85
+ | `enabled` | `false` = no recording, no network, no credentials needed |
86
+ | `serviceId`, `serviceVersion` | unique serviceId per instance helps the profiler; version inferred |
87
+ | `http`, `rpc`, `grpc`, `graphql`, `ws` | `tags`, `setAttributes`, `getUserId`, `ignore` per transport |
88
+ | `jobs` | `tags`, `setAttributes` for queue/cron jobs |
89
+ | `http.queryParamsObfuscateRegex`, `http.capture` (`headers`, `body.maxBytes` ≤16384, `slowerThanMs`) | |
90
+ | `outgoing` | `database`, `http` (`ignore`, `propagateTraceId`), `llm` (`hosts` for gateways) or `false` |
91
+ | `openTelemetry`, `otlp` | see above |
92
+ | `runtimeMetrics`, `runtimeMetricsInterval` | default true / 60000 ms; also the heartbeat for silence alerts |
93
+ | `forwardLogs`, `redaction` (`enabled`, `useDefaultPatterns`, `patterns`, `keys`, `replacement`) | logs streaming is a paid feature |
94
+ | `tracesSampleRate` | 1.0, or `(protocol, attributes) => boolean` |
95
+ | `maxTracesPerBatch`, `flushInterval` | 1000 / 5000 ms |
96
+ | `spanCollapse` | collapse >20 identical sibling spans, keep slowest 3 |
97
+ | `shutdownFlushTimeout` | default 2000 ms (0 in tests) |
98
+ | `debug` | SDK diagnostics |
99
+
100
+ Overhead: ~0.1 ms median per request, ~8 µs CPU per request + 1–2.5 µs per traced call.
101
+
102
+ ## Using more than one tool
103
+
104
+ - Observe + OTel: `openTelemetry: true` (+ `otlp`) joins the shared traces.
105
+ - Observe + Datadog/New Relic: point `otlp` at the platform's OTLP endpoint.
106
+ - Observe + Sentry: Sentry on the frontend, Observe on the Nest backend.