Por que o bug desaparece toda vez que você roda na sua máquina

No seu notebook existe um único usuário, memória limpa, latência de 0,2ms até o banco e nenhum job batch rodando em paralelo às 03h00. O bug intermitente de produção mora justamente nas brechas entre processos simultâneos.

Enquanto você olha para a função isolada jurando que o código é determinístico, o problema pode ser uma réplica de leitura do PostgreSQL com 400ms de atraso devolvendo "usuário não encontrado" logo após o INSERT no primário.

Protocolo de 4 passos para encurralar um Heisenbug

Troque tentativa e erro por isolamento sistemático de variáveis:

  • 1. Correlation ID ponta a ponta: gere ou propague X-Request-Id no gateway, passe por todas as filas/chamadas HTTP internas e grave no log estruturado JSON.
  • 2. Logue fronteiras e latências, não só exceções: às vezes o erro 500 é só consequência de uma dependência que respondeu em 12 segundos e estourou o timeout do cliente antes.
  • 3. Investigue os 4 suspeitos clássicos: race condition entre dois webhooks, leak de variável global/singleton em worker, réplica de leitura atrasada e cache parcialmente populado.
  • 4. Reproduza o padrão com script paralelo: dispare 20 requisições idênticas simultaneamente contra staging para forçar a colisão de estado.
{
  "timestamp": "2026-11-24T17:59:11.402Z",
  "level": "error",
  "request_id": "req_9f41a8c2",
  "worker_pid": 42,
  "db_host": "read-replica-02",
  "replication_lag_ms": 680,
  "msg": "Pedido recém-criado não encontrado na leitura subsequente"
}

Por que colocar try/catch vazio só piora a sequela

Engolir a exceção com try/catch genérico para "parar de apitar no Sentry" transforma um erro intermitente visível em corrupção silenciosa de dados que só vai aparecer na auditoria financeira três meses depois.

Sintoma Intermitente vs. Causa Raiz Mais Provável

Sintoma ObservadoSuspeito PrincipalDado para Confirmar em Log
Falha só após escrita recenteRead-after-write em réplica atrasadaComparar host primário vs. réplica e lag em ms
Erro ocorre só sob pico de tráfegoRace condition ou pool de conexões esgotadoTimestamp sobreposto no mesmo recurso + wait time do pool
Funciona 99% e quebra para 1 usuárioPayload malformado, fuso horário ou char especialHash/tamanho do payload + locale/timezone de entrada
Degrada ao longo de horas até crashMemory leak ou singleton acumulando estadoRSS de memória por uptime do pod + worker_pid

Perguntas Frequentes (FAQ)

Como investigar bug intermitente se o sistema ainda não tem OpenTelemetry?

Comece hoje com log estruturado em JSON contendo um X-Request-Id único por requisição e o tempo gasto em cada chamada externa. Só isso já corta 80% do tempo de caça.

Aumentar o timeout resolve falhas intermitentes de integração?

Raramente. Se um serviço travou, aumentar o timeout de 5s para 30s apenas mantém suas threads presas por seis vezes mais tempo, espalhando a queda para o resto da aplicação.

Por que webhooks duplicados causam erros difíceis de reproduzir?

Porque provedores externos reenviam eventos simultaneamente em caso de oscilação de rede. Sem chave de idempotência garantida por constraint única no banco, duas execuções correm ao mesmo tempo sobre o mesmo pedido.

Referências e Fontes

Sobre a Autoria

Senior Dev Esgotado (SQL //sequela)

Staff Engineer & Sobrevivente de Produção

Engenheiro sênior movido a café frio e post-mortems das 23h. Documenta falhas reais de infraestrutura, rituais corporativos inúteis e a ergonomia duvidosa de quem mantém sistemas críticos no ar.

  • 12+ anos apagando incêndios em produção às sextas-feiras
  • Especialista em Sistemas Distribuídos, Post-Mortems e Sobrevivência a Dailies