Runbook design checklist

Действуй как опытный SRE. Спроектируй runbook для алерта {{alert_name}} по сервису {{service_name}}. Цель — runbook должен быть таким, чтобы дежурный в 3 ночи открыл его, выполнил шаги, починил, и пошёл досыпать. Без runbook'а alert — это «иди разбирайся сам».

Структура runbook'а (обязательные секции)

1. Trigger

• Alert name: {{alert_name}} (точное имя из alerting system).
• Что триггерит: условие (метрика, threshold, hysteresis). Пример: p99 latency > 1s for 5 min.
• Источник: какой dashboard / какая alert rule. Прямые ссылки.
• Owner team: кто owns этот сервис (не для эскалации, для контекста).

2. Severity criteria

• Default severity: SEV{N}.
• Когда повышать: «если customer-facing flow X тоже affected → SEV1». Чёткие критерии, не «по ощущению».
• Когда понижать: «если только 1 region и есть fallback → SEV3».
• Customer-facing impact: да/нет/частично. От этого зависит, нужен ли status page update.

3. First response (первые 5 команд)

Самое важное. Дежурный в 3 ночи не помнит, что делать. Дай ему готовый copy-paste.

# 1. Подтвердить, что symptom реален (не page noise)
kubectl get pods -n {{service_name}} | grep -v Running

# 2. Посмотреть recent deploys (40% инцидентов = последний deploy)
kubectl rollout history deployment/{{service_name}} -n {{service_name}}

# 3. Посмотреть error logs за последние 5 минут
kubectl logs -n {{service_name}} -l app={{service_name}} --tail=200 --since=5m | grep -i error

# 4. Открыть дашборд (ссылка должна быть real)
# https://grafana.example.com/d/{{service_name}}

# 5. Проверить downstream dependencies
curl -sS https://status.{provider}.com | jq '.status'

После этих 5 команд должно быть ясно: симптом реален? недавний deploy виноват? зависимость лежит?

4. Diagnosis tree

Дерево решений, не wall of text. Каждая ветка — actionable.

Was there a deploy in last 30 min?
├── YES → Go to "Mitigation: Rollback"
└── NO  → Continue

Downstream dependency status: down?
├── YES → Go to "Mitigation: Failover" (and notify dep owner)
└── NO  → Continue

Error logs show OOM / disk full?
├── YES → Go to "Mitigation: Scale"
└── NO  → Continue

Error logs show DB connection refused?
├── YES → Go to "Mitigation: DB issue" (escalate to DB team)
└── NO  → Escalate to service owner — outside known patterns

5. Mitigation steps

Для каждой возможной mitigation — конкретные команды, не «откатить деплой».

Rollback:

# Откатить deploy на предыдущую версию
kubectl rollout undo deployment/{{service_name}} -n {{service_name}}

# Проверить статус rollout
kubectl rollout status deployment/{{service_name}} -n {{service_name}}

# Verify: error rate должен упасть в течение 2-3 минут на дашборде

Scale:

# Увеличить replicas
kubectl scale deployment/{{service_name}} -n {{service_name}} --replicas=10

# HPA проверить (если автоскейл стоит — может быть max hit)
kubectl get hpa -n {{service_name}}

Feature flag off:

# Через CLI (зависит от вашей системы flags)
flag-cli set feature.{{service_name}}.{feature_name} false --env=prod --reason="incident-{{alert_name}}"

6. Escalation

• Когда эскалировать: если 15 минут после первых 5 команд + diagnosis tree без улучшения.
• К кому (по тирам):
  • L2 (service owner / on-call senior): @handle, phone, secondary phone.
  • L3 (engineering manager): @handle, phone.
  • L4 (director / VP): только если SEV1 > 1 час.
• Как: PagerDuty escalation OR ручной call (телефон, не Slack — в 3 ночи Slack игнорят).
• Что говорить при эскалации: 3 строки — что (symptom), что попробовали (actions), что текущий статус (impact).

7. Verification (как понять, что починили)

Самая забываемая секция. «Я что-то сделал и графики выглядят лучше» — это не verification.

• Метрики: {primary metric} должен быть в baseline range {X-Y} на протяжении 15+ минут непрерывно. Не «увидел один зелёный спайк → resolved».
• Synthetic check: прогнать smoke test (если есть). Пример: curl -sS https://api.example.com/health → 200.
• End-to-end: один реальный user flow — login → core action → logout. Через UI или scripted check.
• Logs: error log volume вернулся к baseline за последние 15 минут.
• Если customer-facing: проверить, что нет новых support tickets за 10 минут.

8. Что НЕ делать (anti-patterns в этом runbook'е)

• ❌ Не делай rollback, если deploy был > 2 часа назад — скорее всего, не он причина, и откат внесёт новый риск.
• ❌ Не рестартуй DB pods наобум — может ухудшить (если master, потеряем writes).
• ❌ Не меняй конфиг production через kubectl edit без PR — нет audit trail, не воспроизведёшь.
• ❌ Не закрывай инцидент после одного зелёного спайка — нужно 15 мин стабильности.
• ❌ Не пиши «починил» в Slack, пока не verify по чеклисту в секции 7.

9. Related runbooks / postmortems

• Похожие алерты: {alert-name-X}, {alert-name-Y}.
• Past incidents с этим runbook: ссылки на post-mortems (для контекста, известных gotchas).

Anti-patterns в дизайне runbook'ов

• ❌ Runbook в Confluence — никто не находит в 3 ночи. Держи в репозитории сервиса (markdown), ссылка в alert payload.
• ❌ Wall of text без шагов — дежурный читает 5 минут, паникует, дёргает manager'а.
• ❌ «Run the standard procedure» — какую? где? Без ссылок runbook бесполезен.
• ❌ Команды без kubectl get ... примеров — копировать неоткуда, печатать в 3 ночи с опечатками.
• ❌ Runbook не обновляется после incident'а — устаревшие команды, fail при попытке использовать.
• ❌ Один runbook на 10 разных alerts — теряется фокус. Один alert = один runbook (можно линковать общие куски).
• ❌ Verification «выглядит нормально» вместо чеклиста — incident reopens через 30 минут.

Format чеклист (перед публикацией)

• First 5 commands есть и они copy-paste ready
• Diagnosis tree — не больше 5 уровней
• Каждая mitigation — с командами
• Escalation: имена + телефоны (не только handle)
• Verification — конкретный чеклист, не «должно быть лучше»
• «Что НЕ делать» секция есть
• Runbook лежит в репозитории сервиса, не в Confluence
• Ссылка на runbook есть в alert payload (auto-generated)
• Runbook прогоняли last drill / last incident — работает

Принцип: runbook — это «calmness in a doc». Хороший runbook убирает stress, плохой добавляет.