Caça a Vazamentos de Memória

APIs do Node.js que nunca liberam memória eventualmente causam OOM-kill em pods. Caçe vazamentos com snapshots de heap no Chrome DevTools, clinic heapprofiler sob carga e revisão de código de listeners, caches e closures.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

# Start with inspect for snapshots
node --inspect src/main.ts
 
# Or Clinic heap profiler
npm install -g clinic
clinic heapprofiler -- node dist/main.js
# exercise API, stop process, open generated HTML

# Signal heap snapshot to disk (Node 24)
kill -USR2 <pid>   # if --heapsnapshot-near-heap-limit configured
node --heapsnapshot-signal=SIGUSR2 dist/main.js

Quando usar isso:

• RSS cresce linearmente ao longo de dias enquanto o tráfego está estável
• k8s reinicia pods com OOMKilled
• Tempos de pausa do GC aumentam nas métricas
• Após adicionar cache em memória, barramento de eventos ou fanout de websocket

Exemplo de Trabalho

// LEAK: unbounded cache keyed by request - anti-pattern for demo
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)); // never evicted
  res.json({ id });
});
 
// FIX: LRU with max entries + 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: log heap periodically in staging
setInterval(() => {
  const m = process.memoryUsage();
  console.log(JSON.stringify({ rss: m.rss, heapUsed: m.heapUsed, external: m.external }));
}, 60_000).unref();

Fluxo de trabalho de snapshot de heap:

1. node --inspect dist/main.js
2. Chrome DevTools -> Memory -> Take heap snapshot (baseline)
3. Run load test 5-10 minutes
4. Take second snapshot
5. Comparison view -> sort by "Size Delta" -> inspect retaining paths

O que isso demonstra:

• Map ilimitado é um vazamento clássico em APIs Node
• LRU + TTL limita a memória para buffers de upload
• Logging periódico de memoryUsage ajuda a correlacionar o crescimento com deploys
• Comparação do DevTools encontra objetos que cresceram entre snapshots

Mergulho Profundo

Como Funciona

• V8 aloca no heap; RSS inclui heap + buffers nativos (BoringSSL, zlib)
• Caminho de retenção mostra qual referência mantém um objeto vivo
• DOM Desanexado é um problema do navegador; no Node, procure por Timers, listeners de EventEmitter, closures sobre buffers grandes
• Vazamentos Nativos (add-ons C++) mostram external crescente em memoryUsage

Locais Comuns de Vazamento em APIs Node

clinic heapprofiler

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

• Executa carga enquanto grava alocações
• Visão em estilo de gráfico de chama (flamegraph) de pilhas de alocação quentes
• Melhor quando o vazamento aparece apenas sob tráfego

Notas de TypeScript

// WeakMap for metadata tied to object lifetime - entries GC when key is GC'd
const meta = new WeakMap<object, { createdAt: number }>();

Armadilhas

• Conclusão de snapshot única - O heap parece "grande" normalmente. Correção: Compare duas snapshots após a carga.
• Depuração em produção com --inspect aberto - Risco de segurança. Correção: Tire snapshot em staging ou use SIGUSR2 para dump de heap para S3 em um runbook controlado.
• Culpar V8 pelo cache da aplicação - "Vazamentos do Node" geralmente são Map da aplicação. Correção: Audite caches após cada recurso.
• Não chamar unref() em timers de depuração - Timer mantém o event loop vivo em testes. Correção: .unref() em intervalos de diagnóstico.
• Snapshots enormes travam o laptop - Snapshots de heap de 2GB são lentas. Correção: Reproduza com carga menor em staging primeiro.

Alternativas

FAQs

Relacionados

• Noções Básicas de Depuração - Configuração do --inspect
• Incidente de Travamento do Event-Loop - CPU vs memória
• Esgotamento do Pool de Conexões - pool não liberado
• Resposta ao OOM Killer - incidente de produção
• Desligamento Gracioso - liberação de recursos

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.