Logging & Observability Rules

Structured logging and correlation IDs make Node services debuggable in production without SSH and grep of unstructured strings.

Recipe

Quick-reference recipe card - copy-paste ready.

import pino from "pino";
import { randomUUID } from "node:crypto";
 
export const logger = pino({ level: process.env.LOG_LEVEL ?? "info" });
 
app.use((req, res, next) => {
  const requestId = req.headers["x-request-id"]?.toString() ?? randomUUID();
  res.setHeader("X-Request-Id", requestId);
  req.log = logger.child({ requestId });
  next();
});

When to reach for this:

• Every production HTTP service and background worker.
• Cross-service calls need traceable request chains.
• Compliance requires audit trails without PII leakage.

Working Example

// src/logging/logger.ts
import pino from "pino";
 
export const rootLogger = pino({
  level: process.env.LOG_LEVEL ?? "info",
  redact: ["req.headers.authorization", "password", "creditCard"],
});
 
export type AppLogger = pino.Logger;

// src/middleware/request-context.ts
import { randomUUID } from "node:crypto";
import type { Request, Response, NextFunction } from "express";
 
import { rootLogger } from "../logging/logger.js";
 
declare global {
  namespace Express {
    interface Request {
      log: import("pino").Logger;
      requestId: string;
    }
  }
}
 
export function requestContext(req: Request, res: Response, next: NextFunction) {
  const requestId = (req.headers["x-request-id"] as string) ?? randomUUID();
  req.requestId = requestId;
  res.setHeader("X-Request-Id", requestId);
  req.log = rootLogger.child({ requestId, method: req.method, path: req.path });
  req.log.info("request started");
  res.on("finish", () => req.log.info({ status: res.statusCode }, "request finished"));
  next();
}

// src/services/billing.ts
export async function charge(log: AppLogger, customerId: string, cents: number) {
  log.info({ customerId, cents }, "charge started");
  // ...
  log.info({ customerId }, "charge completed");
}

What this demonstrates:

• JSON logs via Pino with field redaction.
• Incoming X-Request-Id respected; generated if absent.
• Child logger carries requestId through service layer.

Deep Dive

How It Works

• Structured logs are JSON lines ingestable by Loki, CloudWatch, Datadog.
• Correlation ID propagates to outbound HTTP via header on internal clients.
• Log levels: error for failures needing action, warn for degraded, info for request lifecycle, debug dev-only.
• Metrics (request duration histogram, error rate) complement logs for SLOs.

Required Fields

TypeScript Notes

• Type req.log augmentation for Express; Fastify uses built-in req.log with pino integration.
• Never log full req.body - log ids and action names only.

Gotchas

• console.log in production - Unstructured, no levels, no redaction. Fix: ESLint no-console in src/.
• Missing correlation on workers - Queue jobs untraceable. Fix: pass requestId in job payload from HTTP handler.
• Logging PII - GDPR violations. Fix: redact paths; hash user ids in logs if needed.
• Debug logs always on - Cost and noise in prod. Fix: LOG_LEVEL=info default; debug via dynamic toggle with expiry.
• Logging inside tight loops - Log volume spikes. Fix: aggregate or sample; log summary counts.

Alternatives

FAQs

await fetch(url, { headers: { "X-Request-Id": requestId } });

Related

• Node Project Rules Checklist - rules 14-15
• Security Rules - PII redaction overlap
• API Rules - error response vs log detail

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.