Resposta ao OOM Killer

Q: Qual código de saída significa OOMKilled?

137 (128 + 9 SIGKILL). Eventos do Kubernetes mostram OOMKilled como a razão.

Q: Como tirar um snapshot do heap em produção?

Use kill -USR2 se estiver conectado a heapdump, ou faça exec em um pod drenado. Nunca tire snapshot do único réplica sob tráfego total.

Quando o Kubernetes marca seu pod Node.js como OOMKilled, você tem minutos para decidir: vazamento, pico de tráfego ou limites mal configurados. Esta página faz a triagem de heap vs RSS e seleciona a mitigação correta.

Receita

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

# 1. Confirme OOMKilled (não CrashLoop por outros motivos)
kubectl describe pod <pod> -n production | grep -E "OOMKilled|Reason|Exit Code"
 
# 2. Verifique métricas de memória: heap vs RSS
# Grafana: process_resident_memory_bytes vs v8 heap used
 
# 3. Correlacione com deploy e tráfego
kubectl rollout history deployment/<svc>
# Compare RPS spike com a inclinação da memória
 
# 4. Mitigue
kubectl scale deployment/<svc> --replicas=<N+2>   # pico de tráfego
kubectl rollout undo deployment/<svc>               # deploy ruim
# vazamento: limite o tráfego, reinicialização em rolling, agende snapshot do heap

Quando usar isto:

Pods reiniciam com OOMKilled e Exit Code 137
O gráfico de memória sobe constantemente sob tráfego estável (suspeita de vazamento)
A memória tem picos com RPS, mas se recupera após o scale-out (suspeita de capacidade)
RSS cresce enquanto heapUsed permanece estável (buffers nativos, gRPC, sharp)

Exemplo de Trabalho

// src/observability/memory-metrics.ts
import { monitorEventLoopDelay } from "node:perf_hooks";
import v8 from "node:v8";
 
const loopDelay = monitorEventLoopDelay({ resolution: 20 });
loopDelay.enable();
 
export function startMemoryReporter(log: (obj: object) => void, intervalMs = 30_000) {
  setInterval(() => {
    const mem = process.memoryUsage();
    const heapStats = v8.getHeapStatistics();
    log({
      msg: "memory_sample",
      rssMb: Math.round(mem.rss / 1024 / 1024),
      heapUsedMb: Math.round(mem.heapUsed / 1024 / 1024),
      heapTotalMb: Math.round(mem.heapTotal / 1024 / 1024),
      externalMb: Math.round(mem.external / 1024 / 1024),
      arrayBuffersMb: Math.round(mem.arrayBuffers / 1024 / 1024),
      heapLimitMb: Math.round(heapStats.heap_size_limit / 1024 / 1024),
      eventLoopP99Ms: Math.round(loopDelay.percentile(99) / 1e6),
    });
    loopDelay.reset();
  }, intervalMs).unref();
}

O que isso demonstra:

A divergência de rss vs heapUsed sinaliza crescimento nativo/buffer
external e arrayBuffers rastreiam a pressão de Buffer e TypedArray
O p99 do loop de eventos junto com a memória captura espirais de pausa do GC

Mergulho Profundo

Heap vs RSS

Métrica	O que mede	Cresce quando
`heapUsed`	Objetos JavaScript do V8	Closures vazadas, Maps crescendo, objetos cacheados
`rss`	Memória residente total do processo	Heap + add-ons nativos + pilhas de thread + mmap
`external`	Objetos C++ vinculados ao JS	Buffers, criptografia nativa, alguns drivers ORM
`arrayBuffers`	Memória ArrayBuffer desanexada	Cargas úteis binárias, uploads de arquivos

Vazamento vs Pico de Tráfego

Sinal	Provável vazamento	Provável tráfego/capacidade
Tráfego	RPS estável	RPS aumenta 2-10x
Inclinação da memória	Linear ao longo de horas	Mudança abrupta no pico
Reinícios	Mesmo pod, mesmo padrão	Todos os pods, carga proporcional
`heapUsed`	Acompanha o aumento do RSS	Pode permanecer moderado
Correção	Correção de código + snapshot	Escalar HPA, ajustar pool, aumentar limites

Árvore de Decisão de Triagem

OOMKilled?
  ├─ Deploy nos últimos 60 min? → fazer rollback primeiro
  ├─ Pico de RPS? → escalar réplicas, verificar tamanhos de pool
  ├─ heapUsed ≈ RSS crescendo? → caça a vazamentos (snapshot, clinic heapprofiler)
  ├─ RSS >> heapUsed? → verificar Buffers, sharp, gRPC, engine Prisma
  └─ Limites muito apertados? → aumentar request/limit de memória com evidências

