---

name: nestjs-observability description: Configure structured logging with Pino, Prometheus metrics, and health checks for NestJS services. Use when adding JSON logging, request tracing with correlation IDs, Prometheus metric endpoints, or liveness/readiness health checks. metadata: triggers: files: - 'main.ts' - '**/*.module.ts' keywords: - nestjs-pino - Prometheus - Logger - reqId

Observability Standards

Priority: P1 (HIGH)

Structured Logging (Pino)

Use nestjs-pino for high-performance, async JSON logging. Node's console.log blocking and unstructured.

See implementation examples

Tracing (Correlation)

• Request ID: Every log line must include reqId. nestjs-pino handles this via AsyncLocalStorage.
• Propagation: Pass x-request-id to downstream microservices and database queries for end-to-end tracing.

Metrics

Expose /metrics for Prometheus scraping using @willsoto/nestjs-prometheus.

See implementation examples

Health Checks

• Terminus: Implement "Liveness" (I'm alive) vs "Readiness" (I can take traffic).
• DB Check: TypeOrmHealthIndicator / PrismaHealthIndicator.
• Memory Check: Fail readiness if Heap > 300MB to prevent crash loops.

Performance Headers (Dev Only)

• X-Response-Duration-Ms, X-DB-Execution-Ms, X-API-Overhead-Ms
• Gate behind ENABLE_PERFORMANCE_BENCHMARK feature flag; never expose in production.

Anti-Patterns

• No console.log: Use nestjs-pino for async, structured, JSON-formatted logging.
• No missing reqId: Propagate x-request-id header to all downstream services and queries.
• No perf data in production by default: Gate benchmarking behind ENABLE_PERFORMANCE_BENCHMARK flag.