Modelo de runbook reutilizável para problemas recorrentes em produção

O que é um runbook e por que problemas recorrentes precisam de um

Um runbook é um conjunto curto e prático de instruções que ajuda alguém a consertar um problema conhecido em produção da mesma forma, toda vez. Ele transforma conhecimento tribal ("tente reiniciar" ou "verifique os logs") em passos claros, com comandos, responsáveis e cheques que confirmam que o sistema voltou a ficar saudável.

Um runbook não é um postmortem. Um postmortem explica o que aconteceu, por que aconteceu e o que você vai mudar para que não aconteça de novo. Um runbook é o que você usa durante o incidente, quando o tempo é curto e você precisa de ações seguras e repetíveis.

Runbooks ajudam especialmente quando problemas se repetem. Por exemplo: o mesmo alerta dispara toda semana (picos de CPU, backlog de filas, cron falhando), o suporte recebe o mesmo relato de usuário ("loop de login", "pagamentos travados"), deploys frequentemente causam uma quebra previsível (migrações, config, cache) ou existe um conserto que só uma pessoa lembra.

Aqui vai um exemplo simples: após alguns deploys, usuários relatam que não conseguem logar. Sem runbook, a pessoa de plantão chuta: reverter, reiniciar, mudar variáveis de ambiente, chamar alguém. Com um runbook, ela segue um caminho comprovado: confirma o sintoma, checa os poucos sinais que importam, aplica a ação corretiva mais segura e verifica se os logins voltaram a funcionar.

Um bom runbook reduz chutes e pânico. Ele não elimina incidentes nem substitui trabalho de engenharia para remover a causa raiz. O que ele faz é ganhar tempo, reduzir risco (menos mudanças aleatórias em produção) e tornar a resposta consistente, mesmo quando quem construiu o sistema não está disponível.

Escolha os erros certos para transformar em runbooks

Nem todo alerta merece um runbook. Comece por problemas que continuam puxando pessoas para o mesmo loop: as mesmas perguntas no Slack, os mesmos “quem sabe consertar isso?” e os mesmos passos manuais que vivem na memória de alguém.

Escolha questões que aconteçam com frequência ou que prejudiquem o negócio quando ocorrem (logins perdidos, pagamentos falhos, jobs presos). Se você ainda não consegue explicar um contorno confiável, deixe para depois e escreva uma nota curta de “sintomas conhecidos” em vez de um runbook completo.

Um filtro simples para seus primeiros 3 a 5 runbooks:

• Repete: aconteceu mais de uma vez nas últimas semanas.
• Impacto: bloqueia clientes ou receita, mesmo que seja raro.
• Previsibilidade: você tem um contorno conhecido, mesmo que a causa raiz não esteja totalmente entendida.
• Tempo: leva regularmente mais de 15 a 30 minutos para resolver.
• Propriedade: há uma equipe clara que pode manter o runbook.

A maioria das equipes encontra ganhos iniciais nas mesmas áreas: fluxos de login e autenticação (tokens, sessões, loops de redirecionamento), pagamentos e webhooks (retries, checagem de assinaturas), jobs em background e filas (workers presos, mensagens venenosas) e timeouts de API e limites de taxa (endpoints lentos, falhas em upstreams).

Estrutura do runbook: campos a incluir sempre

Um runbook só ajuda se for fácil de escanear sob estresse. Uma estrutura consistente também torna o próximo runbook mais rápido de escrever.

Comece com um cabeçalho que responda o básico à primeira vista:

• Nome do incidente (use a mesma expressão do seu alerta)
• Nível de severidade
• Serviço ou funcionalidade afetada
• Última atualização (nome e data)

Se o runbook estiver desatualizado, as pessoas vão hesitar em confiar nele.

Em seguida, adicione uma meta em uma linha que descreva o que “corrigido” significa em linguagem simples. Não diga “reiniciar o servidor”, diga “usuários conseguem fazer login novamente e a taxa de erro volta ao normal por 10 minutos”. Isso evita que as pessoas parem cedo.