Limites do Kubernetes

resources:
  requests:
    memory: "512Mi"
  limits:
    memory: "768Mi"   # margem acima do RSS em estado estável

Defina NODE_OPTIONS=--max-old-space-size=512 abaixo do limite do k8s (deixe ~30% para não-heap)
OOMKilled em 768Mi com 700Mi de RSS significa limite, não necessariamente vazamento
Use recomendações do VPA apenas após observar o estado estável sob carga

Armadilhas

Snapshot sob carga - heapdump paralisa o event loop. Correção: Copie o pod, drene o tráfego, tire o snapshot no clone.
Ignorar external - Detectores de vazamento monitoram apenas o heap. Correção: Registre arrayBuffers e external a cada 30s.
Reiniciar sem evidências - Mascara a taxa de vazamento. Correção: O scribe registra o URL do gráfico de memória antes de reiniciar.
Mesmo limite para API e worker - Workers lidam com payloads de job maiores. Correção: Separe Deployments e limites.
Caches globais sem TTL - Map com chave userId cresce para sempre. Correção: LRU com entradas máximas ou Redis.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
`clinic heapprofiler`	Vazamento reproduzível em staging	Produção sob carga do cliente
`clinic doctor`	Event-loop + memória combinados	Você já sabe que é OOM
Aumentar limites apenas	Pico de capacidade comprovado	RSS sobe sob tráfego estável
Mudar para worker threads	Loop bloqueante intensivo em CPU	API intensiva em I/O (não corrigirá vazamento)

FAQs

Qual código de saída significa OOMKilled?

137 (128 + 9 SIGKILL). Eventos do Kubernetes mostram OOMKilled como a razão.

Como tirar um snapshot do heap em produção?

Use kill -USR2 <pid> se estiver conectado a heapdump, ou faça exec em um pod drenado. Nunca tire snapshot do único réplica sob tráfego total.

Vazamentos de pool de conexão podem causar OOM?

Eles causam exaustão e timeouts antes do OOM, mas o crescimento do pool ocioso aumenta o RSS. Verifique pg pool totalCount vs max.

Devo desabilitar o GC com --expose-gc?

Apenas em diagnósticos controlados. Forçar o GC oculta sinais de vazamento nas métricas.

Relacionados

Noções Básicas de Incidentes - checklist dos primeiros 15 minutos
Ajuste de Memória e GC - ajuste proativo
Suite Clinic.js - profiling de vazamentos
Ajuste de Pool de Conexão - dimensionamento de pool
HPA e Limites de Recursos - limites do k8s

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.

Receita

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

# 1. Confirme OOMKilled (não CrashLoop por outros motivos)
kubectl describe pod <pod> -n production | grep -E "OOMKilled|Reason|Exit Code"
 
# 2. Verifique métricas de memória: heap vs RSS
# Grafana: process_resident_memory_bytes vs v8 heap used
 
# 3. Correlacione com deploy e tráfego
kubectl rollout history deployment/<svc>
# Compare RPS spike com a inclinação da memória
 
# 4. Mitigue
kubectl scale deployment/<svc> --replicas=<N+2>   # pico de tráfego
kubectl rollout undo deployment/<svc>               # deploy ruim
# vazamento: limite o tráfego, reinicialização em rolling, agende snapshot do heap

Quando usar isto:

Pods reiniciam com OOMKilled e Exit Code 137
O gráfico de memória sobe constantemente sob tráfego estável (suspeita de vazamento)
A memória tem picos com RPS, mas se recupera após o scale-out (suspeita de capacidade)
RSS cresce enquanto heapUsed permanece estável (buffers nativos, gRPC, sharp)

Exemplo de Trabalho

// src/observability/memory-metrics.ts
import { monitorEventLoopDelay } from "node:perf_hooks";
import v8 from "node:v8";
 
const loopDelay = monitorEventLoopDelay({ resolution: 20 });
loopDelay.enable();
 
export function startMemoryReporter(log: (obj: object) => void, intervalMs = 30_000) {
  setInterval(() => {
    const mem = process.memoryUsage();
    const heapStats = v8.getHeapStatistics();
    log({
      msg: "memory_sample",
      rssMb: Math.round(mem.rss / 1024 / 1024),
      heapUsedMb: Math.round(mem.heapUsed / 1024 / 1024),
      heapTotalMb: Math.round(mem.heapTotal / 1024 / 1024),
      externalMb: Math.round(mem.external / 1024 / 1024),
      arrayBuffersMb: Math.round(mem.arrayBuffers / 1024 / 1024),
      heapLimitMb: Math.round(heapStats.heap_size_limit / 1024 / 1024),
      eventLoopP99Ms: Math.round(loopDelay.percentile(99) / 1e6),
    });
    loopDelay.reset();
  }, intervalMs).unref();
}

