Melhores Práticas de Depuração

Reproduza com volume de dados semelhante ao de produção localmente antes de ajustar a produção. Estas práticas reduzem o tempo médio de resolução de incidentes do Node.js.

Como Usar Esta Lista

• O runbook de plantão se conecta a páginas de cenários relevantes
• O ambiente de staging espelha a versão do Node.js de produção (24.18.0) e os limites de tamanho do corpo
• Cada postmortem adiciona uma proteção automatizada (teste, alerta ou lint)
• Use em conjunto com Iniciadores de Runbook de Plantão

A - Reprodução

• Combine a versão major.minor do Node.js com a de produção em staging (24.18.0 LTS).
• Repita o tráfego com tamanhos de payload semelhantes - webhooks de 3MB, não fixtures de 30 bytes.
• Use autocannon ou k6 para estressar endpoints de saúde enquanto testa rotas pesadas.
• Capture a reprodução mínima em um teste de integração antes de corrigir flags exclusivas de produção.
• Documente os passos de reprodução no ticket - outro engenheiro pode verificar sem contexto do Slack.

B - Instrumentação

• Logs JSON estruturados com requestId, traceId, rota, duração.
• monitorEventLoopDelay na prontidão ou exportador de métricas.
• Exporte total, idle, waiting do pool pg em /health/db.
• Traces do OpenTelemetry em spans de HTTP e DB de saída.
• Evite console.log de objetos enormes - paralisa o event loop e vaza PII.

C - Ferramentas de Depuração Local

• node --inspect + Chrome DevTools para breakpoints e snapshots de heap.
• clinic doctor / clinic heapprofiler antes de culpar o hardware.
• Source maps habilitados para números de linha do TypeScript em stacks.
• Remova declarações debugger antes do merge - imposto pelo ESLint.
• NODE_OPTIONS='--unhandled-rejections=strict' nos testes de CI.

D - Segurança de Produção

• Não deixe --inspect=0.0.0.0 em produção sem um túnel de autenticação.
• Anexe SIGUSR1 apenas via runbook aprovado em réplicas de staging.
• Crashe em rejeição não tratada após log + drain para APIs stateful.
• Snapshots de heap para S3 via job agendado, não anexo manual em produção, quando necessário.
• Redija segredos em logs de erro - sem DATABASE_URL em traces enviados a clientes.

E - Classes Comuns de Incidentes

• Exaustão do pool: verifique release() em finally; dimensione pools por cálculo de pod.
• Paralisação do event-loop: mova JSON/crypto síncronos para workers ou filas.
• Vazamento de memória: compare snapshots de heap após carga, audite caches globais.
• Requisições travadas: timeout em todo I/O externo; registre a contagem de espera do pool.
• Duplicatas de webhook: aguarde o processamento; chaves de idempotência em efeitos colaterais.

F - Pós-Incidente

• Postmortem culpa sistemas, não indivíduos - adicione a proteção listada acima.
• Alerta sobre o sintoma (pool em espera, p99 do event-loop) não apenas sobre crash.
• Teste de carga da nova configuração de deploy (contagem de réplicas × max do pool) antes do pico.
• Atualize a documentação de cenários quando um novo modo de falha aparecer duas vezes.
• Compartilhe o trace + consulta de log no runbook para esta assinatura de falha.

FAQs

Relacionados

• Noções Básicas de Depuração - inspeção e depurador
• Caça a Vazamento de Memória - fluxo de heap
• Exaustão do Pool de Conexões - história de guerra de pool
• Falha de Produção por Rejeição Não Tratada - política de crash
• Melhores Práticas de Logging - logs estruturados

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.