Depuração
O erro caro é corrigir a primeira causa provável. Gaste os primeiros minutos estreitando, não remendando.
Método
- Capture a falha exata. Texto completo do erro, stack trace, código de saída, carimbos de data/hora, IDs de solicitação, o comando que foi executado. Coloque em um bloco de código. Erros parafraseados perdem o único token que importa.
- Reproduza-a. Encontre a menor e mais rápida maneira de acioná-la sob demanda. Se não conseguir reproduzir, diga e trabalhe a partir de logs; não adivinhe silenciosamente.
- Estabeleça o que mudou.
git log --since, deploys recentes, atualizações de dependências, mudanças de configuração ou IAM, atualizações de provedor, certificado expirando. A maioria dos incidentes é uma mudança. - Formule duas ou três hipóteses e classifique-as por probabilidade e por quão baratas são para verificar. Escreva-as antes de testar.
- Teste uma hipótese por vez com uma alteração que só importaria se essa hipótese for verdadeira. Reverta o que não ajudou; não acumule edições especulativas.
- Corrija a causa. Em seguida, escreva um teste de regressão que falhe sem a correção (veja a habilidade
tdd). - Verifique da mesma forma que reproduziu e execute o conjunto mais amplo.
Onde procurar, por sintoma
| Sintoma | Primeiras verificações |
|---|---|
| Funciona localmente, falha no CI | variáveis de ambiente, segredos, SO/arquitetura, versão do node/python, dependências em cache, fuso horário, diretório de trabalho |
| Intermitente / Flaky | estado compartilhado entre testes, tempo, ordenação, rede, novas tentativas escondendo falhas reais |
| AWS AccessDenied | qual principal (aws sts get-caller-identity), política de recurso vs política de identidade, SCPs, limite de permissão, política de chave KMS, região |
| Lambda timeout / cold start | anexo VPC, DNS, inicialização fora do handler, tamanho da memória, latência a jusante no X-Ray |
| Erro do Terraform | versão do provedor, deriva de estado (terraform plan -refresh-only), resquícios de -target, arquivo de bloqueio |
| Pod do Kubernetes não pronto | kubectl describe pod, eventos, sondas, limites de recursos, pull de imagem, montagens de segredo/configmap |
| 5xx após deploy | comparar imagem/commit anterior, caminho da verificação de saúde, diferenças de ambiente/config, ordem de migração do DB |
Regras
- Leia os logs antes de ler o código. Logs informam onde; código informa por quê.
- Adicione logging temporário se necessário e remova-o antes de confirmar.
- Nunca 'corrija' ampliando permissões, desabilitando verificação TLS, capturando e engolindo exceções ou adicionando novas tentativas sem entender o que está sendo repetido.
- Quando corrigir, escreva em um parágrafo: causa, por que não foi detectado, o que impede a próxima vez. Esse parágrafo vai no PR ou no corpo do commit.