Regras de Logging & Observabilidade

Logs estruturados e IDs de correlação tornam os serviços Node depuráveis em produção sem SSH e grep de strings não estruturadas.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

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

Quando usar isso:

• Todo serviço HTTP de produção e worker em background.
• Chamadas entre serviços precisam de cadeias de requisição rastreáveis.
• Conformidade exige trilhas de auditoria sem vazamento de PII.

Exemplo de Trabalho

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

O que isso demonstra:

• Logs JSON via Pino com redação de campos.
• X-Request-Id de entrada respeitado; gerado se ausente.
• Logger filho carrega requestId pela camada de serviço.

Mergulho Profundo

Como Funciona

• Logs estruturados são linhas JSON que podem ser ingeridas por Loki, CloudWatch, Datadog.
• ID de correlação propaga para chamadas HTTP de saída via cabeçalho em clientes internos.
• Níveis de log: error para falhas que precisam de ação, warn para degradação, info para ciclo de vida da requisição, debug apenas para desenvolvimento.
• Métricas (histograma de duração da requisição, taxa de erro) complementam os logs para SLOs.

Campos Obrigatórios

Notas de TypeScript

• Tipo de aumento req.log para Express; Fastify usa req.log integrado com integração Pino.
• Nunca faça log do req.body completo - registre apenas IDs e nomes de ação.

Armadilhas

• console.log em produção - Não estruturado, sem níveis, sem redação. Correção: ESLint no-console em src/.
• Correlação ausente em workers - Tarefas de fila não rastreáveis. Correção: passe requestId no payload da tarefa do manipulador HTTP.
• Log de PII - Violações do GDPR. Correção: oculte caminhos; hasheie IDs de usuário nos logs, se necessário.
• Logs de debug sempre ativos - Custo e ruído em produção. Correção: LOG_LEVEL=info padrão; depure via alternância dinâmica com expiração.
• Log dentro de loops apertados - Picos de volume de log. Correção: agregue ou amostre; registre contagens de resumo.

Alternativas

FAQs

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

Relacionados

• Node Project Rules Checklist - regras 14-15
• Security Rules - sobreposição de redação de PII
• API Rules - resposta de erro vs detalhe do log

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (LTS Ativo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, e NestJS 11.