O playbook de memory leaks do Node.js — heap snapshots, clinic.js e os quatro padrões que continuamos encontrando

Memory leaks de Node.js tendem a parecer aterrorizantes e normalmente não são. Os mesmos quatro padrões aparecem em auditoria após auditoria: um Map/Set que cresce sem limite, uma closure que segura um escopo pai inesperadamente grande, event listeners adicionados mas nunca removidos, e um cache em processo sem política de eviction.

Este é o playbook de diagnóstico que rodamos em serviços Node de cliente que começam a consumir memória semana após semana.

Heap snapshots — o único diagnóstico que não é adivinhação

import v8 from 'node:v8';
import fs from 'node:fs';
 
process.on('SIGUSR2', () => {
  const file = `/tmp/heap-${Date.now()}.heapsnapshot`;
  v8.writeHeapSnapshot(file);
  console.log('wrote', file);
});

Envie SIGUSR2 para o processo, pegue um snapshot, repita após 30 minutos de tráfego, diff os dois na aba Memory do Chrome DevTools. A coluna retained-objects te diz exatamente o que está crescendo.

O artigo completo cobre:

• Os quatro padrões e como cada um aparece no diff do heap snapshot
• clinic.js doctor e clinic flame para CPU + memória juntos
• --inspect e Chrome DevTools para profiling ao vivo fora de produção
• Rodar a detecção de leaks contra seus próprios serviços no CI antes da produção
• A leitura cgroups + OOMKiller quando o leak foi para produção mesmo assim
• Quando o «leak» é na verdade a young generation do V8 não coletando rápido o suficiente (não é leak)

Fale conosco se seu serviço Node tem crescido silenciosamente e ninguém sabe por quê.