Seja claro sobre para quem o runbook é direcionado. Um atendente precisa de detalhes diferentes de um engenheiro de plantão, um fundador ou um contratado. Se o leitor pretendido for não técnico, inclua checagens simples e onde clicar, não apenas jargão interno.

Liste acessos necessários logo no começo para que ninguém bata em um bloqueio no meio do incidente:

• Dashboards (métricas e rastreamento de erros)
• Logs (aplicação e infraestrutura)
• Painel de administração (usuários e cobrança)
• Console da nuvem (deploys e segredos)
• Sistema de feature flag ou de config

Depois mantenha alguns campos padrão para que todo runbook pareça familiar: pré-requisitos e notas de segurança (o que não fazer), contato de escalonamento, nota de rollback e um pequeno bloco de verificação de como confirmar a recuperação.

Ações passo a passo que as pessoas podem seguir

Comece com uma nota de segurança. Coloque o que é arriscado logo no começo para que ninguém “ajude” e piore tudo às 2h da manhã. Seja específico: “Não delete dados, não rotacione chaves nem reinicie um cluster inteiro sem aprovação do líder do incidente.” Se um passo pode causar downtime, diga sem rodeios.

Escreva passos como ações pequenas que alguém pode fazer em cerca de um minuto. Cada passo deve começar com um verbo (Verifique, Compare, Rode, Reverta). Mantenha cada passo focado: um passo, um objetivo, um resultado esperado.

Quando incluir comandos, faça o copy-paste previsível. Use placeholders e diga de onde eles vêm (ticket, logs, dashboard). Mantenha checagens somente leitura antes das mudanças.

# Set placeholders first
export ENV=prod
export SERVICE=api
export REQUEST_ID="<REQUEST_ID_FROM_LOGS>"

# Read-only: confirm the error is happening
kubectl -n $ENV logs deploy/$SERVICE --since=10m | grep "$REQUEST_ID" | tail -n 5

# Expected: lines include "ERROR" and the same REQUEST_ID

Depois de passos importantes, acrescente “o que você deve ver”. Se a saída esperada é vazia, diga isso. Se o sucesso significa que uma métrica cai, nomeie a métrica e a faixa normal.

Inclua um ponto de parada claro. Se os logs mostram um erro diferente do que o runbook presume, ou se um comando retorna permission denied, o próximo passo não é “tente mais”. É:

• Pare as mudanças
• Capture os sinais chave (timestamp, request ID, último deploy)
• Escale para o responsável listado por aquele sistema

Triagem e diagnóstico: encontre a causa sem chutar

Quando um alerta dispara, seu primeiro objetivo é aprender o formato do problema, não caçar um conserto esperto. O runbook deve tornar previsíveis os primeiros 10 minutos, mesmo quando o sistema está barulhento.

Comece pelo escopo. É um único usuário (dados da conta), uma região (edge ou roteamento) ou todos (dependência central)? Uma resposta rápida evita que você fuce no lugar errado.

Checagens rápidas que frequentemente explicam falhas “súbitas”

Antes de mergulhar nos logs, verifique os suspeitos de sempre:

• Deploys, rollouts ou migrações recentes nos últimos 30 a 60 minutos
• Mudanças de config (env vars, segredos, strings de conexão) e credenciais expiradas
• Feature flags ou experimentos que mudaram regras de direcionamento
• Incidentes em dependências (banco, fila, provedor de autenticação) e limites de taxa
• Alterações de capacidade (autoscaling travado, nova fonte de tráfego, pico de cron)

Então pegue alguns números que ajudam a escolher uma direção: tendência da taxa de erro, latência, profundidade da fila e contagem de conexões do banco (ou saturação). Se puder, compare “agora” com “última hora” e “mesma hora de ontem” para identificar mudanças.

Encontre a primeira mensagem de erro útil

Logs podem ser intermináveis. Filtre pelo endpoint ou nome do job que está falhando e procure o erro mais antigo na cadeia (não a última stack trace). Escolha um único request ID, user ID ou uma janela de tempo estreita em torno do pico e siga até achar o primeiro “por quê”.

