Runbook: a diferença entre resposta em minutos e em horas

TL;DR

• Runbook separa resposta profissional de improvisação sob pressão. Sem runbook, plantão é tentativa e erro de madrugada.
• Os 5 campos obrigatórios: sintoma, diagnóstico, mitigação, validação, escalonamento. Runbook sem esses é texto, não procedimento.
• Runbook não testado em staging é texto morto. Teste mensal, em ambiente isolado, simulando o sintoma.
• Runbook mora no mesmo repositório do código. Versionado, revisado em PR, propriedade clara do mantenedor.
• Runbook que cobre 5 cenários recorrentes vale mais que enciclopédia de 50 cenários que ninguém consulta.
• Runbook é ferramenta de onboarding: sênior júnior aprende 80% da operação lendo os 10 runbooks ativos.

O que separa runbook de documentação morta

Documentação operacional tradicional nasce wiki e morre wiki. Texto livre, sem versionamento, sem teste, sem dono. Em 6 meses, ninguém lembra o que está desatualizado, e ninguém lê o que parece obsoleto. Quando o incidente chega, o operador ignora a wiki e improvisa — porque a wiki provavelmente está errada.

Runbook de verdade tem três propriedades que documentação wiki não tem. Primeiro, é executável: cada comando listado está validado e roda como esperado no ambiente-alvo. Segundo, é versionado: cada mudança passa por revisão e tem histórico. Terceiro, é testado: periodicamente alguém executa o procedimento em staging para confirmar que continua funcionando. Documentação que falha essas três propriedades é wiki. Runbook que passa essas três é o que separa resposta profissional de resposta amadora.

A métrica que captura a diferença é MTTR — Mean Time To Recover. Times com runbook versionado consistentemente reportam MTTR de 15-30 minutos para incidentes conhecidos. Times sem runbook reportam MTTR de 2-6 horas para os mesmos incidentes. A diferença não é talento — é processo.

Anatomia de um runbook executável

Runbook de verdade cabe em uma tela. Mais que isso, e o operador sob pressão vai rolar a página e perder o fio. Estrutura canônica: cabeçalho identificando o cenário, cinco campos obrigatórios em sequência, link para o dashboard ou log relevante, e critério de fechamento do incidente.

O cabeçalho é direto: título do cenário, serviço afetado, severidade esperada. Exemplo: “Banco lento — checkout-api — severidade 2”. Essa nomenclatura permite busca rápida e triagem automática em sistema de paging.

Os cinco campos vêm em ordem que reflete o fluxo de atendimento: primeiro detectar (sintoma), depois investigar (diagnóstico), depois agir (mitigação), depois validar (validação), depois decidir se precisa de ajuda (escalonamento). Runbook escrito fora dessa ordem confunde o operador que está lendo sob pressão de pager.

# Banco lento — checkout-api — severidade 2

**Sintoma:** latência p95 > 800ms em `checkout-api`
**Diagnóstico:** `pg_stat_activity` + `pg_stat_statements`
**Mitigação:** cancelar queries > 5min + reiniciar pool
**Validação:** p95 < 200ms em 5min
**Escalonamento:** se p95 não voltar em 15min → DBA on-call

Esse bloco cabe em 10 linhas. O operador copia os comandos do campo “diagnóstico”, segue para “mitigação” se confirmar o sintoma, valida, e escala se nada funcionar. Tempo total: 15-30 minutos para alguém que nunca viu o sistema antes.

Os 5 campos obrigatórios em cada runbook

Cada campo tem função específica e critério de qualidade. Sintoma precisa ser detectável por métrica ou log automatizado — não pode ser “o sistema parece lento”. Diagnóstico lista os comandos que confirmam que o sintoma é realmente o problema descrito. Mitigação é o conjunto de comandos que resolve a situação sem causar efeito colateral pior. Validação confirma que a mitigação funcionou. Escalonamento define quando parar de tentar e chamar alguém mais sênior.

Sintoma bem escrito tem threshold numérico. “Latência alta” é vago. “latência p95 > 800ms em checkout-api por mais de 3 minutos” é detectável pelo Prometheus e dispara alerta automaticamente. Sem threshold, sintoma vira opinião — três pessoas diferentes vão interpretar de três formas.

Diagnóstico bem escrito tem um comando único que responde a pergunta principal. Em sistemas com Postgres, esse comando costuma ser `SELECT * FROM pg_stat_activity WHERE state = ‘active’ AND query_start < now() - interval '5 minutes'`. Esse comando mostra toda query rodando há mais de 5 minutos — em 90% dos incidentes de banco lento, a query culpada está nessa lista.

Mitigação bem escrita tem ordem de operações reversível. Primeiro a ação menos invasiva (`SELECT pg_cancel_backend(pid)`). Depois a mais invasiva (`SELECT pg_terminate_backend(pid)`). Por último o restart do serviço. Cada nível tem seu motivo para falhar e critério para avançar.

Validação bem escrita confirma que a métrica voltou ao baseline. Não basta “sistema parece OK” — é `latência p95 < 200ms por 5 minutos consecutivos`. Sem validação numérica, o operador fecha o incidente cedo demais e o sintoma volta em 30 minutos.

