Runbook de queda: o que olhar primeiro e o restore escrito em comandos

Três da manhã, a API da loja responde 502 e quem está de plantão é a desenvolvedora que entrou há dois meses. O documento "Operação" tem 12 páginas: diagrama de arquitetura, histórico das decisões, a filosofia do deploy. Em lugar nenhum está o comando que mostra que o disco encheu. Ela rola a tela, chuta, reinicia o serviço três vezes e acorda o líder às 4h10. O problema era um log de 40 GB.

A resposta curta: runbook é uma página por problema, que começa pelo sintoma e segue com comandos que se copiam. Cada passo diz o que você deve ver quando está tudo normal, o que fazer se não estiver e em que ponto parar e chamar outra pessoa. Teoria e arquitetura ficam em outro documento, com link.

Por que o documento longo falha no incidente

No susto, a capacidade de ler e interpretar cai muito. A pessoa não quer entender o sistema; quer saber qual é o próximo comando e se o resultado está bom. Um parágrafo como "verifique se há espaço suficiente nos volumes relevantes" exige que ela saiba quais volumes são relevantes e o que é suficiente. Às 3h, isso vira chute.

O capítulo de resposta a emergências do livro de SRE do Google insiste em dois pontos que cabem aqui: o que não foi ensaiado tende a falhar, e a lição de cada incidente precisa voltar para o procedimento escrito. Runbook que ninguém atualiza depois de usar envelhece com o sistema.

A estrutura de um runbook que funciona

Cada runbook responde às mesmas perguntas, na mesma ordem, para que a pessoa saiba onde olhar sem ler tudo.

1. Sintoma: o que o alerta ou o usuário relatou, nas palavras que vão aparecer na tela. É por isso que o link do alerta aponta para cá.
2. Impacto: quem é afetado e quão urgente é. Ajuda a decidir se dá para esperar ou se precisa de mais gente agora.
3. Diagnóstico: comandos em bloco, cada um seguido de "normal é..." e "se aparecer X, vá para o passo Y".
4. Correção: os passos para resolver, em ordem, com o comando exato.
5. Confirmação: como saber que passou. Um curl que devolve 200, um gráfico que volta ao normal.
6. Escalonar: quando parar de tentar e quem chamar, com o canal. "Se em 20 minutos não voltou, chame fulano pelo telefone do plantão."
7. Onde estão as credenciais: o nome do item no cofre de senhas, nunca a senha.

Exemplo: API fora por disco cheio

Este é o runbook que teria resolvido a madrugada do primeiro parágrafo. Ele vive no repositório da operação, em texto simples, e o alerta de disco tem o link dele.

RUNBOOK: API da loja responde 502 / disco cheio em api-01
Atualizado: 2026-10-17 por Carla

SINTOMA
  Alerta "DiscoRaizCheio" ou API com 502. Nginx no ar, aplicação não escreve.

IMPACTO
  Checkout parado. Urgente.

1. Confirmar que o disco encheu
   df -h /
   Normal: Use% abaixo de 80%.
   Se 100%: siga para o passo 2.
   Se abaixo de 90%: o disco não é a causa. Vá para o runbook "API 502 geral".

2. Achar o que cresceu
   sudo du -xh /var --max-depth=2 2>/dev/null | sort -h | tail -n 15
   Esperado: /var/log e /var/lib/docker no topo.

3a. Se /var/log/journal for o maior
   journalctl --disk-usage
   sudo journalctl --vacuum-size=500M

3b. Se /var/log/loja/ for o maior
   ls -lhS /var/log/loja/ | head
   Comprima os arquivos antigos (.log.1, .log.2) com gzip.
   NÃO apague o arquivo aberto (loja.log): o espaço só volta quando o processo fecha o arquivo.

3c. Se /var/lib/docker for o maior
   docker system df
   Não rode prune sem saber o que vai sair. Escale.

4. Religar e confirmar
   sudo systemctl restart loja-api
   curl -fsS https://loja.exemplo.com.br/health
   Normal: {"status":"ok"} e df -h / abaixo de 85%.