Se o monitoramento estiver faltando (comum em protótipos apressados), o runbook deve dizer o que capturar manualmente antes de mudar qualquer coisa:

• Hora exata em que o problema começou e como foi detectado
• Alguns exemplos de user IDs ou request IDs que falham
• Uma resposta de erro completa e uma resposta bem-sucedida (se houver)
• Versão/commit atual da app e estado das feature flags ativas
• Screenshot ou exportação dos gráficos chave que você tem

Esse pequeno pacote de evidências evita chutes e torna a passagem para outras pessoas mais limpa.

Responsáveis e escalonamento: quem faz o quê e quando

Um runbook só funciona quando nomeia quem é responsável. “Owner” deve ser um papel (não apenas uma pessoa) que esteja de plantão ou seja responsável pelo serviço. Adicione um dono reserva para quando o principal estiver dormindo, em férias ou já lidando com outro incidente.

Defina também quem pode aprovar ações arriscadas. Diga o que “arriscado” significa para sua equipe: qualquer coisa que possa causar perda de dados, downtime, exposição de segurança ou bloqueio de clientes. Exemplos: reverter uma migração de banco, rotacionar segredos de autenticação, desabilitar um controle de segurança ou rodar um script destrutivo.

Escreva quando chamar no pager e quando escalar. Regras vagas como “page se estiver ruim” criam atrasos.

• Page imediatamente se erros de login excederem X% por Y minutos, ou se um endpoint chave estiver retornando 5xx.
• Page se qualquer problema que impacte clientes durar mais que Z minutos sem um caminho confirmado para recuperação.
• Page segurança imediatamente se suspeitar de segredos expostos, acesso administrativo inesperado ou possível injeção.
• Escale se o conserto requerer uma aprovação que você não tem.
• Escale se você não conseguir verificar melhora após uma mitigação segura.

Então liste a ordem de escalonamento para que ninguém debata isso no meio do incidente:

• On-call primário
• On-call reserva
• Tech lead do serviço
• Segurança (se autenticação, segredos ou tráfego suspeito estiverem envolvidos)
• Suporte do fornecedor (nuvem, pagamentos, email) quando evidências apontarem fora do seu código

Adicione uma nota curta para times de suporte: uma ou duas frases para dizer aos usuários, e o que não prometer. Exemplo: “Estamos investigando falhas de login e trabalhando em um conserto. Seus dados estão seguros. Próxima atualização em 30 minutos.”

Cheques de verificação: como confirmar que o conserto realmente funcionou

Um conserto não é real até que você possa provar. Cheques de verificação são medições pequenas e repetíveis que você roda logo após a mudança para confirmar que o sistema está saudável novamente.

Case os cheques com o que os usuários experimentaram. Se o problema foram falhas de login, não pare em “erros diminuíram”. Confirme que as pessoas realmente conseguem logar e que a taxa de erro e a saúde do serviço de auth voltaram ao normal.

Mantenha simples: um smoke test + algumas métricas

Tenha um smoke test que qualquer pessoa de plantão saiba rodar, mais 2 a 3 sinais do monitoramento:

• Smoke test (fluxo do usuário): faça uma ação real de ponta a ponta (login, criar um registro, finalizar um checkout de teste) e defina o que significa “sucesso”.
• Métricas chave: escolha algumas que devem se mover imediatamente (taxa de 5xx, falhas de auth, profundidade de fila, latência p95, logs de erro para o endpoint específico).
• Checagens de sistema: confirme que dependências estão saudáveis (conexões de banco, taxa de acerto de cache, status de terceiros se envolvidos).
• Teste de regressão: repita a ação que desencadeou o incidente (mesma rota, mesmo formato de payload, mesmo estado de feature flags).
• Guardrails: confirme que nenhum segredo ou configuração de debug foi exposto durante o conserto.

Se o conserto foi um rollback, acrescente verificação de rollback também: confirme que a versão X está ativa em produção, que o endpoint com falha retorna 200 e que a taxa de erro retornou ao baseline.