Escalonamento bem escrito tem tempo limite. “Se latência não voltar em 15 minutos, escalar para DBA on-call”. Sem tempo, o operador tenta cada vez mais coisas e nunca chama ajuda. Com tempo, há critério objetivo para parar de improvisar.

Como testar runbook antes de precisar dele

Runbook não testado é texto morto. A regra é simples: cada runbook ativo deve ser executado em staging pelo menos uma vez por mês. Quem testa não precisa ser o mesmo que escreveu — idealmente é alguém júnior que valida que o procedimento é executável por operador sem contexto.

O teste tem três passos. Primeiro, simular o sintoma em staging usando ferramentas de chaos engineering ou scripts que reproduzem a falha — kill de processo, sobrecarga de CPU, partição de rede. Segundo, executar o runbook como se fosse produção real, seguindo cada comando na ordem documentada. Terceiro, validar que o runbook levou o sistema de volta ao estado normal dentro do tempo esperado.

Runbook que falha o teste volta para revisão. Causa típica: comando que não roda mais porque API mudou, threshold desatualizado porque o serviço escalou, mitigação que funcionava em monolito mas não em microsserviço. Esses ajustes só aparecem quando alguém testa.

Ferramentas que facilitam o teste: Chaos Monkey (Netflix), Litmus (CNCF), Gremlin (comercial). Mesmo sem ferramenta dedicada, scripts bash que matam processo e validam recuperação cobrem 80% dos cenários.

Versionamento e propriedade do runbook

Runbook mora no repositório do código que ele descreve. Mesma branch, mesmo PR, mesma revisão. Quando alguém refatora checkout-api e muda o pool de conexão, o PR deve incluir a atualização do runbook “Banco lento — checkout-api”. Sem essa regra, runbook desatualiza inevitavelmente.

Propriedade do runbook segue propriedade do código. Se checkout-api é mantido pelo time X, o runbook de checkout-api é mantido pelo time X. Essa propriedade fica explícita no cabeçalho do runbook: “@time-x”. On-call que encontra runbook sem dono claro marca como “órfão” e cria tarefa de revisão.

Revisão de runbook segue mesmo processo de code review: 1-2 reviewers, aprovação explícita, merge via PR. Comandos errados em runbook têm o mesmo peso que código quebrado — operador executando o procedimento confia no comando documentado.

Histórico de mudanças no runbook é tão importante quanto histórico do código. Quem mudou o que, por quê, em que PR. Esse histórico responde perguntas como “por que esse comando de cancelamento foi adicionado em 2024-09” — informação crucial quando runbook para de funcionar e alguém precisa entender a intenção original.

Runbook como ferramenta de onboarding

Sênior júnior aprendendo a operação de um sistema tem 80% do conhecimento necessário nos runbooks ativos. Os 20% restantes vêm de mentoria, contexto histórico, e decisão de arquitetura. Runbook bem escrito é a diferença entre “júnior fica 6 meses perdido” e “júnior fica operacional em 2 semanas lendo os runbooks e fazendo perguntas pontuais”.

A prática recomendada é parear júnior com sênior em uma sessão de 2 horas por semana onde o sênior executa cada runbook ativo enquanto o júnior observa. Após 5-6 sessões, júnior conhece os principais cenários de incidente e tem confiança para entrar em plantão. Sem runbook, esse mesmo aprendizado levaria 6-12 meses de observação passiva.

O efeito colateral benéfico: ao explicar runbook para júnior, sênior identifica gaps e melhorias. Runbook que sênior não consegue explicar de forma clara provavelmente está mal escrito. Sessão de onboarding vira auditoria informal do runbook, e isso é bom para o time.

Os Cinco Campos como modelo de maturidade

O framework dos Cinco Campos Obrigatórios do Runbook funciona como régua de maturidade operacional. Estágio 1: runbooks existem mas faltam campos (geralmente validação e escalonamento). Estágio 2: runbooks têm os 5 campos mas não são testados. Estágio 3: runbooks são testados mensalmente mas versionamento é informal. Estágio 4: runbooks são versionados no mesmo repositório do código, revisados em PR, testados em staging, propriedade explícita.

Times brasileiros de operação em 2026 raramente passam do estágio 2. A maioria tem wikis bonitas que ninguém consulta e playbooks que ninguém testou. A diferença entre time de plantão tranquilo e time de plantão caótico é a transição do estágio 2 para o estágio 3 — exige disciplina mensal de teste em staging, não grandes investimentos em ferramentas.

Construir os 5 campos não é projeto. É decisão de priorizar: na próxima vez que alguém resolver um incidente em produção, escreve o runbook no formato dos 5 campos enquanto a memória está fresca. Em 6 meses, o time tem 10-15 runbooks ativos cobrindo os cenários mais frequentes. Esse é o tamanho mínimo viável para uma operação profissional.

Leitura relacionada

• Manutenção remota é skill que ninguém ensina — apresenta os quatro pilares da observabilidade remota; este post detalha o pilar de execução via runbook.
• Mobile é manutenção multiplataforma disfarçada de uma linguagem — mostra como runbook de crash reporting mobile segue os mesmos 5 campos adaptados a três ambientes.
• Manutenção de código web é debugar browsers como caixa-preta — aborda a camada cliente onde runbook tradicional falha e exige adaptação para estado de browser.