ESCALAR
  Se em 20 minutos não voltou, ou se o passo 2 mostrar algo fora desta lista:
  ligue para o plantão secundário (escala no canal #plantao).

CREDENCIAIS
  SSH: chave pessoal. Sudo: item "api-01 sudo" no cofre da equipe.

Repare no que esse texto evita. Não explica o que é journald. Não diz "libere espaço" sem dizer onde. Avisa do erro clássico de apagar um log aberto, que não devolve espaço enquanto o processo segura o arquivo. E diz quando parar.

Exemplo: restaurar o banco a partir do backup

O restore é o runbook mais importante e o menos usado, o que é a pior combinação. Ninguém lembra dos passos porque eles quase nunca acontecem. Escreva-o com os nomes reais e ensaie com ele, como em O backup que ninguém restaurou ainda não é backup.

RUNBOOK: restaurar o banco "loja" (MySQL) a partir do backup externo
Atualizado: 2026-10-17 por Carla. Último ensaio: 2026-10-03, 22 minutos.

QUANDO USAR
  Banco corrompido, dados apagados por engano ou servidor perdido.
  Decisão de restaurar: líder de plantão. Restaurar descarta o que veio depois do backup.

1. Pôr a loja em manutenção
   sudo systemctl stop loja-api

2. Baixar o backup mais recente do armazenamento externo
   rclone lsf remoto-backup:mysql/ | sort | tail -n 3
   rclone copy remoto-backup:mysql/loja-2026-10-17-0300.sql.gz /tmp/restore/
   Normal: arquivo com mais de 300 MB. Se for muito menor, PARE e escale.

3. Restaurar num banco novo, sem tocar no atual
   mysql --defaults-extra-file=/etc/loja/restore.cnf -e "CREATE DATABASE loja_restore CHARACTER SET utf8mb4;"
   gunzip -c /tmp/restore/loja-2026-10-17-0300.sql.gz | mysql --defaults-extra-file=/etc/loja/restore.cnf loja_restore
   Leva cerca de 15 minutos.

4. Conferir
   mysql --defaults-extra-file=/etc/loja/restore.cnf loja_restore -e "SELECT COUNT(*), MAX(criado_em) FROM pedidos;"
   Normal: MAX(criado_em) perto do horário do backup.

5. Apontar a aplicação e religar
   Em /etc/loja/api.env, troque DB_NAME=loja por DB_NAME=loja_restore
   sudo systemctl start loja-api
   curl -fsS https://loja.exemplo.com.br/health

6. Avisar
   Canal #incidentes: horário do backup usado e o intervalo de dados perdido.

CREDENCIAIS
  /etc/loja/restore.cnf (permissão 600). Senha do usuário de restore: item "mysql restore" no cofre.

Duas decisões nesse texto são deliberadas. Restaurar em loja_restore, em vez de por cima de loja, preserva o banco danificado para investigação e permite voltar atrás. E a linha "decisão de restaurar: líder de plantão" existe porque restaurar descarta dados, e quem está sozinho às 3h não deveria carregar essa escolha. Se a sua volta envolve versão de aplicação, junte com o roteiro de rollback ensaiado.

Como manter os runbooks vivos

1. Um alerta, um link. Toda página do plantão aponta para o runbook dela. Alerta sem runbook é sinal de que falta escrever, ou de que ele não deveria acordar ninguém.
2. Atualize logo depois de usar. No mesmo dia, enquanto a memória está fresca: o comando que faltou, a saída que era diferente, o passo que confundiu.
3. Ensaie com quem não escreveu. Uma vez por trimestre, alguém novo segue o runbook num ambiente de teste. Cada pergunta que essa pessoa fizer é uma linha que faltava.
4. Data e autor no topo. Runbook sem data não diz se ainda vale.
5. Guarde onde o incidente não alcança. Se o runbook vive na wiki que roda no mesmo servidor que caiu, ele cai junto. Tenha uma cópia no repositório ou em serviço externo.

Erros comuns

• Começar pela arquitetura. A pessoa rola até achar um comando e perde os minutos mais valiosos do incidente.
• Passo sem "normal é...". Ela roda o comando e não sabe se o resultado é bom ou ruim, então chuta.
• Colar senha no runbook. O documento circula, vai para o chat e vira vazamento. Aponte para o item do cofre; veja também log sem senha.
• Nenhum ponto de parada. Quem está sozinho tenta por uma hora antes de chamar ajuda, e o incidente dobra de tamanho.
• Restore por cima do banco danificado. Se o backup também estiver ruim, não sobra nada para investigar nem para recuperar à mão.
• Nunca atualizar. O comando mudou de nome, o servidor mudou de IP, e o runbook passa a ensinar o caminho errado.

Checklist

• Uma página por problema, com o sintoma na primeira linha.
• Comandos em bloco, prontos para copiar, com nomes reais de servidor e serviço.
• Cada passo de diagnóstico diz o que é normal e para onde ir se não for.
• Passo de confirmação que prova que o problema passou.
• Critério de escalonamento com tempo e contato.
• Credenciais referenciadas pelo nome no cofre, nunca escritas.
• Data, autor e data do último ensaio no topo.
• Cópia acessível mesmo com o sistema principal fora do ar.

Pegue o alerta mais comum do seu plantão e abra o runbook dele. Alguém que nunca viu o sistema consegue chegar ao fim só copiando comandos, sem interpretar nenhum parágrafo longo? Se a resposta for não, é por ele que você começa.