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.
- package/CHANGELOG.md +68 -0
- package/LICENSE +21 -0
- package/NOTICE.md +6 -0
- package/README.md +168 -2
- package/bin/nestjs-boost.mjs +148 -0
- package/guidelines/core.md +64 -0
- package/lib/agents.mjs +137 -0
- package/lib/installer.mjs +450 -0
- package/lib/prompt.mjs +131 -0
- package/lib/setup.mjs +60 -0
- package/manifest.json +676 -0
- package/package.json +67 -6
- package/scripts/postinstall.mjs +49 -0
- package/skills/nestjs-ai/SKILL.md +145 -0
- package/skills/nestjs-ai/references/ai-reference.md +143 -0
- package/skills/nestjs-architecture/SKILL.md +83 -0
- package/skills/nestjs-architecture/references/dynamic-modules.md +92 -0
- package/skills/nestjs-architecture/references/scopes-lifecycle.md +98 -0
- package/skills/nestjs-architecture/references/troubleshooting.md +77 -0
- package/skills/nestjs-authentication/SKILL.md +115 -0
- package/skills/nestjs-authentication/references/flows.md +180 -0
- package/skills/nestjs-authorization/SKILL.md +104 -0
- package/skills/nestjs-caching/SKILL.md +109 -0
- package/skills/nestjs-cli-tooling/SKILL.md +94 -0
- package/skills/nestjs-cli-tooling/references/nest-cli-json.md +91 -0
- package/skills/nestjs-configuration/SKILL.md +109 -0
- package/skills/nestjs-cqrs/SKILL.md +124 -0
- package/skills/nestjs-database-drizzle/SKILL.md +117 -0
- package/skills/nestjs-database-mikro-orm/SKILL.md +109 -0
- package/skills/nestjs-database-mongoose/SKILL.md +124 -0
- package/skills/nestjs-database-prisma/SKILL.md +126 -0
- package/skills/nestjs-database-sequelize/SKILL.md +88 -0
- package/skills/nestjs-database-typeorm/SKILL.md +110 -0
- package/skills/nestjs-deployment/SKILL.md +133 -0
- package/skills/nestjs-deployment/references/serverless-and-systemd.md +133 -0
- package/skills/nestjs-events/SKILL.md +78 -0
- package/skills/nestjs-file-storage/SKILL.md +111 -0
- package/skills/nestjs-file-storage/references/storage-reference.md +82 -0
- package/skills/nestjs-graphql/SKILL.md +119 -0
- package/skills/nestjs-graphql/references/federation.md +110 -0
- package/skills/nestjs-graphql/references/schema-features.md +133 -0
- package/skills/nestjs-health-checks/SKILL.md +114 -0
- package/skills/nestjs-http-client/SKILL.md +118 -0
- package/skills/nestjs-http-client/references/http-client-reference.md +116 -0
- package/skills/nestjs-http-platform/SKILL.md +104 -0
- package/skills/nestjs-http-platform/references/adapters.md +88 -0
- package/skills/nestjs-http-web-features/SKILL.md +113 -0
- package/skills/nestjs-http-web-features/references/uploads-streaming.md +108 -0
- package/skills/nestjs-i18n/SKILL.md +113 -0
- package/skills/nestjs-idempotency/SKILL.md +112 -0
- package/skills/nestjs-locks/SKILL.md +108 -0
- package/skills/nestjs-logging/SKILL.md +123 -0
- package/skills/nestjs-mail/SKILL.md +125 -0
- package/skills/nestjs-mail/references/mail-reference.md +90 -0
- package/skills/nestjs-mcp-server/SKILL.md +152 -0
- package/skills/nestjs-mcp-server/references/mcp-reference.md +146 -0
- package/skills/nestjs-microservices/SKILL.md +108 -0
- package/skills/nestjs-microservices/references/transports.md +117 -0
- package/skills/nestjs-observability/SKILL.md +108 -0
- package/skills/nestjs-observability/references/apm-and-otel.md +106 -0
- package/skills/nestjs-openapi/SKILL.md +90 -0
- package/skills/nestjs-openapi/references/swagger-reference.md +180 -0
- package/skills/nestjs-outbox/SKILL.md +119 -0
- package/skills/nestjs-outbox/references/outbox-reference.md +74 -0
- package/skills/nestjs-passport-auth/SKILL.md +125 -0
- package/skills/nestjs-queues/SKILL.md +118 -0
- package/skills/nestjs-queues/references/bull-legacy.md +75 -0
- package/skills/nestjs-request-pipeline/SKILL.md +146 -0
- package/skills/nestjs-request-pipeline/references/filters-interceptors.md +114 -0
- package/skills/nestjs-request-pipeline/references/pipes-decorators.md +80 -0
- package/skills/nestjs-resilience/SKILL.md +116 -0
- package/skills/nestjs-resilience/references/resilience-reference.md +74 -0
- package/skills/nestjs-scheduling/SKILL.md +100 -0
- package/skills/nestjs-security-hardening/SKILL.md +99 -0
- package/skills/nestjs-security-hardening/references/throttler-advanced.md +78 -0
- package/skills/nestjs-standalone-apps/SKILL.md +78 -0
- package/skills/nestjs-testing/SKILL.md +118 -0
- package/skills/nestjs-testing/references/advanced-testing.md +62 -0
- package/skills/nestjs-upgrading/SKILL.md +82 -0
- package/skills/nestjs-upgrading/references/esm-switch.md +114 -0
- package/skills/nestjs-validation-serialization/SKILL.md +124 -0
- package/skills/nestjs-validation-serialization/references/validation-options.md +84 -0
- package/skills/nestjs-webhooks/SKILL.md +116 -0
- package/skills/nestjs-webhooks/references/webhooks-reference.md +132 -0
- package/skills/nestjs-websockets/SKILL.md +108 -0
- package/skills/nestjs-workflows/SKILL.md +123 -0
- 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.
|