Process Reports no Node.js

Process Reports geram um arquivo de diagnóstico com informações sobre o processo Node.js, sistema operacional, versões, memória, pilhas nativas e JavaScript, handles libuv e outros dados úteis durante falhas ou travamentos. O relatório pode ser criado automaticamente após determinados eventos ou sob demanda.

Ele não substitui logs, métricas, traces ou heap snapshots. Sua principal função é capturar o estado do runtime em um momento crítico, especialmente quando o processo apresenta crash, uso anormal de recursos ou não encerra.

Gerando um relatório manual

const filename = process.report.writeReport();
console.log(`Relatório criado em ${filename}`);

O arquivo é JSON e normalmente recebe um nome com data, PID e sequência. Grave-o em diretório protegido e com espaço controlado.

Definindo o diretório

process.report.directory = '/var/log/my-app/reports';
process.report.filename = '';

Filename vazio permite que o Node.js gere nomes únicos. Um nome fixo pode sobrescrever relatórios anteriores.

Gerando em memória

const report = process.report.getReport();

console.log({
  event: report.header.event,
  pid: report.header.processId,
  commandLine: report.header.commandLine,
});

getReport() retorna um objeto JavaScript. Não serialize e envie o relatório completo para logs comuns, pois ele pode ser grande e conter informações sensíveis.

Ativando por linha de comando

node --report-on-fatalerror dist/server.js

Essa opção gera um relatório em erros fatais internos. Outras opções controlam sinais e exceções não capturadas. Verifique o contrato da versão adotada.

Relatório em exceção não capturada

node --report-uncaught-exception dist/server.js

O relatório pode ajudar a relacionar a exceção com pilhas, versões e handles ativos. O processo ainda deve encerrar; não use o evento para continuar em estado potencialmente inconsistente.

Relatório por sinal

node --report-on-signal --report-signal=SIGUSR2 dist/server.js

Em sistemas compatíveis, envie o sinal:

kill -USR2 12345

Escolha um sinal que não conflite com o supervisor, profiler ou plataforma. Em Windows e containers, o comportamento pode ser diferente.

Configuração por código

process.report.reportOnFatalError = true;
process.report.reportOnUncaughtException = true;
process.report.reportOnSignal = true;
process.report.signal = 'SIGUSR2';

Configurar por linha de comando costuma capturar eventos que ocorrem muito cedo, antes de seu código inicializar.

Estrutura do relatório

As seções podem incluir:

• header com evento, horário, PID, plataforma e versões;
• JavaScript stack;
• native stack;
• heap e espaços de memória;
• resource usage;
• libuv handles;
• variáveis de ambiente;
• limites do sistema;
• bibliotecas compartilhadas.

Campos exatos podem mudar. Crie parsers tolerantes e preserve o arquivo original.

Analisando o header

Comece por:

• evento que gerou o relatório;
• timestamp;
• versão do Node.js e V8;
• command line;
• arquitetura e sistema;
• uptime;
• working directory.

Compare com a versão implantada e o commit. Uma divergência pode explicar comportamento que não aparece em staging.

Pilha JavaScript

A pilha mostra onde a thread estava no momento da captura. Em um sinal manual, ela pode apontar apenas a própria geração do relatório. Em uma exceção, costuma ser mais relevante.

Source maps e nomes de funções melhoram a leitura. Preserve os artefatos da versão implantada.

Native stack

A pilha nativa ajuda em falhas do runtime, addons e bibliotecas C/C++. Símbolos ausentes podem limitar a análise. Em incidentes graves, combine com core dump, debugger e suporte da biblioteca.

Heap

O resumo de heap mostra memória total, usada, disponível e espaços do V8. Ele ajuda a confirmar pressão, mas não revela quais objetos estão retidos. Para isso, use heap snapshot.

Compare com RSS e memória externa. Buffers e addons podem consumir memória fora do heap JavaScript.

Resource usage

Observe CPU, page faults, contexto, memória e limites. Em containers, compare com métricas do cgroup e eventos de OOM. Um processo morto pelo kernel pode não conseguir criar relatório no momento final.

Handles libuv

