IDs de Correlação de Requisição

Rastreie uma única requisição de usuário através de logs e serviços com x-request-id - aceite IDs de entrada, gere quando ausente e encaminhe para chamadas downstream.

Receita

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

import { randomUUID } from "node:crypto";
 
function getRequestId(header: string | string[] | undefined): string {
  const raw = Array.isArray(header) ? header[0] : header;
  return raw && raw.length <= 128 ? raw : randomUUID();
}
 
// Middleware
app.use((req, res, next) => {
  const requestId = getRequestId(req.headers["x-request-id"]);
  req.headers["x-request-id"] = requestId;
  res.setHeader("x-request-id", requestId);
  req.log = logger.child({ requestId });
  next();
});

Quando usar isso:

• Depurando "quais logs pertencem a este erro 500?"
• Tickets de suporte com um único ID de cabeçalhos de resposta.
• Rastreamento distribuído antes da implantação completa do OpenTelemetry.
• Correlacionando logs de API com logs de trabalhos de fila de workers.

Exemplo de Trabalho

import express from "express";
import pino from "pino";
import { randomUUID } from "node:crypto";
 
const logger = pino({ level: "info" });
 
const app = express();
app.use(express.json());
 
app.use((req, res, next) => {
  const incoming = req.headers["x-request-id"];
  const requestId = typeof incoming === "string" && incoming.length <= 128
    ? incoming
    : randomUUID();
 
  res.setHeader("x-request-id", requestId);
  (req as express.Request & { log: pino.Logger; requestId: string }).log =
    logger.child({ requestId });
  (req as express.Request & { requestId: string }).requestId = requestId;
 
  req.log.info({ event: "request_start", method: req.method, path: req.path });
  next();
});
 
async function fetchBillingProfile(requestId: string, userId: string) {
  const res = await fetch(`https://billing.internal/users/${userId}`, {
    headers: { "x-request-id": requestId },
    signal: AbortSignal.timeout(3_000),
  });
  return res.json();
}
 
app.get("/users/:id/summary", async (req, res) => {
  const billing = await fetchBillingProfile(req.requestId, req.params.id);
  req.log.info({ event: "summary_built", billingStatus: billing.status });
  res.json({ userId: req.params.id, billing });
});
 
app.listen(3000);

O que isso demonstra:

• x-request-id de entrada preservado quando presente e limitado (128 caracteres).
• A resposta ecoa o mesmo ID para correlação de cliente/suporte.
• fetch de saída encaminha o ID para serviços internos.
• Todos os logs na requisição compartilham requestId via logger filho.

Mergulho Profundo

Como Funciona

• O ID de correlação é uma string opaca - UUID v4 é o padrão comum.
• O gateway de borda (nginx, ALB, Cloudflare) pode injetar x-request-id primeiro.
• Serviços downstream devem confiar, mas validar o formato/comprimento, não o conteúdo.
• O trace_id do OpenTelemetry pode coexistir - muitas equipes mapeiam x-request-id para a raiz do trace ou baggage.

Convenções de Cabeçalho

Escolha um ID principal nos logs; suporte ambos os cabeçalhos na borda durante a migração.

Fastify

const app = Fastify({
  genReqId: (req) => req.headers["x-request-id"] as string ?? randomUUID(),
  requestIdHeader: "x-request-id",
  requestIdLogLabel: "requestId",
});

• req.id e req.log integrados - menos boilerplate de middleware.

Workers de Fila

await queue.add("send-email", payload, {
  headers: { "x-request-id": req.requestId },
});

• Propague o ID na carga útil do trabalho ou nas opções do trabalho BullMQ para traces de ponta a ponta.

Armadilhas

• Gerar novo ID em cada salto interno - quebra a correlação. Correção: encaminhe o ID de entrada.
• Valores de cabeçalho ilimitados - injeção de log / abuso de armazenamento. Correção: comprimento máximo de 64-128, alfanumérico + hífen.
• Não retornar ID na resposta - o suporte não consegue correlacionar. Correção: res.setHeader("x-request-id", id).
• Registrar ID apenas no início - erros profundos perdem contexto. Correção: logger filho em req.log.
• Confiar no ID do cliente para autenticação - o ID não é um segredo. Correção: autentique via JWT/sessão separadamente.
• ID ausente em fire-and-forget assíncrono - setImmediate perde req. Correção: AsyncLocalStorage ou capture o ID no closure.

Alternativas

FAQs

Relacionados

• Noções Básicas de Logging - campos estruturados
• pino - loggers filhos
• AsyncLocalStorage para Contexto - propagação implícita
• OpenTelemetry Node SDK - contexto de trace

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