Defina uma janela de monitoramento e uma linha clara de “pronto”

Após o conserto, monitore os gráficos e logs certos por 15 a 60 minutos. Escreva o que você espera que se mantenha estável e qual limite significa que o problema voltou.

Termine com uma única linha “pronto”, por exemplo: “Pronto quando o smoke test passar duas vezes, taxa de erro ficar abaixo de 1% por 30 minutos e nenhum alerta relacionado reaparecer.” Depois documente:

• o que mudou (commit, config, flag, deploy ou rollback)
• quais cheques você rodou e os resultados
• o que fará da próxima vez para detectar mais cedo

Seção de comandos: torne o copy-paste seguro e previsível

A forma mais rápida de transformar um runbook em uma ferramenta real (não um doc que ninguém confia) é tornar comandos seguros para copiar e difíceis de usar errado. Trate o bloco de comandos como um mini produto: entradas claras, saídas claras, avisos claros.

Comece com comandos somente leitura. Coloque comandos de escrita (reinícios, mudanças de config, migrações) depois, com um aviso de uma linha acima.

Um padrão que funciona bem:

• Use placeholders como <service>, <env>, <region>, <user_id>, <incident_id> e mostre um exemplo “conhecido bom” preenchido.
• Adicione comandos “NÃO RODE” quando as pessoas costumam usá-los sob estresse.
• Declare permissões requeridas no começo (nome do papel, acesso ao sistema e se acesso de escrita em prod é necessário).
• Exija um registro de mudanças: hora, comando exato, resultado e o ticket/ID do incidente.
• Diga o que significa “sucesso” para cada comando (saída esperada ou um número que deve mudar).

# Read-only checks (safe)
export ENV=<prod|staging>
export SERVICE=<api>

# Confirm current deploy + error rate
kubectl -n $ENV get deploy $SERVICE
kubectl -n $ENV logs deploy/$SERVICE --since=10m | tail -n 50

# Known good example
# ENV=prod SERVICE=auth-api

# Write actions (DANGER: prod impact)
# Only run with <role_name> and after confirming incident <incident_id>
# Log: <time> <command> <result> <incident_id>

# DO NOT RUN: resets all sessions (use only with approval)
# redis-cli -h <host> FLUSHALL

Se você herdou comandos de deploy confusos ou scripts de ops gerados por IA, faça-os revisar antes de virarem “padrão”. Pequenos erros (namespace errado, wildcard perigoso, falta de confirmação) podem gerar incidentes repetidos.

Erros comuns que tornam runbooks inúteis

Runbooks falham sob pressão por alguns motivos previsíveis, e a maioria tem a ver com clareza.

A primeira armadilha é responsabilidade. Um runbook que diz “alguém do backend deve checar os logs” será ignorado às 2 a.m. Todo problema recorrente precisa de um dono nomeado (papel ou pessoa) e um caminho de escalonamento claro.

Outro fracasso comum é conhecimento oculto. Passos que dependem da “senha de sempre”, de um dashboard privado ou de uma chave SSH única não são passos, são esperanças. Se o acesso é sensível, diga onde as credenciais estão guardadas e quais permissões mínimas são necessárias. Se o acesso não estiver disponível durante um incidente, diga isso e aponte para o fallback.

Verifique estes problemas antes de publicar:

• Sem dono ou contato on-call
• Passos que presumem conhecimento tribal, como onde os logs ficam ou qual ambiente é “o real”
• Sem checagens de verificação, então o sintoma some brevemente e volta
• Comandos que mudaram após alterações na infra (serviços renomeados, novas regiões, ferramenta de deploy diferente)
• “Consertos” que são arriscados ou vagos, como “reinicie tudo” ou “mude config com cuidado”

A verificação é a parte que as pessoas pulam, e é justamente a que evita novos pages. Após cada conserto, inclua provas rápidas como “login funciona para um usuário de teste”, “taxa de erro cai abaixo de X” e “nenhum novo 5xx por 10 minutos”.

