Mejores prácticas de registro

Registra campos accionables; muestrea la depuración en producción con moderación. Estas reglas mantienen los registros de Node.js buscables, conformes y económicos a escala.

Cómo usar esta lista

• Revisa en cada nuevo middleware, cliente saliente y procesador de trabajador.
• Combínalo con Redacción y cumplimiento de PII antes de SOC2.
• Agrega una prueba de instantánea de CI para las rutas de redacción en cargas útiles de muestra.
• Alinea los nombres de los campos (requestId, tenantId) en los microservicios en un documento compartido.

A - Estructura y niveles

• Un objeto JSON por línea a stdout. Sin concatenación de cadenas o volcados de pila de varias líneas como texto plano.
• Campo event o action estable para registros de negocio. order_created, no un vago done.
• info para el ciclo de vida de la solicitud y eventos de negocio. error para fallos que requieren acción.
• debug desactivado o muestreado en producción. LOG_LEVEL=info por defecto; muestreo de cola para investigaciones.
• Prohíbe console.log en src/ a través de ESLint. Excepción solo para puntos de entrada CLI.

B - Contexto de la solicitud

• Acepta o genera x-request-id en el borde. Devuelve el mismo ID en el encabezado de respuesta.
• Registrador secundario o ALS para requestId en cada línea. Sin paso manual en capas profundas sin ALS.
• Reenvía x-request-id en HTTP saliente y trabajos en cola. Correlación de extremo a extremo.
• Registra método, ruta, estado, duración al finalizar. Excluye /health o registra en depuración.
• Vincula userId/tenantId después de la autenticación en el registrador secundario. No antes de que la autenticación sea exitosa.

C - Seguridad y cumplimiento

• redact de Pino para autorización, cookies, contraseñas, PAN. Consulta pino.
• Los serializadores personalizados eliminan PII de los objetos req y user. Registra IDs, no correos electrónicos.
• Documenta el TTL de retención de registros por entorno. Típico de 30 a 90 días para producción, alineado con GDPR.
• Índices de registro separados por entorno. Sin tráfico de producción en agregadores de desarrollo.
• Nunca registres req.body completo o error.response.data de Axios por defecto.

D - Rendimiento y operaciones

• No uses pino-pretty en producción. Solo JSON; el transporte bonito bloquea el bucle de eventos.
• Evita registrar dentro de bucles cerrados. Agrega recuentos o muestrea 1/N.
• Un único registrador raíz por proceso con base: { service, version }. Metadatos de flota buscables.
• Envía registros a través de stdout + sidecar de agente. No rotación de archivos a nivel de aplicación en contenedores.
• Alerta sobre picos de volumen de registros. A menudo indica tormentas de errores o depuración activada.

E - Integración de observabilidad

• Comparte trace_id con OpenTelemetry cuando esté habilitado. Correlaciona registros y trazas en APM.
• Usa un mapeo de severidad consistente para PagerDuty. fatal alerta; error tickets; warn panel de control.
• Enlaces de runbook en descripciones de alertas, no en cada línea de registro. Mantén las cargas útiles de registro pequeñas.
• Prueba la salida de registro en CI para regresiones de redacción. Instantánea de accesorio sensible.
• Documenta los campos requeridos en LOGGING.md para nuevos servicios.

Preguntas frecuentes

Relacionado

• Conceptos básicos de registro - ejemplos introductorios
• pino - referencia de configuración
• IDs de correlación de solicitudes - propagación de encabezados
• Mejores prácticas de observabilidad - métricas y trazas

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.