Do alerta a resolução: construindo runbooks vivos com automação na prática

Mito 1: "Runbook é só documentação, então colocamos no wiki e está resolvido"

A crença de que runbook é sinônimo de documento está na raiz de 80% dos fracassos de incident response que já presenciei. Um PDF ou página de wiki com passos descritos em linguagem natural não é um runbook: é um manual de instruções para situações de calmaria. Em produção, às 2h da manhã, com 50 mil usuários afetados, você não quer ler, quer agir.

Realidade: Runbook é código executável. Um runbook vivo é um script ou automação que pode ser disparado por um alerta, executado via ChatOps, ou invoked programaticamente por um sistema de incident management. O procedimento está codificado, versionado, testado e pronto para execução repetível.

A diferença prática é brutal. Considere um cenário real: database de réplica com atraso de replicação superior a 30 segundos.

Abordagem tradicional (wiki):

1. Verificar latência de rede entre dbprimary e dbreplica
2. Checar utilização de IOPS no primary
3. Se problema persistir, reiniciar o serviço de replicação
4. Ligar para o DBA de plantão

Abordagem com runbook automatizado:

#!/usr/bin/env bash
# runbook/replicationlagrecovery.sh

set euo pipefail
REPLICA_HOST="${REPLICA_HOST:?}"
THRESHOLD_SECONDS=30

# Step 1: Diagnóstico automático
current_lag=$(mysql h "$REPLICA_HOST" e "SELECT MAX(ABS(TIMESTAMPDIFF(SECOND, NOW(), Read_Master_Log_Pos))) as lag FROM slave_master_info();" N)
echo "Lag atual: ${current_lag}s"

# Step 2: Verificação de conectividade
if ! mysql h "$REPLICA_HOST" e "SELECT 1" >/dev/null 2>&1; then
  echo "ERRO: Réplica inacessível"
  # Dispara escalação automática
  opsgenie alerts create message "Réplica $REPLICA_HOST inacessível" tags "runbook,autoescalation"
  exit 1
fi

# Step 3: Se lag > threshold, tenta recuperação
if [ "$current_lag" gt "$THRESHOLD_SECONDS" ]; then
  echo "Lag acima do threshold. Tentando STOP SLAVE; START SLAVE;"
  mysql h "$REPLICA_HOST" e "STOP SLAVE; START SLAVE;"
  sleep 5
  new_lag=$(mysql h "$REPLICA_HOST" e "SELECT MAX(ABS(TIMESTAMPDIFF(SECOND, NOW(), Read_Master_Log_Pos))) as lag FROM slave_master_info();" N)
  echo "Lag após recuperação: ${new_lag}s"
fi

O segundo bloco não é documentação sobre o que fazer: é o que fazer, pronto para ser executado por qualquer pessoa, a qualquer hora, sem depender de interpretação.

flowchart LR
    subgraph Tradicional["🕐 Abordagem Tradicional (MTTR: 45min+)"]
        A1[Alerta] --> A2[Buscar no Wiki]
        A2 --> A3[Ler Documentação]
        A3 --> A4[Executar Manualmente]
        A4 --> A5{Funciona?}
        A5 -->|Não| A6[Iterar Debug]
        A6 --> A4
        A5 -->|Sim| A7[Resolvido]
    end
    subgraph Automatizado["⚡ Runbook Automatizado (MTTR: 3min)"]
        B1[Alerta] --> B2[Disparar Automação]
        B2 --> B3[Executar Passos Predefinidos]
        B3 --> B4[Resolvido]
    end
    style A1 fill:#ff6b6b,color:#fff
    style B1 fill:#51cf66,color:#fff
    style A7 fill:#ff8787,color:#fff
    style B4 fill:#69db7c,color:#fff

Mito 2: "Automação de runbook é luxo de empresa grande. Nossa equipe pequena não precisa"

teams pequenas frequentemente rationalizam a omissão de práticas de SRE maduras por não terem "escala suficiente". Esse raciocínio inverte a lógica correta. Quanto menor a equipe, maior a dependência de cada indivíduo e menor a capacidade de absorver erros evitáveis.

Realidade: Automação de runbook tem ROI imediato em qualquer escala. Os custos são menores do que você imagina: um script shell, um workflow de Ansible, ou um playbook de Rundeck resolve a maioria dos casos. Ferramentas como o Cloudflare Workers, scripts serverless, ou até GitHub Actions com triggers de incident management são opções viáveis com custo marginal zero para a maioria dos times.

O cálculo que você deve fazer é simples:

Um único incidente de severidade alta que você poderia ter resolvido em 10 minutos, mas que custou 2 horas por falta de automação, frequentemente tem impacto financeiro superior a meses de investimento em runbook automation.

Mito 3: "Alerta inteligente substitui a necessidade de runbooks"

Este mito é particularmente perigoso porque vem de uma confusão entre detecção e resposta. Ferramentas de AIOps e alerting avançado são excelentes para identificar anomalias, correlacionar eventos e reduzir ruído. O que elas não fazem é executar a correção.

Realidade: Alertamento e runbook são ortogonais. Um alerta diz que algo está errado. Um runbook diz o que fazer sobre isso. Você pode ter o sistema de monitoramento mais sofisticado do mundo e, sem automação de resposta, ainda vai depender de humanos para interpretar e agir.

