Runbooks de resposta a incidentes que realmente são usados
Um runbook que abre com arquitetura do sistema é documentação para onboarding, não operações para as 3 da manhã. Runbooks de incidentes são usados quando começam com sintomas, ramificam em sinais observáveis e terminam com passos de verificação curtos o bastante para executar sob estresse.
O pager disparou às 2:47 da manhã. On-call abriu o wiki. O runbook começava com um diagrama de microsserviços de 2022. Três serviços tinham sido renomeados. Um foi removido. O diagrama não tinha link para logs, nem "se taxa de erro em X," nem comando de rollback. Vinte minutos passaram lendo prosa sobre filosofia do sistema. Runbooks de resposta a incidentes que realmente são usados compartilham uma propriedade: começam onde o incidente começa — um sintoma, um alerta, um relato de cliente — e ramificam em checagens que levam segundos, não capítulos que consomem atenção.
Runbooks não são documentação. Documentação ensina o sistema. Runbooks guiam ação quando o sistema está falhando e a cognição está prejudicada. A diferença é estrutura: árvores de decisão versus ensaios, comandos versus conceitos, passos de verificação versus contexto histórico.
Runbooks falham quando escritos para leitores calmos
| Runbook anti-pattern | Why it fails at 3 AM |
|---|---|
| Visão geral de arquitetura primeiro | O leitor precisa de ação, não de contexto |
| Parágrafos em prosa | A varredura falha sob estresse |
| Nomes de serviço obsoletos | A confiança colapsa na primeira referência errada |
| Sem owner nem data da última verificação | Não está claro se é seguro seguir |
| Links para links | A navegação quebra no mobile |
| "Contatar o time" | Sem telefone, sem caminho de escalação |
Bons runbooks assumem: o leitor pode ser novo, cansado, sozinho e desconhecedor de deploys recentes. Cada passo deve ser executável sem memória institucional.
Um runbook é um programa para humanos. Se não ramifica em condições, é um script que só roda em uma máquina — a sua, há seis meses.
Anatomia de um runbook que realmente é aberto
Header (cinco linhas no máximo)
- Nome do serviço / sintoma
- Contexto de severidade (quando usar este runbook)
- Data da última verificação + owner
- Alertas relacionados (nomes no PagerDuty, Grafana)
- Contato de escalação
Pontos de entrada por sintoma
Múltiplas rotas de entrada — a mesma causa raiz pode se apresentar de formas diferentes:
Entry: Checkout error rate > 2%
Entry: Payment provider webhook failures
Entry: Customer report "card charged, order missing"
Árvore de decisão (núcleo)
1. Check payment provider status page → outage?
YES → Post status, enable maintenance message, DONE (monitor)
NO → step 2
2. Recent deploy < 30 min?
YES → Execute rollback runbook §1 → verify → DONE or escalate
NO → step 3
3. DB connection pool exhausted?
YES → Scale pool / kill long queries (link command) → verify
NO → escalate to payments on-call
Comandos prontos para copiar e colar
CLI exato, URLs de dashboard, SQL com placeholders marcados {{service}}. Nada de "rodar a limpeza habitual."
Verificação
Como saber que o incidente está resolvido — limiares de métricas, smoke test, transação de amostra.
Template de comunicação
Texto de status page, mensagem interna no Slack — preencher em branco.
Linkar estratégia de rollback com árvores de decisão dentro de ramos relacionados a deploy — não duplicar, referenciar.
Organizar por sintoma, não por organograma de serviços
Runbooks por serviço ("Payments Runbook") envelhecem mal quando a propriedade muda. Runbooks por sintoma ("Checkout failures") se alinham com como alertas e clientes chegam.
Linkar runbooks relacionados:
- Taxa de erro alta → caminho de rollback de deploy
- Latência elevada → runbook de banco de dados / cache
- Falhas de auth → runbook de provedor de identidade
Página índice: nome do alerta → URL do runbook. On-call não deveria buscar no Confluence.
Manter runbooks vivos
Runbooks apodrecem mais rápido que código.
Data da última verificação — game day trimestral ou atualização pós-incidente obrigatória.
Mandato pós-incidente — cada sev-1/sev-2 atualiza ou cria runbook em 48 horas. Item de ação do postmortem sem culpa: "lacuna de runbook."
Automatizar passos onde possível — o runbook dispara script para operações seguras (reiniciar worker, limpar fila travada). Passos humanos para decisões de julgamento.
Limite de tamanho — uma tela por nó de decisão. Runbooks longos se dividem em sub-runbooks linkados.
Alertas de burn de SLO indicam que se está em território de incidente. Runbooks dizem o que fazer — parear cada alerta de burn com link de runbook no payload do alerta.
Papéis durante incidentes: o que runbooks assumem
Mesmo times pequenos se beneficiam de papéis explícitos no header do runbook:
| Role | Responsibility |
|---|---|
| Incident commander | Coordena, comunica, decide escalação |
| Investigator | Segue a árvore técnica |
| Communicator | Status page, sync com suporte ao cliente |
| Scribe | Timeline para postmortem |
On-call solo pode usar todos os chapéus — o runbook ainda anota qual chapéu cada seção serve para que nada seja esquecido.
Como times devem escrever runbooks de incidentes?
Esses padrões separam runbooks operacionais do preenchimento do wiki.
Quão longo deve ser um runbook?
O mais curto possível para o caminho de decisão. Meta: primeira ação em 60 segundos de abrir. Se contexto de arquitetura for necessário, linkar para doc separada — não antepor.
O que vai no runbook versus postmortem?
Runbook: como corrigir ou mitigar agora. Postmortem: por que aconteceu, correções sistêmicas. Runbooks podem anotar falsos positivos conhecidos de incidentes passados — uma linha, não postmortem completo.
Runbooks devem incluir comandos de rollback?
Sim, quando correlação com deploy é modo de falha comum. Referenciar árvore de decisão de rollback centralizada; incluir comandos específicos do serviço (redeploy tag, nome de toggle de flag).
Uma visão oposta
A postura contrária sustenta que boa observabilidade e remediação automatizada tornam runbooks obsoletos — que dashboards e sistemas auto-reparadores substituem procedimentos escritos.
Automação trata known knowns. Incidentes costumam ser combinações novas — deploy mais outage de provedor mais pico de tráfego. Runbooks capturam memória organizacional para sequências de checagem que automação não deveria executar sem supervisão (rollback, reparo de dados). Observabilidade sem runbooks produz paralisia informada — muitos gráficos, sem próximo passo.
Key takeaways
- Runbooks começam com sintomas e alertas — não diagramas de arquitetura.
- Árvores de decisão com ramos sim/não vencem prosa; primeira ação em 60 segundos.
- Comandos copiar-colar, limiares de verificação, templates de comunicação obrigatórios.
- Índice nome do alerta → URL do runbook; runbooks obsoletos pior que nenhum — verificar trimestralmente.
- Atualizações pós-incidente em 48 horas para sev-1/sev-2; linkar runbooks de rollback e SLO.
- Dividir procedimentos longos em sub-runbooks linkados; uma tela por nó de decisão.
Conclusion
Runbooks de resposta a incidentes que realmente são usados são escritos para a versão de on-call que está acordada há noventa minutos e não lembra o deploy do trimestre passado. Sintomas primeiro, ramos em fatos observáveis, verificação antes do all-clear. Todo o resto é documentação com rótulo de runbook.
O exercício: escolher as últimas três páginas. Para cada uma, abrir o runbook linkado. Tempo até a primeira ação executável. Mais de dois minutos — reescrever antes da próxima página.