IDs de correlación de solicitudes

Rastrea una única solicitud de usuario a través de registros y servicios con x-request-id: acepta IDs entrantes, genera cuando faltan y reenvía a llamadas posteriores.

Receta

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

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

Cuándo usarlo:

• Depuración de "¿a qué logs pertenece este error 500?".
• Tickets de soporte con un único ID de los encabezados de respuesta.
• Trazado distribuido antes de la implementación completa de OpenTelemetry.
• Correlacionar logs de API con logs de trabajos de cola de trabajadores.

Ejemplo de trabajo

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

Lo que esto demuestra:

• x-request-id entrante se conserva cuando está presente y limitado (128 caracteres).
• La respuesta devuelve el mismo ID para la correlación cliente/soporte.
• fetch saliente reenvía el ID a los servicios internos.
• Todos los logs en la solicitud comparten requestId a través del logger hijo.

Análisis profundo

Cómo funciona

• El ID de correlación es una cadena opaca; UUID v4 es el valor predeterminado común.
• La puerta de enlace de borde (nginx, ALB, Cloudflare) puede inyectar x-request-id primero.
• Los servicios posteriores deben confiar pero validar el formato/longitud, no el contenido.
• trace_id de OpenTelemetry puede coexistir; muchos equipos mapean x-request-id a la raíz de la traza o al equipaje.

Convenciones de encabezado

Elige un ID principal en los logs; admite ambos encabezados en el borde durante la migración.

Fastify

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

• req.id y req.log incorporados: menos código repetitivo de middleware.

Trabajadores de cola

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

• Propaga el ID en la carga útil del trabajo o en las opciones del trabajo de BullMQ para trazas de extremo a extremo.

Errores comunes

• Generar un nuevo ID en cada salto interno: rompe la correlación. Solución: reenvía el ID entrante.
• Valores de encabezado ilimitados: inyección de logs / abuso de almacenamiento. Solución: longitud máxima de 64-128, alfanumérico + guion.
• No devolver el ID en la respuesta: el soporte no puede correlacionar. Solución: res.setHeader("x-request-id", id).
• Registrar el ID solo al principio: los errores profundos pierden contexto. Solución: logger hijo en req.log.
• Confiar en el ID del cliente para la autenticación: el ID no es un secreto. Solución: autenticación a través de JWT/sesión por separado.
• ID faltante en "disparar y olvidar" asíncrono: setImmediate pierde req. Solución: AsyncLocalStorage o captura el ID en el cierre.

Alternativas

Preguntas frecuentes

Relacionado

• Conceptos básicos de registro - campos estructurados
• pino - loggers hijos
• AsyncLocalStorage para el contexto - propagación implícita
• SDK de OpenTelemetry Node - contexto de traza

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