Runbook / Operations Manual

# Runbook — [Nome do serviço]

**Owner team:** [time responsável]
**On-call rotation:** [link para PagerDuty/OpsGenie]
**Última atualização:** [YYYY-MM-DD] por [autor]
**Service tier:** Tier 1 (mission critical) / Tier 2 / Tier 3

---

## TL;DR para o on-call
- **O que esse serviço faz:** [1 frase]
- **Dependências críticas:** [banco X, fila Y, API externa Z]
- **Dashboard principal:** [link Grafana/Datadog]
- **Logs:** [link Loki/Splunk com filtro pré-aplicado]
- **Traces:** [link Jaeger/Tempo]
- **Repo:** [link GitHub/GitLab]

## Arquitetura em 1 minuto
[Diagrama simples — request entra aqui, passa por X, sai por Y]

## SLOs
| Métrica | SLO | Janela | Error Budget |
|---------|-----|--------|--------------|
| Disponibilidade | 99.9% | 30 dias | ~43 min |
| Latência P99 | < 200 ms | 30 dias | 1% das requests |
| Taxa de erro | < 0.1% | 30 dias | 1 em mil |

---

## Alertas comuns

### 🔴 [Alerta: HighErrorRate]
**Severidade:** Crítica · página o on-call

**O que significa:** taxa de erro 5xx acima de 1% por > 5 min.

**Diagnóstico em ordem:**
1. Olhe o dashboard "Errors by endpoint" — qual endpoint?
2. Olhe os traces de erro recentes — qual stack trace?
3. Banco está saudável? (link para dashboard banco)
4. Dependência externa caiu? (status page de Stripe, etc.)
5. Deploy recente? (ver últimos N deploys)

**Mitigações típicas:**
- Se foi deploy recente: rollback imediato
  - Comando: \`kubectl rollout undo deployment/api-service\`
- Se dependência externa: ativar feature flag de degradation
  - Comando: \`./scripts/feature-flag set degraded_mode true\`
- Se banco: verificar slow queries; pode precisar restart
  - **Antes** de restart: ver o que tem em vôo

**Quando escalar:**
- Se mitigation acima não resolve em 15 min → escalar para tech lead
- Se afeta >10% dos usuários e não há mitigation óbvia → escalar
  para incident commander

### 🟡 [Alerta: HighLatency]
[Mesma estrutura. Severidade: Warning. Não página, mas notifica.]

### 🟡 [Alerta: HighMemoryUsage]
[...]

### 🔴 [Alerta: ServiceDown]
[...]

[Repetir para todos os alertas configurados.]

---

## Operações comuns

### Deploy de emergência (hotfix)
```bash
# 1. Branch da última tag
git checkout v2.4.1
git checkout -b hotfix/issue-1234

# 2. Cherry-pick ou commit do fix
git cherry-pick <sha>

# 3. Deploy direto via pipeline
gh workflow run deploy.yml -f env=production -f tag=v2.4.2-hotfix
```

### Rollback
```bash
kubectl rollout undo deployment/api-service -n production
# verificar com:
kubectl rollout status deployment/api-service -n production
```

### Restart graceful (se necessário)
```bash
kubectl rollout restart deployment/api-service -n production
```

### Limpar cache em massa
```bash
# CUIDADO: vai afetar latência por 1-2 minutos
./scripts/cache-purge.sh --confirm
```

### Acessar shell em produção (read-only)
```bash
kubectl exec -it $(kubectl get pod -l app=api-service -o name | head -1) -- /bin/sh
```

---

## Capacity & scaling

### Quando escalar (manual)
- Se sustentar >80% CPU por >30 min: scale up
- Se autoscaler atinge max e ainda não basta: aumentar max

### Limites conhecidos
- **API:** sustenta ~5000 RPS antes do banco saturar
- **Worker:** processa ~500 jobs/s (limite de IO)
- **Banco:** read replicas têm lag > 5s acima de 80% CPU

---

## Contatos
- **Tech lead:** [@person] (slack), [phone]
- **Eng manager:** [@person]
- **Skip:** [escalation manager]
- **Security on-call:** #security-incidents (slack)
- **Customer on-call:** #cs-priority (slack)

## Recursos externos
- [Status page do provedor X]
- [Health check pública]
- [Painel de incident para incident commander]