A tendência de autohealing (autoresolução de problemas) é real e valiosa, mas tem limites claros:

Pode fazer: Reiniciar um processo, limpar cache, escalar instâncias, pausar um job travado Não pode fazer: Tomar decisão de rollback de migration, avaliar impacto de negócio, comunicar stakeholders, decidir sobre escalation para equipe de produto

O runbook automatizado bem projetado conhece esses limites e inclui pontos de decisão humana com gates claros.

Mito 4: "Levamos tempo demais para criar runbooks, então não vale o esforço"

O argumento de que runbooks são custosos de manter é verdadeiro quando você os trata como documentos. É falso quando você os treata como código.

Realidade: Runbooks seguem o mesmo ciclo de vida que código de produção e recebem os mesmos benefícios: CI/CD, testes automatizados, code review, versionamento, e rollback.

# .github/workflows/runbooktests.yml
name: Runbook Smoke Tests
on:
  push:
    paths:
       'runbooks/**'
       'runbooks/**/*.sh'

jobs:
  test:
    runson: ubuntulatest
    steps:
       uses: actions/checkout@v4
       name: Validar sintaxe de todos os runbooks
        run: |
          for script in runbooks/**/*.sh; do
            bash n "$script" || exit 1
          done
       name: Testar runbooks com dryrun
        env:
          DRY_RUN: "true"
        run: |
          # Testa lógica sem executar em produção
          ./runbooks/replicationlagrecovery.sh dryrun

O custo real de não ter runbook automatizado é pago em horas de engenharia durante incidentes, em burnout de oncall, e em erros de execução sob pressão que causam incidentes secundários.

Mito 5: "Uma vez criado, o runbook está pronto para sempre"

Runbooks estáticos são um antipattern. Em produção, sua infraestrutura, serviços e dependências mudam constantemente. Um runbook criado há 6 meses provavelmente referencia IPs que não existem mais, APIs que mudaram de endpoint, ou flags de configuração que foram removidas.

Realidade: Runbooks são artefatos vivos que devem ser tratados como firstclass citizens do seu codebase. Isso significa:

Testes automatizados validam que o runbook ainda funciona após mudanças de infraestrutura Alertas de staleness identificam runbooks não executados em X meses Métricas de uso mostram quais runbooks foram disparados e quantas vezes Revisões periódicas (trimestrais ou após cada uso) garantem relevância ** ownership claro**: cada runbook tem um dono responsável pela sua manutenção

# stale_runbook_detector.py
from datetime import datetime, timedelta
from dataclasses import dataclass

@dataclass
class Runbook:
    path: str
    last_modified: datetime
    last_executed: datetime | None
    owner: str

def check_staleness(runbook: Runbook, max_days: int = 90) > bool:
    is_modified_stale = (datetime.now()  runbook.last_modified).days > max_days
    never_executed = runbook.last_executed is None
    # Flag se nunca executado ou não modificado após mudança de infra
    return never_executed or is_modified_stale

A decisão técnica: do alerta a resolução em 3 camadas

A arquitetura de runbook automation madura opera em três camadas:

1. Detecção (observabilidade): PagerDuty, OpsGenie, ou equivalente + alertas bem calibrados com SLOs
2. Orquestração (runbook engine): Ferramenta que executa os runbooks: Rundeck, Ansible Tower, ou custom (Python/Go com handlers de evento)
3. Execução (automação): Scripts idempotentes, testes, e integração com infraestrutura (Terraform, Kubernetes, APIs de cloud)

A integração entre essas camadas é o que transforma um alerta em uma resolução automática. Quando você dispara um alerta de "disk usage > 90% on prodapi03", o runbook não deveria esperar que alguém lesse o alerta e executasse passos manuais. O runbook deveria:

1. Identificar qual volume está cheio
2. Listar os maiores arquivos nos últimos 7 dias
3. Se menemukan arquivos de log antigos, fazer rotação
4. Se o problema persistir, expandir o volume automaticamente (com guardrails de custo)
5. Notificar o canal de #infraops com resumo da ação tomada

Esse fluxo, executado em 30 segundos, é o que separa equipes de SRE maduras de equipes que ainda estão firefightering manualmente.

Conclusão: runbook que não executa é só ficção

A armadilha fundamental é tratar runbook como deliverable de documentação. Se o procedimento não pode ser executado por qualquer pessoa de plantão, às 3h da manhã, sem precisar ligar para o autor original, então você não tem um runbook: tem um desejo.

A decisão técnica é clara: invista em automação de runbook para seus top 5 incidentes mais frequentes. Meça o MTTR antes e depois. Comprove o ROI. Expanda gradualmente. Em 6 meses, você terá uma biblioteca de runbooks vivos que transforma seu oncall de evento estressante em processo repetível e confiável.

A diferença entre uma equipe que sobrevive a incidentes e uma que os resolve está em uma pergunta: seu runbook executa, ou só documenta?

Se sua equipe ainda executa procedimentos manuais em incidentes críticos, podemos mostrar como automatizar os runbooks mais críticos em 30 dias. Sem compromisso.

Fale com um especialista da Eficify