O que isso demonstra:

A divergência de rss vs heapUsed sinaliza crescimento nativo/buffer
external e arrayBuffers rastreiam a pressão de Buffer e TypedArray
O p99 do loop de eventos junto com a memória captura espirais de pausa do GC

Mergulho Profundo

Heap vs RSS

Métrica	O que mede	Cresce quando
`heapUsed`	Objetos JavaScript do V8	Closures vazadas, Maps crescendo, objetos cacheados
`rss`	Memória residente total do processo	Heap + add-ons nativos + pilhas de thread + mmap
`external`	Objetos C++ vinculados ao JS	Buffers, criptografia nativa, alguns drivers ORM
`arrayBuffers`	Memória ArrayBuffer desanexada	Cargas úteis binárias, uploads de arquivos

Vazamento vs Pico de Tráfego

Sinal	Provável vazamento	Provável tráfego/capacidade
Tráfego	RPS estável	RPS aumenta 2-10x
Inclinação da memória	Linear ao longo de horas	Mudança abrupta no pico
Reinícios	Mesmo pod, mesmo padrão	Todos os pods, carga proporcional
`heapUsed`	Acompanha o aumento do RSS	Pode permanecer moderado
Correção	Correção de código + snapshot	Escalar HPA, ajustar pool, aumentar limites

Árvore de Decisão de Triagem

OOMKilled?
  ├─ Deploy nos últimos 60 min? → fazer rollback primeiro
  ├─ Pico de RPS? → escalar réplicas, verificar tamanhos de pool
  ├─ heapUsed ≈ RSS crescendo? → caça a vazamentos (snapshot, clinic heapprofiler)
  ├─ RSS >> heapUsed? → verificar Buffers, sharp, gRPC, engine Prisma
  └─ Limites muito apertados? → aumentar request/limit de memória com evidências

Limites do Kubernetes

resources:
  requests:
    memory: "512Mi"
  limits:
    memory: "768Mi"   # margem acima do RSS em estado estável

Defina NODE_OPTIONS=--max-old-space-size=512 abaixo do limite do k8s (deixe ~30% para não-heap)
OOMKilled em 768Mi com 700Mi de RSS significa limite, não necessariamente vazamento
Use recomendações do VPA apenas após observar o estado estável sob carga

Armadilhas

Snapshot sob carga - heapdump paralisa o event loop. Correção: Copie o pod, drene o tráfego, tire o snapshot no clone.
Ignorar external - Detectores de vazamento monitoram apenas o heap. Correção: Registre arrayBuffers e external a cada 30s.
Reiniciar sem evidências - Mascara a taxa de vazamento. Correção: O scribe registra o URL do gráfico de memória antes de reiniciar.
Mesmo limite para API e worker - Workers lidam com payloads de job maiores. Correção: Separe Deployments e limites.
Caches globais sem TTL - Map com chave userId cresce para sempre. Correção: LRU com entradas máximas ou Redis.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
`clinic heapprofiler`	Vazamento reproduzível em staging	Produção sob carga do cliente
`clinic doctor`	Event-loop + memória combinados	Você já sabe que é OOM
Aumentar limites apenas	Pico de capacidade comprovado	RSS sobe sob tráfego estável
Mudar para worker threads	Loop bloqueante intensivo em CPU	API intensiva em I/O (não corrigirá vazamento)

FAQs

Qual código de saída significa OOMKilled?

137 (128 + 9 SIGKILL). Eventos do Kubernetes mostram OOMKilled como a razão.

Como tirar um snapshot do heap em produção?

Use kill -USR2 <pid> se estiver conectado a heapdump, ou faça exec em um pod drenado. Nunca tire snapshot do único réplica sob tráfego total.

Vazamentos de pool de conexão podem causar OOM?

Eles causam exaustão e timeouts antes do OOM, mas o crescimento do pool ocioso aumenta o RSS. Verifique pg pool totalCount vs max.

Devo desabilitar o GC com --expose-gc?

Apenas em diagnósticos controlados. Forçar o GC oculta sinais de vazamento nas métricas.

Relacionados

Noções Básicas de Incidentes - checklist dos primeiros 15 minutos
Ajuste de Memória e GC - ajuste proativo
Suite Clinic.js - profiling de vazamentos
Ajuste de Pool de Conexão - dimensionamento de pool
HPA e Limites de Recursos - limites do k8s

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.

Resposta ao OOM Killer

Buscar na documentação

Resposta ao OOM Killer