Mejores Prácticas de Depuración

Reproduce con un volumen de datos similar al de producción localmente antes de ajustar la producción. Estas prácticas acortan el tiempo medio de resolución de incidentes de Node.js.

Cómo Usar Esta Lista

• El manual de guardia enlaza a las páginas de escenarios relevantes
• Staging refleja la versión de Node de producción (24.18.0) y los límites de tamaño de cuerpo
• Cada postmortem añade una protección automatizada (prueba, alerta o lint)
• Combínalo con Iniciadores de Manual de Guardia

A - Reproducción

• Coincide la versión mayor.menor de Node con la de producción en staging (24.18.0 LTS).
• Reproduce el tráfico con tamaños de payload similares - webhooks de 3MB, no fixtures de 30 bytes.
• Usa autocannon o k6 para estresar los endpoints de salud mientras pruebas rutas pesadas.
• Captura la reproducción mínima en una prueba de integración antes de corregir banderas solo de producción.
• Documenta los pasos de reproducción en el ticket - otro ingeniero puede verificar sin contexto de Slack.

B - Instrumentación

• Logs JSON estructurados con requestId, traceId, ruta, duración.
• monitorEventLoopDelay en la preparación o exportador de métricas.
• Exporta total, idle, waiting del pool de pg en /health/db.
• Trazas de OpenTelemetry en HTTP saliente y spans de DB.
• Evita console.log de objetos enormes - detiene el bucle de eventos y filtra PII.

C - Herramientas de Depuración Local

• node --inspect + Chrome DevTools para puntos de interrupción y snapshots de heap.
• clinic doctor / clinic heapprofiler antes de culpar al hardware.
• Mapas de origen habilitados para números de línea de TypeScript en stacks.
• Elimina las sentencias debugger antes de la fusión - aplicado por ESLint.
• NODE_OPTIONS='--unhandled-rejections=strict' en pruebas de CI.

D - Seguridad en Producción

• No dejes --inspect=0.0.0.0 en producción sin un túnel de autenticación.
• Adjunta SIGUSR1 solo a través de un manual de ejecución aprobado en réplicas de staging.
• Crashea en rechazo no manejado después de log + drenaje para APIs con estado.
• Snapshots de heap a S3 a través de un trabajo programado, no adjunto manual en producción, cuando sea necesario.
• Redacta secretos en los logs de error - no DATABASE_URL en las trazas de pila enviadas a los clientes.

E - Clases Comunes de Incidentes

• Agotamiento del pool: verifica release() en finally; dimensiona los pools por pod.
• Bloqueo del bucle de eventos: mueve JSON/cripto síncrono a workers o colas.
• Fuga de memoria: compara snapshots de heap después de la carga, audita cachés globales.
• Solicitudes colgadas: establece un tiempo de espera para todas las E/S externas; registra el recuento de espera del pool.
• Duplicados de webhook: espera el procesamiento; claves de idempotencia en efectos secundarios.

F - Post-Incidente

• El postmortem culpa a los sistemas, no a los individuos - añade la protección mencionada anteriormente.
• Alerta sobre el síntoma (pool en espera, p99 del bucle de eventos) no solo sobre el crash.
• Prueba de carga la nueva configuración de despliegue (recuento de réplicas × pool max) antes del pico.
• Actualiza la documentación del escenario cuando un nuevo modo de fallo aparece dos veces.
• Comparte la traza + la consulta de log en el manual de ejecución para esta firma de fallo.

Preguntas Frecuentes

Relacionado

• Conceptos Básicos de Depuración - inspeccionar y depurador
• Búsqueda de Fugas de Memoria - flujo de trabajo de heap
• Agotamiento del Pool de Conexiones - historia de guerra del pool
• Interrupción de Producción por Rechazo No Manejado - política de crash
• Mejores Prácticas de Logging - logs estructurados

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.