Por fim, escreva de forma à prova de estresse. Se um passo pode causar dano, detalhe limites seguros e um rollback.

Exemplo de runbook: falhas recorrentes de login após um deploy

Este runbook de exemplo cobre um padrão comum: logins quebram logo após um deploy.

Cenário: 5 a 10 minutos após o deploy, usuários relatam que não conseguem entrar. O site carrega, mas o botão de login gira e depois mostra “Algo deu errado.”

Sinal de alerta: taxa de erro da API para /auth/login sobe de <1% para 20%+. Tickets de suporte mencionam “senha correta, mesmo assim falha.”

Responsáveis: engenheiro de plantão (primário), release captain (aprovador para rollback), líder de suporte (comunicação com usuários).

Triagem e diagnóstico

Confirme escopo e a mudança mais recente antes de tentar consertos.

• Confirme impacto: novos usuários, usuários existentes ou ambos? Uma região ou todas?
• Verifique último deploy: o que mudou em auth, config, env vars ou migrações de banco?
• Inspecione logs pelo primeiro erro após o tempo do deploy (procure 401 vs 500, env var faltando, erros de assinatura de token).
• Cheque dependências: provedor de identidade, banco, cache, status do serviço de email.

Passos de mitigação (escolha a ação mais segura que se aplica)

Use a ação menos disruptiva primeiro e pare assim que o sistema se recuperar.

• Desative a feature flag relacionada ao login (se disponível) para direcionar o tráfego ao caminho anterior.
• Reverta a configuração de auth para a última versão conhecida boa (comum: callback URL, segredo JWT, domínio do cookie).
• Reinicie o serviço de auth para carregar a configuração corrigida (apenas após verificar que os segredos estão presentes).
• Reverter para o deploy anterior se os erros persistirem após reverter a config.

Cheques de verificação

Confirme tanto a experiência do usuário quanto as métricas.

• Complete um fluxo real de login (usuário de teste) e confirme que uma sessão é criada.
• A taxa de erro retorna ao baseline por 10 a 15 minutos e não surgem novos picos nos logs.

Após o incidente, atualize o runbook com o padrão exato de log, a chave de configuração que causou a quebra, a regra de decisão para rollback e um checklist pré-deploy (por exemplo: “validar que env vars de auth requeridas existem em produção”).

Próximos passos: mantenha runbooks atualizados e reduza incidentes recorrentes

Um runbook só economiza tempo se refletir como o sistema funciona hoje. A maneira mais rápida de ter docs desatualizados é tratar um runbook como “pronto” depois de escrito uma vez.

Após cada incidente, reserve 10 minutos enquanto os detalhes estão frescos e faça pequenas edições: ajuste a descrição do sintoma, adicione a linha de log que faltou e capture qualquer novidade do conserto.

Antes de fechar o ticket, faça uma checagem rápida de usabilidade:

• Cabeçalho completo (serviço, ambiente, última atualização, riscos conhecidos)
• Responsáveis e caminho de escalonamento definidos (e ainda precisos)
• Passos testados recentemente (não apenas escritos)
• Cheques de verificação definidos (o que significa sucesso)
• Comandos seguros para copiar e colar (específicos, reversíveis e documentados)

Defina uma cadência simples de revisão. Mensal funciona para equipes ocupadas, mas gatilhos melhores são “após cada incidente” e “após cada refatoração ou atualização de dependência” para os serviços que mais quebram.

Se você notar as mesmas falhas reaparecendo após todo deploy, pode não ser um problema do runbook. Pode ser um problema de código, especialmente em apps gerados por ferramentas de IA onde autenticação, segredos e arquitetura parecem ok em demos mas falham em produção.

Se você estiver herdando um app gerado por IA e ficar sempre apagando incêndios, FixMyMess (fixmymess.ai) foca em diagnosticar e reparar essas bases: reparo de lógica, endurecimento de segurança, refatoração e preparação de deploy. Uma auditoria curta pode transformar correções tribais em mudanças estáveis e gerar runbooks que batem com o comportamento real do sistema.