Runbook — Incidente no Bot Handler

Sinais de incidente

• Erro elevado (5xx) no API Gateway/Lambda.
• Latência p95 acima do SLO da fase.
• Falhas consecutivas de dependências (llm_gateway, data_service, sqs_send).
• Circuit breaker aberto com recorrência.

Pré-requisitos de acesso

• Permissão de leitura em CloudWatch Logs/Metrics.
• Permissão de leitura em filas SQS e funções Lambda.
• Acesso ao repositório e workflow de CI.

Passo a passo (triagem)

1. Confirmar GET /health:

   curl https://<api-url>/health
   # Esperado: 200 {"status":"ok"}

   Verificar metrics e circuits no payload.

2. Verificar logs recentes da função — buscar:

   • trace.end com outcome=error
   • reason=rate_limit, kpi_query_failure
   • Erros de parsing/auth

3. Validar integridade de dependências:

   • llm_gateway respondendo
   • data_service respondendo consultas
   • Fila SQS disponível

4. Conferir regressão recente:

   • Últimos commits na branch staging
   • Resultado dos jobs quality e smoke no CI

Mitigação imediata

Cenário	Ação
Falha em dependência externa	Modo degradado, resposta amigável ao usuário
Falha no enqueue SQS	Confirmar ao usuário e registrar para retry operacional
Erro de autenticação/assinatura	Validar ALLOW_ANONYMOUS, VALIDATE_BOT_SIGNATURE, BOT_SIGNATURE_SECRET
Circuit breaker aberto persistente	Investigar causa raiz, aguardar cool down

Verificação pós-mitigação

npm run lint
npm run build
npm run test
npm run test:smoke

GET /health deve retornar status=ok sem crescimento anômalo de falhas.

Critério de encerramento

• Erro e latência retornam à faixa normal por pelo menos 30 minutos.
• Sem novos alarmes críticos no período.
• Causa raiz e ação preventiva documentadas.