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 Observado | Suspeito Principal | Dado para Confirmar em Log |
|---|---|---|
| Falha só após escrita recente | Read-after-write em réplica atrasada | Comparar host primário vs. réplica e lag em ms |
| Erro ocorre só sob pico de tráfego | Race condition ou pool de conexões esgotado | Timestamp sobreposto no mesmo recurso + wait time do pool |
| Funciona 99% e quebra para 1 usuário | Payload malformado, fuso horário ou char especial | Hash/tamanho do payload + locale/timezone de entrada |
| Degrada ao longo de horas até crash | Memory leak ou singleton acumulando estado | RSS de memória por uptime do pod + worker_pid |
Leia também
- Glossário Dev: Drift de Homologação (Environment Drift)
Entenda por que diferenças ocultas entre staging e produção escondem esses erros.
- Modelo prático de Post-Mortem sem caça às bruxas
Documente a causa raiz quando finalmente pegar o Heisenbug para ele não voltar no próximo trimestre.
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
- Google SRE Book — Effective Troubleshooting & Monitoring Distributed Systems — Google Site Reliability Engineering