Express.js
Explica cómo registrar eventos estructurados por request, correlacionar errores y redactar tokens, cookies, passwords y datos personales en aplicaciones Express.js.
Un log útil es un evento estructurado que permite reconstruir qué ocurrió sin exponer secretos. Imprimir strings arbitrarios no es una estrategia de observabilidad.
Logging responde preguntas concretas:
La estructura facilita búsqueda y agregación:
{
"level": "info",
"event": "http_request_completed",
"requestId": "req_123",
"method": "POST",
"route": "/orders",
"statusCode": 201,
"durationMs": 84,
"tenantId": "ten_42"
}Un mensaje como:
Something failedno permite correlacionar, filtrar ni distinguir contextos. Strings concatenados también dificultan ocultar datos sensibles.
Pino, Winston u otra librería pueden producir JSON. La elección importa menos que definir esquema, niveles y redacción.
const requestLogger = logger.child({
requestId,
tenantId,
actorId,
});Los child loggers evitan repetir contexto, pero no guardes objetos de request completos.
Acepta un ID externo únicamente si cumple formato y límites; de lo contrario genera uno.
const incoming = request.get('x-request-id');
const requestId = isValidRequestId(incoming)
? incoming
: crypto.randomUUID();Propágalo a dependencias y devuélvelo en response. Un trace ID puede cumplir una función relacionada, pero request ID y trace no son necesariamente idénticos.
Registra al finalizar, no solo al entrar:
function accessLog(request, response, next) {
const started = performance.now();
const log = logger.child({ requestId: response.locals.requestId });
response.once('finish', () => {
log.info({
event: 'http_request_completed',
method: request.method,
route: request.route?.path ?? 'unmatched',
statusCode: response.statusCode,
durationMs: performance.now() - started,
});
});
response.once('close', () => {
if (!response.writableFinished) {
log.warn({ event: 'http_request_aborted' });
}
});
next();
}Usa la plantilla de ruta, no URLs completas con IDs, para evitar alta cardinalidad.
Una convención posible:
debug: diagnóstico detallado habilitado temporalmente.info: eventos normales importantes.warn: degradación recuperable o comportamiento anómalo.error: operación fallida que requiere investigación.fatal: proceso no puede continuar.No marques como error cada 404 esperado. El nivel debe reflejar impacto operativo.
Serializa Error de forma que conserve:
El cliente recibe una versión pública; el log interno puede contener más detalle, sujeto a redacción.
La redacción debe ocurrir en el logger, no depender solo de que cada desarrollador recuerde.
const logger = pino({
redact: {
paths: [
'req.headers.authorization',
'req.headers.cookie',
'*.password',
'*.token',
],
censor: '[REDACTED]',
},
});Los paths exactos dependen de la estructura real.
Endpoints de alto volumen pueden generar demasiados logs. Sampling reduce coste, pero conserva:
No samples de forma que desaparezcan incidentes raros.
Un log técnico no es un audit trail confiable. Auditoría requiere:
Separa ambos propósitos. Los logs operativos pueden rotarse o samplearse.
Una orden falla por stock:
{
"level": "warn",
"event": "order_creation_rejected",
"requestId": "req_123",
"tenantId": "ten_42",
"actorId": "usr_8",
"reason": "INSUFFICIENT_STOCK",
"productCount": 3,
"durationMs": 31
}No necesitas registrar todos los items ni el body completo para diagnosticar el tipo de rechazo.
Registra nombre lógico, operación, duración y resultado:
{
"event": "dependency_call_completed",
"dependency": "payment-provider",
"operation": "create_intent",
"durationMs": 420,
"result": "timeout",
"attempt": 2
}Evita URL con query sensible y response body completo.
Logging síncrono o serialización de objetos grandes puede afectar latencia. En producción suele escribirse a stdout y un agente recoge. No hagas rotación compleja dentro de cada contenedor salvo necesidad.
Define:
Más retención no siempre es mejor si contiene datos sensibles.
console.log(request.body).Observabilidad: logs, métricas y trazas combina señales para responder no solo qué ocurrió, sino por qué y con qué impacto.