Runbooks

«Алерт без runbook — фоновый шум» — это фраза, которую я повторяю чаще всего на ревью алертов. Сам runbook — это не идея «давайте напишем инструкции», это конкретный документ с конкретными командами, выводами и решениями. Если в три ночи дежурный получит pager и откроет ваш runbook — он либо найдёт там команду для копирования, либо обнаружит эссе. Лист про разницу.

Что должен уметь

Главный навык на уровне L4 — писать runbook так, чтобы по нему мог пройти новый дежурный без контекста. Если на каждом шаге дежурный должен «вспомнить архитектуру сервиса», «понять, что имел в виду автор», «решить, какой dashboard смотреть» — runbook сломан. Хороший runbook — это серия конкретных команд и явных решений «если видишь X, переходи к шагу N; если Y — к шагу M».

Использует существующие runbook’и команды для реагирования на инциденты; следует шагам, не выходит за их пределы без эскалации.
Сообщает владельцу runbook о найденной неточности или устаревшем шаге сразу после использования (не «потом, на ревью»).

Пишет runbook для известного типа инцидента: симптом → шаги диагностики → шаги mitigation → как откатить → escalation. Обновляет runbook после новых инцидентов.
Следует шаблону команды и проверяет actionable-критерий: каждый шаг — конкретная команда или явное решение; не «понять и подумать».

Строит культуру runbook-first: алерт без runbook в команде не принимается. Проводит аудит runbook’ов на актуальность по расписанию.
Тестирует runbook’и в game day / wheel of misfortune; не доверяет ни одному runbook, которым никто не проходил по факту.
Встраивает ссылку на runbook прямо в алерт (например, через runbook_url annotation в Prometheus AlertRule или поле runbook в Alertmanager).

L6+

Внедряет runbook-систему: платформа, шаблоны, метрики использования, автоматическая связь с alert-системой.
Держит SLO для самого runbook-репозитория (например, «≥ 95% алертов имеют ссылку на актуальный runbook»); отслеживает деградацию покрытия.

Материалы

Книги

Betsy Beyer et al. — Site Reliability Engineering (O’Reilly, 2016), глава 11 «Being On-Call». Раздел «Documenting» — фундамент runbook-культуры.
Betsy Beyer et al. — The Site Reliability Workbook (O’Reilly, 2018), глава 8 «On-Call». Продолжение: playbook содержит severity, impact, debugging suggestions, mitigation. Утверждение «каждый алерт получает playbook» как норма.

Статьи и доклады

PagerDuty — Incident Response Documentation. Публичный guide по incident response; даёт референс формата runbook («Being On-Call → Before / During / After»). По моим наблюдениям, многие команды берут именно его как стартовый шаблон.

Инструменты

Markdown в репозитории команды — самый простой и работающий формат. Один runbook = один файл; PR-based review; история через git. Я вижу, что большинство зрелых команд так и живёт — отдельная платформа избыточна для большинства случаев.
Rundeck — open-source платформа для исполняемых runbook’ов (job runner + access control + audit). Имеет смысл, когда часть шагов автоматизируется и нужно фиксировать исполнение.
StackStorm — event-driven automation platform; runbook как сценарий, запускаемый по триггеру. Альтернатива Rundeck для команд, у которых уже есть event-bus.
Prometheus AlertRule runbook_url annotation — стандартный паттерн: каждому алерту в prometheus.yml прописывается ссылка на runbook. Alertmanager пробрасывает её в нотификацию (Slack/Pager).

Best practices

Я регулярно встречаю команды, у которых 200+ active алертов в Prometheus, из них 70–80% либо без runbook, либо с устаревшим runbook (ссылки на несуществующие сервисы, deprecated команды, dashboard URL → 404). Каждый алерт на смене — «разбуди и пусть гадает»: инженер ack’ает, копает 10–30 минут, в большинстве случаев alert оказывается шумом, runbook не пишется «до следующего раза». MTTR на алерт на такой смене — десятки минут. После систематической работы (правило «или runbook, или удаляем алерт») цифра падает в несколько раз — но это требует именно работы, не «найти время».

Короткие правила:

Runbook = детальные шаги, не нарратив. Если для исполнения шага нужно «знать архитектуру» или «вспомнить контекст», runbook сломан — on-call в три ночи не должен думать, он должен следовать.
Каждый шаг — actionable + критерий проверки. Шаг «проверить логи» без указания где, какие, что искать — бесполезен. Правильно: «выполни kubectl logs -n prod app-foo --tail=200 | grep ERROR; если видишь connection refused — переходи к шагу 3, иначе к шагу 5».
Шаг «как откатить безопасно» — обязательный. Каждое изменяющее действие сопровождается откатным шагом и критерием «откатывать ли». Без этого runbook ведёт mitigation вперёд, но не описывает, что делать, если mitigation сделал хуже.

Подробнее:

Привязка к симптому, а не к причине. Дежурный не видит «база упала» — он видит «p99 latency > 500ms» или «5xx rate > 1%». Если runbook называется «падение базы», а дежурный смотрит на p99 latency — он не свяжет это с runbook, потеряет 15 минут на ориентацию. Runbook называется по симптому, который видит дежурный (имя алерта). Симптомов мало, причин много; от симптома runbook ведёт к диагностике причин.

Регулярный аудит и владелец. Устаревший runbook хуже его отсутствия — он даёт ложное чувство уверенности и ведёт не туда. Я встречаю это часто: runbook ссылается на dashboard URL, который пере-namespace’или год назад; на скрипт в репо, который удалили; на on-call ротацию команды, которая расформировалась. Установите периодичность пересмотра (квартал/полугодие) и владельца, отвечающего за актуальность. После каждого инцидента — обязательное обновление того runbook, который использовался.

Тестирование в game day. Runbook, написанный год назад и положенный в wiki, в момент инцидента может оказаться неработоспособным: команда не работает, шаги ведут не туда, dashboard уже другой. Регулярные game day (wheel of misfortune, прогон сценария из прошлого постмортема) выявляют гнильё без боевой обстановки. Без тестирования runbook — обещание, а не инструмент.

Связанные листья

SLI-based Alerting — обязательная пара: каждый SLO-алерт ведёт к runbook; алерт без runbook удаляется как фоновый шум.
Incident Response — runbook — главный инструмент в моменте инцидента; качество runbook прямо определяет MTTR.
Postmortem Culture — каждый постмортем порождает обновление runbook (новый или правки существующего); без обновления lesson learned не закреплён.
Dev Team Partnership — co-ownership: runbook’и пишутся совместно с product-командой; иначе SRE дежурит вслепую по чужому сервису.
Toil Automation — automatable runbook steps мигрируют в automation; «runbook говорит сделать X — пусть делает скрипт» как естественный следующий шаг.
Playbooks — runbook отвечает «как делать», playbook — «что решать и кого звать». Runbook’и встраиваются в playbook’и как ссылки на конкретные шаги; разделение явное.

Открытые вопросы

Я не знаю хорошего ответа на «когда runbook превращается в automated remediation». В тривиальных случаях — alert + 3-step runbook → Lambda или k8s operator. В нетривиальных — runbook содержит ветвление по контексту, и автоматизация рискует выстрелить в ногу при первом edge-case. Граница «можно автоматизировать» / «надо оставить человеческое решение» в публичной литературе чёткой не вижу. Если есть опыт — расскажите PR’ом.