Reglas de Registro y Observabilidad

Los registros estructurados y los IDs de correlación hacen que los servicios de Node sean depurables en producción sin SSH y sin buscar cadenas no estructuradas.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

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();
});

Cuándo usarlo:

• Cada servicio HTTP de producción y trabajador en segundo plano.
• Las llamadas entre servicios necesitan cadenas de solicitud rastreables.
• El cumplimiento requiere pistas de auditoría sin fugas de PII.

Ejemplo de trabajo

// 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");
}

Lo que esto demuestra:

• Registros JSON a través de Pino con redacción de campos.
• Se respeta el X-Request-Id entrante; se genera si está ausente.
• El logger hijo lleva el requestId a través de la capa de servicio.

Análisis profundo

Cómo funciona

• Los registros estructurados son líneas JSON que pueden ser ingeridas por Loki, CloudWatch, Datadog.
• El ID de correlación se propaga a HTTP saliente a través del encabezado en los clientes internos.
• Niveles de registro: error para fallos que necesitan acción, warn para degradados, info para el ciclo de vida de la solicitud, debug solo para desarrollo.
• Las métricas (histograma de duración de la solicitud, tasa de error) complementan los registros para los SLO.

Campos requeridos

Notas de TypeScript

• Aumenta el tipo req.log para Express; Fastify usa req.log incorporado con integración pino.
• Nunca registres el req.body completo; registra solo los IDs y los nombres de las acciones.

Errores comunes

• console.log en producción - No estructurado, sin niveles, sin redacción. Solución: ESLint no-console en src/.
• Correlación faltante en trabajadores - Trabajos en cola no rastreables. Solución: pasa requestId en la carga útil del trabajo desde el manejador HTTP.
• Registro de PII - Violaciones de GDPR. Solución: redacta rutas; hashea los IDs de usuario en los registros si es necesario.
• Registros de depuración siempre activados - Costo y ruido en producción. Solución: LOG_LEVEL=info por defecto; depura mediante un interruptor dinámico con caducidad.
• Registro dentro de bucles cerrados - Picos de volumen de registro. Solución: agrega o muestrea; registra recuentos de resumen.

Alternativas

Preguntas frecuentes

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

Relacionado

• Lista de verificación de reglas del proyecto Node - reglas 14-15
• Reglas de seguridad - superposición de redacción de PII
• Reglas de API - respuesta de error vs detalle del registro

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.