Como construir runbooks úteis que o time realmente consulta em incidentes

1. Por que a maioria dos runbooks falha (e como evitar)

O maior erro ao criar runbooks é tratá-los como documentação estática. Estudos mostram que 70% dos runbooks corporativos nunca são atualizados após a primeira versão, tornando-se "letra morta". Quando um incidente real acontece, o time prefere debuggar do zero a confiar em instruções desatualizadas.

A armadilha do excesso de detalhes é igualmente perigosa. Um runbook de 15 páginas descrevendo cada nuance do sistema vira um manual de operação, não uma ferramenta de resposta rápida. Em incidentes, o cérebro humano opera em modo de estresse — listas longas são ignoradas.

A falta de testes e validação é o terceiro pecado capital. Runbooks que nunca foram executados em cenário real contêm erros óbvios: comandos que não funcionam, caminhos de diretório incorretos, permissões quebradas.

Como evitar: Adote o princípio do "MVP do runbook" — comece com 3 a 5 passos críticos, valide em um game day, e evolua baseado em incidentes reais.

2. Estrutura enxuta e orientada a decisões

O formato "Se-Então" transforma um runbook confuso em uma árvore de decisões clara. Cada passo deve responder a uma pergunta específica:

SE o P99 de latência > 500ms ENTÃO:
  1. Acesse o dashboard de performance: [link]
  2. Verifique o número de conexões ativas:
     comando: curl -s http://localhost:8080/metrics | grep connections
  3. Se conexões > 1000, execute:
     kubectl scale deployment api-server --replicas=5
  4. Monitore o P99 por 2 minutos
  5. Se não normalizar, suba para o time de infra: #incident-escale

Checklist mínimo de sobrevivência:

CHECKLIST DE 5 PASSOS:
[ ] 1. Confirmar o alerta: [link para alerta]
[ ] 2. Verificar status dos serviços críticos: [dashboard]
[ ] 3. Coletar logs dos últimos 5 minutos: journalctl -u api-server --since "5 min ago"
[ ] 4. Aplicar mitigação conhecida (se existir): [comando]
[ ] 5. Escalonar se não resolvido em 10 min: [contato do SRE sênior]

Inclua playbooks de escalonamento explícitos:

QUANDO SUBIR O INCIDENTE:
- 5 min sem progresso: Notificar #sre-oncall
- 15 min sem resolução: Chamar engenheiro de plantão (telefone: +55 11 99999-9999)
- 30 min: Acionar gerente de operações

3. Linguagem e acessibilidade para times multidisciplinares

Use linguagem clara e sem jargões desnecessários. Um runbook deve ser compreensível por um desenvolvedor júnior, um SRE e um analista de suporte.

Hierarquia visual é crucial:

# TÍTULO: Falha no serviço de pagamentos

## SINTOMAS
- Erro 503 na API de pagamentos
- Faturamento parou de processar

## DIAGNÓSTICO RÁPIDO
1. Verifique o health check:
   ➡️ comando: curl -f https://api.pagamentos.com/health
   ➡️ resposta esperada: {"status": "ok"}

2. Consulte o banco de dados:
   ➡️ comando: SELECT count(*) FROM transacoes WHERE status = 'pending';
   ➡️ se > 1000, há acúmulo de transações

## MITIGAÇÃO
⚠️ **COMANDO CRÍTICO**: Reinicie o worker de processamento
   kubectl rollout restart deployment payment-worker

## ESCALONAMENTO
Se o erro persistir após 5 minutos:
   ➡️ Slack: #incident-pagamentos
   ➡️ Telefone: [número do SRE]

4. Integração com ferramentas de observabilidade

Runbooks úteis não existem isolados — eles se conectam diretamente às ferramentas que o time já usa. Inclua links diretos para dashboards e métricas relevantes:

DASHBOARDS RELACIONADOS:
- P99 Latency: [link para Grafana]
- Error Budget: [link para painel de SLOs]
- Taxa de Erro: [link para Datadog]

Configure gatilhos de alerta que puxam automaticamente o runbook correto. Exemplo de configuração no PagerDuty:

Alerta: "High P99 Latency on Payment API"
Ação: Incluir link para runbook: https://runbooks.internal/payment-high-latency

Exemplo de comando para consulta rápida em produção:

# Verificar conexões ativas no banco de dados
psql -h db-primary -c "SELECT count(*) FROM pg_stat_activity WHERE state = 'active';"

# Verificar uso de memória do serviço
curl -s http://localhost:9090/metrics | grep -E "process_resident_memory_bytes|http_requests_total"

5. Ciclo de vida e manutenção contínua

Após cada incidente, atualize o runbook com o que foi aprendido. Crie um processo de revisão pós-incidente:

TEMPLATE DE ATUALIZAÇÃO PÓS-INCIDENTE:
- Data do incidente: [data]
- O que funcionou: [passos que salvaram tempo]
- O que faltou: [comandos ou diagnósticos que não estavam no runbook]
- Nova versão: [link para PR com as alterações]

Realize testes periódicos com game days. Exemplo de cenário:

GAME DAY: Simulação de falha no banco de dados
Passos a testar:
1. Executar comando de failover: pg_ctl promote standby
2. Verificar se o runbook aponta para o comando correto
3. Medir tempo para completar cada passo
4. Coletar feedback: "O runbook foi claro?"

Mantenha versionamento e changelog:

CHANGELOG DO RUNBOOK:
v1.2 - 2024-03-15 - Adicionado comando de failover do banco
v1.1 - 2024-02-28 - Corrigido link do dashboard de P99
v1.0 - 2024-01-10 - Versão inicial

6. Adoção cultural e incentivo ao uso

Runbook deve ser parte obrigatória do playbook de on-call. Crie uma política clara:

POLÍTICA DE ON-CALL:
- Todo plantonista deve ler os runbooks dos serviços sob sua responsabilidade
- Durante incidentes, o primeiro passo é abrir o runbook correspondente
- Se o runbook não existir, criar um é prioridade pós-incidente

Gamificação pode aumentar a adoção:

MÉTRICAS DE GAMIFICAÇÃO:
- Taxa de consulta: quantos incidentes tiveram runbook consultado?
- Tempo de resolução: redução após adoção do runbook?
- Pontuação: runbooks mais consultados ganham "estrelas" no repositório

Crie um canal de feedback loop:

CANAL DE SUGESTÕES:
- Slack: #runbook-feedback
- Formulário: [link para Google Forms anônimo]
- Recompensa: quem sugerir correção ganha café

7. Métricas para medir a utilidade real do runbook

A utilidade de um runbook deve ser mensurada objetivamente:

MÉTRICAS PRINCIPAIS:
- Taxa de consulta: (incidentes com runbook acessado) / (total de incidentes) > 80%
- Tempo médio de resolução (MTTR): comparar antes e depois da adoção
- Steps pulados: se > 30% dos passos são ignorados, o runbook tem ruído

Pesquisa de satisfação pós-incidente:

PESQUISA PÓS-INCIDENTE:
1. O runbook ajudou a resolver o incidente? [Sim / Não / Parcialmente]
2. Os comandos funcionaram sem erros? [Sim / Não]
3. O que poderia ser melhorado? [campo de texto livre]
4. Nota geral (1-5): [nota]

Se a taxa de satisfação for menor que 4, o runbook precisa de revisão urgente.

Referências