Separar sintoma de impacto
Um enunciado curto: "Em tal horario, tal fluxo apresentou tal sintoma com tal impacto".
Causa raiz
Corrigir sem entender a causa pode apenas adiar o mesmo problema.
Use este roteiro para transformar evidencias em hipoteses, confirmar causa raiz e sair do incidente com uma prevencao pequena, verificavel e com dono.
Metodo simples
O objetivo nao e encontrar culpado. E impedir que a falha volte igual.
Uma boa analise separa sintoma, impacto, linha do tempo, hipoteses, causa confirmada, correcao e prevencao. Isso ajuda a equipe a agir melhor no proximo incidente.
Montar uma linha do tempo
Uma sequencia com horario, evento, evidencia, efeito percebido e decisao tomada.
Formular hipoteses pequenas
Uma lista de 2 a 4 hipoteses com evidencia esperada e teste de verificacao.
Roteiro de analise
Da evidencia ate a prevencao.
Use as etapas abaixo como um roteiro curto de pos-incidente ou investigacao tecnica. Cada etapa deve produzir um artefato simples.
Separar sintoma de impacto
O sintoma diz o que foi observado. O impacto diz por que isso importa para usuario, receita, operacao, seguranca ou indexacao.
Perguntas
- Qual fluxo, pagina, API, campanha ou rotina apresentou o problema?
- O problema afeta todos os usuarios ou apenas um grupo?
- Existe perda de lead, indisponibilidade, erro visivel, risco de dado ou queda de rastreamento?
- Quando comecou e qual foi a ultima mudanca conhecida?
Saida esperada
Um enunciado curto: "Em tal horario, tal fluxo apresentou tal sintoma com tal impacto".
Montar uma linha do tempo
A linha do tempo evita conclusoes apressadas. Ela aproxima sintoma, deploy, configuracao, trafego, DNS, campanha ou evento externo.
Perguntas
- Houve deploy, alteracao de ambiente, migracao, troca de DNS, campanha ou atualizacao de dependencia?
- O primeiro erro registrado vem antes ou depois do sintoma percebido?
- O problema apareceu junto de aumento de trafego, campanha ou publicacao de pagina?
- Existe diferenca entre horario do usuario, log da aplicacao e log do proxy?
Saida esperada
Uma sequencia com horario, evento, evidencia, efeito percebido e decisao tomada.
Formular hipoteses pequenas
Hipoteses pequenas ajudam a investigar sem mexer em tudo ao mesmo tempo. Cada uma precisa de uma evidencia que confirme ou descarte.
Perguntas
- O problema esta em codigo, dado, ambiente, proxy, permissao, fornecedor, campanha ou conteudo?
- Qual evidencia confirmaria essa hipotese?
- Qual teste descartaria essa hipotese com baixo risco?
- A hipotese explica todos os sintomas ou apenas parte deles?
Saida esperada
Uma lista de 2 a 4 hipoteses com evidencia esperada e teste de verificacao.
Confirmar causa antes de corrigir
Causa provavel ainda nao e causa raiz. Confirmar evita corrigir um sintoma e deixar o problema voltar no proximo deploy.
Perguntas
- A causa explica o sintoma, o horario, o alcance e o impacto?
- A correcao proposta remove a causa ou apenas contorna a manifestacao?
- Existe evidencia antes e depois da correcao?
- O mesmo problema pode acontecer em outra rota, pagina, campanha ou ambiente?
Saida esperada
Uma causa confirmada, uma correcao aplicada e uma evidencia de validacao.
Transformar causa em prevencao
A investigacao so termina quando deixa um ajuste no sistema de trabalho: checklist, alerta, teste, documento, permissao ou rotina.
Perguntas
- Qual evidencia teria revelado o problema mais cedo?
- Qual checklist precisa mudar?
- Qual decisao tecnica precisa ser registrada?
- A prevencao cabe na rotina semanal, mensal, pos-deploy ou pos-incidente?
Saida esperada
Uma acao preventiva pequena, verificavel e com dono.
Tipos de causa
Causa raiz pode morar fora do lugar onde o erro aparece.
Um erro visivel no frontend pode nascer no proxy. Um problema de campanha pode estar no formulario. Uma API lenta pode ser banco, dado historico ou falta de indice.
Codigo, contrato ou regra de API
A falha nasce em validacao, regra de negocio, serializacao, status HTTP, contrato quebrado ou tratamento de excecao insuficiente.
Exemplos
- Erro 500 depois de uma validacao nova
- Endpoint muda resposta e quebra consumidor
- Payload raro causa excecao nao tratada
- Mensagem de erro esconde o campo que falhou
Evidencias uteis
- Endpoint
- payload anonimizado
- status HTTP
- stack trace
- commit relacionado
Prevencao comum
Mapear contrato, criar teste para o caso quebrado e registrar regra de erro esperada.
Dados, banco ou migracao
A causa esta em dado inesperado, indice ausente, migracao incompleta, schema diferente ou consulta que nao suporta o volume real.
Exemplos
- Consulta lenta apenas com clientes grandes
- Campo nulo antigo quebra regra nova
- Indice esperado nao existe em producao
- Migracao roda em ambiente e falha em outro
Evidencias uteis
- consulta
- plano de execucao quando houver
- schema
- volume
- registro afetado mascarado
Prevencao comum
Validar migracoes, revisar dados historicos e criar rotina de backup/restauracao testada.
Ambiente, variavel ou configuracao
A aplicacao esta correta, mas o ambiente publicado usa variavel, porta, URL, segredo, perfil ou recurso diferente do esperado.
Exemplos
- SMTP local funciona, mas producao usa From invalido
- URL da API aponta para dominio antigo
- Container sobe sem variavel obrigatoria
- SSL, proxy ou base path muda a rota final
Evidencias uteis
- variavel esperada sem valor secreto
- ambiente
- container
- log de inicializacao
- host publico
Prevencao comum
Documentar variaveis, validar ambiente no deploy e separar segredo de configuracao publica.
Infraestrutura, DNS ou proxy
A causa aparece fora do codigo: DNS, Cloudflare, Nginx, certificado, porta, rota SPA, cache, container ou rede.
Exemplos
- Dominio aponta para IP antigo
- mail fica como CNAME do site e confunde e-mail
- Rota React cai na home por falta de fallback correto
- Nginx encaminha para porta errada
Evidencias uteis
- registro DNS
- status proxy
- resposta HTTP
- logs Nginx
- certificado
- porta/container
Prevencao comum
Manter mapa de dominio, proxy, containers e validacao de rotas publicas depois de mudancas.
Observabilidade insuficiente
A causa nao fica visivel porque o sistema nao registra rota, tempo, erro, usuario tecnico, correlacao ou etapa afetada.
Exemplos
- Nao ha log do endpoint com erro
- Tudo vira erro generico sem contexto
- Tempo lento nao informa se foi banco, API externa ou serializacao
- Nao existe indicador antes e depois do deploy
Evidencias uteis
- lacuna de log
- metricas ausentes
- erro generico
- dificuldade de reproduzir
Prevencao comum
Adicionar logs orientados a investigacao e indicadores simples nas rotas mais importantes.
Processo, deploy ou validacao incompleta
O problema nao e uma linha de codigo isolada. Ele aparece porque a publicacao nao tinha checklist, rollback, validacao ou dono claro.
Exemplos
- Pagina nova nao entra no sitemap
- Formulario nao e testado depois de deploy
- Rollback nao estava documentado
- Mudanca de campanha acontece sem teste de conversao
Evidencias uteis
- checklist ausente
- validacao incompleta
- rota nao testada
- rollback indefinido
Prevencao comum
Criar checklist pos-deploy, registrar validacoes e definir responsavel por cada publicacao.
Conteudo, tag ou rastreamento
A causa esta na camada de descoberta e monetizacao: tag ausente, UTM perdida, pagina sem proximo passo, schema desalinhado ou conteudo escondido.
Exemplos
- Google Ads gera clique, mas conversao nao registra
- Contato chega sem UTM
- Pagina publicada nao aparece na busca interna
- Conteudo novo nao tem link interno nem sitemap
Evidencias uteis
- URL final
- UTM
- Tag Assistant
- sitemap
- busca interna
- evento de conversao
Prevencao comum
Validar tags, UTMs, formularios, sitemap e links internos como parte da rotina editorial.
Governanca, acesso ou IA sem limite claro
A causa raiz e permissao ampla, segredo exposto, fonte sem confianca, IA sem revisao ou processo sem dono tecnico.
Exemplos
- Senha real aparece em print ou repositorio
- IA usa documento desatualizado como fonte
- Codigo gerado e publicado sem revisao
- Conta compartilhada impede rastrear mudanca
Evidencias uteis
- fonte
- permissao
- segredo afetado
- usuario
- revisao humana
- teste de resposta
Prevencao comum
Separar acessos, registrar fontes, revisar codigo gerado e manter limites claros para automacao.
Perguntas comuns
A melhor correcao deixa rastro para o futuro.
Se a equipe nao consegue explicar por que corrigiu, como validou e como vai evitar repeticao, a causa provavelmente ainda esta parcialmente escondida.
Causa raiz e sempre uma causa unica?
Nao. Em sistemas web, a causa costuma combinar codigo, ambiente, processo, dado, proxy, campanha ou falta de observabilidade. O importante e separar causa confirmada de suposicao.
Quando a analise de causa raiz deve acontecer?
Depois da contencao inicial e antes de encerrar o incidente. Se a operacao esta parada, primeiro reduza impacto. Depois investigue para prevenir reincidencia.
Como evitar que a analise vire burocracia?
Limite o registro ao essencial: sintoma, impacto, linha do tempo, evidencias, causa confirmada, correcao, validacao e uma prevencao pequena com dono.