A lista de handles pode indicar por que o processo não encerra:

• servidores;
• sockets;
• timers;
• pipes;
• processos filhos;
• watchers.

Nem todo handle listado é vazamento. Compare com a arquitetura e faça captura em processo saudável.

Exemplo de endpoint administrativo

app.post('/internal/diagnostics/report', requireAdmin, (req, res) => {
  const filename = process.report.writeReport();
  auditLogger.warn({ filename, actor: req.user.id }, 'Relatório gerado');
  res.status(202).json({ created: true });
});

Evite expor essa rota na internet. Use autenticação forte, rede interna, rate limit e auditoria. Não devolva o caminho completo nem o conteúdo.

Relatório em evento de memória

Você pode gerar ao ultrapassar um limite operacional:

let generated = false;

setInterval(() => {
  const { rss } = process.memoryUsage();
  if (!generated && rss > 1_500_000_000) {
    generated = true;
    process.report.writeReport();
  }
}, 10_000).unref();

Use cooldown para não encher disco. O ato de gerar relatório também consome recursos.

Relatório antes de shutdown forçado

const forceTimer = setTimeout(() => {
  process.report.writeReport();
  process.exit(1);
}, 30_000);
forceTimer.unref();

Isso ajuda quando handles impedem o shutdown. Não dependa de escrita síncrona em volume indisponível.

Containers

Grave em volume persistente ou envie o arquivo por um agente depois da criação. Se o pod for removido, o filesystem efêmero desaparece.

Garanta permissões e limite de disco. Um diretório somente leitura faz a geração falhar.

Kubernetes

Uma estratégia:

1. gerar relatório em volume emptyDir ou persistente;
2. sidecar ou agente coleta o arquivo;
3. associar pod, namespace, versão e timestamp;
4. restringir acesso;
5. aplicar retenção.

Se usar emptyDir, colete antes de o pod desaparecer.

Dados sensíveis

O relatório pode conter command line, variáveis de ambiente, caminhos, IPs e detalhes internos. Não publique nem anexe em issue pública sem revisão. Remova segredos e aplique criptografia em trânsito e repouso.

Retenção

Defina quantidade e idade máxima. Uma captura automática em crash loop pode gerar muitos arquivos. O supervisor deve limitar reinícios e o coletor deve deduplicar.

Correlação

Use o nome do arquivo e metadados para correlacionar com:

• deploy e commit;
• logs do mesmo PID;
• traces próximos ao horário;
• métricas de CPU e memória;
• eventos do orquestrador;
• OOM e sinais;
• perfil de CPU ou heap.

Automação de coleta

Um agente pode observar a pasta e enviar novos arquivos para armazenamento privado. Faça upload atômico: escreva, feche e então renomeie ou marque o arquivo para evitar coleta parcial.

Teste da configuração

Não espere um incidente para descobrir que o diretório não existe. Em staging:

1. gere manualmente;
2. confirme permissões;
3. valide coleta;
4. teste sinal;
5. simule exceção;
6. confirme retenção;
7. revise dados sensíveis.

Diferença para heap snapshot

Process Report é um panorama amplo e relativamente legível. Heap snapshot é detalhado, maior e focado em objetos e retenção. Em vazamento, gere relatório para contexto e snapshot para análise de objetos.

Diferença para core dump

Core dump captura memória do processo em nível do sistema e permite depuração profunda, mas é maior e mais sensível. Process Report é mais fácil de coletar e suficiente para muitos casos.

Erros comuns

• salvar em diretório efêmero sem coleta;
• usar nome fixo;
• gerar repetidamente em loop;
• expor endpoint público;
• enviar relatório completo para logs;
• ignorar variáveis sensíveis;
• tratar o resumo de heap como heap snapshot;
• não testar sinais no container;
• não correlacionar com versão.

Fluxo recomendado

Ative relatórios para eventos críticos, defina diretório seguro, teste a coleta, limite retenção e correlacione com observabilidade. Combine com Heap Snapshots no Node.js, CPU Profiling, Clinic.js e métricas de perf_hooks.

Consulte a documentação oficial de Process Reports e a referência das opções de relatório na CLI.