Como debugar Node em produção: guia prático passo a passo

Depurar Node.js em produção não é tarefa para console.log desenfreado. O primeiro passo é entender que o ambiente produtivo exige técnica: logs estruturados, inspeção pontual e análise de memória, tudo sem derrubar o serviço. Este guia cobre o caminho do diagnóstico ao tratamento, com foco em segurança e estabilidade.

Passo 1: Comece pelos logs estruturados

Antes de qualquer ferramenta de debug, garanta que sua aplicação emita logs em formato JSON, com timestamp, nível (info, warn, error) e contexto. Use bibliotecas como pino ou winston. O erro comum aqui é logar objetos inteiros sem sanitizar: isso vaza tokens e dados pessoais para o arquivo de log.

Dica: configure níveis dinâmicos via variável de ambiente, assim você aumenta a verbosidade sem novo deploy.

Passo 2: Ative o inspector do Node apenas em casos pontuais

O Node.js traz um depurador embutido acessível via --inspect. Em produção, use --inspect-brk somente em uma instância isolada, nunca no cluster inteiro. Conecte pelo Chrome DevTools ou pelo Visual Studio Code, que é o caminho mais comum segundo a comunidade.

Erro a evitar: deixar a porta de inspeção aberta publicamente. Restrinja por firewall ou túnel SSH.

Passo 3: Capture heap snapshot e profile sob demanda

Quando o problema é memória ou lentidão, gere um heap snapshot com v8.writeHeapSnapshot() ou use o profiling via --cpu-prof. Analise o arquivo no DevTools para achar vazamentos ou funções lentas.

Ressalva concreta: snapshots pesam, então agende fora do pico e remova os arquivos depois.

Passo 4: Use breakpoints remotos com cautela

Breakpoints pausam a execução. Em produção, isso significa requests travadas. Prefira debugger statements condicionais ou a pausa apenas em uma réplica de teste que receba tráfego espelhado.

Passo 5: Tenha um plano de rollback

Nenhuma técnica substitui um deploy reversível. Se o debug não resolver rápido, reverta a versão e investigue com calma.

Checklist final: logs estruturados ativos, inspector restrito, snapshot sob demanda, breakpoints raros, rollback pronto.

Perguntas frequentes

É seguro usar --inspect em produção?

Sim, desde que a porta esteja restrita a um túnel seguro e a instância seja isolada do tráfego real. Nunca exponha publicamente.

Qual a diferença entre --inspect e --inspect-brk?

--inspect inicia o depurador sem pausar; --inspect-brk pausa na primeira linha, útil para analisar o estado inicial, mas perigoso em produção.

Como debugar vazamento de memória em Node?

Gere heap snapshots em intervalos e compare os objetos retidos. Ferramentas como o DevTools ajudam a identificar closures ou listeners não removidos.

Posso usar console.log em produção?

Pode, mas não é ideal. Logs estruturados com níveis são mais fáceis de filtrar e menos ruidosos. Console.log em loop pode impactar performance.

Preciso de uma ferramenta paga para debug?

Não. O inspector nativo do Node e o Chrome DevTools resolvem a maioria dos casos. Ferramentas como Datadog ou New Relic adicionam observabilidade, mas não são obrigatórias.