Caza de Fugas de Memoria

Las API de Node.js que nunca liberan memoria eventualmente terminan con pods OOM-killed. Caza fugas con instantáneas de heap en Chrome DevTools, clinic heapprofiler bajo carga y revisión de código de listeners, cachés y cierres.

Receta

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

# Empieza con inspect para instantáneas
node --inspect src/main.ts
 
# O el perfilador de heap de Clinic
npm install -g clinic
clinic heapprofiler -- node dist/main.js
# ejercita la API, detén el proceso, abre el HTML generado

# Señal para instantánea de heap a disco (Node 24)
kill -USR2 <pid>   # si --heapsnapshot-near-heap-limit está configurado
node --heapsnapshot-signal=SIGUSR2 dist/main.js

Cuándo usarlo:

• RSS crece linealmente durante días mientras el tráfico es plano
• k8s reinicia pods con OOMKilled
• Los tiempos de pausa del GC aumentan en las métricas
• Después de añadir caché en memoria, bus de eventos o fanout de websocket

Ejemplo de trabajo

// FUGA: caché ilimitada indexada por solicitud - antipatrón para demostración
const leakCache = new Map<string, Buffer>();
 
import express from "express";
const app = express();
 
app.post("/upload", express.raw({ type: "*/*", limit: "5mb" }), (req, res) => {
  const id = crypto.randomUUID();
  leakCache.set(id, Buffer.from(req.body)); // nunca se desaloja
  res.json({ id });
});
 
// SOLUCIÓN: LRU con entradas máximas + TTL
import { LRUCache } from "lru-cache";
 
const cache = new LRUCache<string, Buffer>({
  max: 500,
  ttl: 1000 * 60 * 15,
});
 
app.post("/upload-fixed", express.raw({ type: "*/*", limit: "5mb" }), (req, res) => {
  const id = crypto.randomUUID();
  cache.set(id, Buffer.from(req.body));
  res.json({ id });
});
 
// DEBUG: registra el heap periódicamente en staging
setInterval(() => {
  const m = process.memoryUsage();
  console.log(JSON.stringify({ rss: m.rss, heapUsed: m.heapUsed, external: m.external }));
}, 60_000).unref();

Flujo de trabajo de instantáneas de heap:

1. node --inspect dist/main.js
2. Chrome DevTools -> Memoria -> Tomar instantánea de heap (línea base)
3. Ejecuta la prueba de carga durante 5-10 minutos
4. Toma una segunda instantánea
5. Vista de comparación -> ordena por "Diferencia de tamaño" -> inspecciona las rutas de retención

Lo que esto demuestra:

• Map ilimitado es una fuga clásica en las API de Node
• LRU + TTL limita la memoria para los búferes de carga
• El registro periódico de memoryUsage ayuda a correlacionar el crecimiento con las implementaciones
• La comparación de DevTools encuentra objetos que crecieron entre instantáneas

Inmersión Profunda

Cómo Funciona

• V8 asigna en el heap; RSS incluye heap + búferes nativos (BoringSSL, zlib)
• La ruta de retención muestra qué referencia mantiene un objeto vivo
• DOM desvinculado es un problema del navegador; en Node busca Timers, listeners de EventEmitter, cierres sobre búferes grandes
• Las fugas nativas (addons de C++) muestran un aumento de external en memoryUsage

Sitios Comunes de Fugas en las API de Node

clinic heapprofiler

clinic heapprofiler --on-port 'autocannon -d 60 localhost:3000' -- node dist/main.js

• Ejecuta carga mientras registra asignaciones
• Vista estilo flamegraph de las pilas de asignación "calientes"
• Mejor cuando la fuga aparece solo bajo tráfico

Notas de TypeScript

// WeakMap para metadatos vinculados a la vida útil del objeto - las entradas se recolectan cuando la clave se recolecta
const meta = new WeakMap<object, { createdAt: number }>();

Errores Comunes

• Conclusión de una sola instantánea - El heap parece "grande" normalmente. Solución: Compara dos instantáneas después de la carga.
• Depuración en producción con --inspect abierto - Riesgo de seguridad. Solución: Instantánea en staging o usa el volcado de heap SIGUSR2 a S3 en un manual de procedimientos controlado.
• Culpar a V8 por la caché de la aplicación - Las "fugas de Node" suelen ser Map de la aplicación. Solución: Audita las cachés después de cada característica.
• No llamar a unref() en los temporizadores de depuración - El temporizador mantiene el bucle de eventos vivo en las pruebas. Solución: .unref() en los intervalos de diagnóstico.
• Instantáneas enormes congelan el portátil - Las instantáneas de heap de 2 GB son lentas. Solución: Reproduce con una carga menor en staging primero.

Alternativas

Preguntas Frecuentes

Relacionado

• Conceptos básicos de depuración - Configuración de --inspect
• Incidente de bloqueo del bucle de eventos - CPU vs memoria
• Agotamiento del pool de conexiones - pool no liberado
• Respuesta del OOM Killer - incidente de producción
• Apagado elegante - liberar recursos

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.