Шаблон runbook для повторяющихся проблем в продакшене

Что такое runbook и почему для повторяющихся проблем он нужен

Runbook — это короткая, практичная последовательность инструкций, которая помогает кому‑то исправить известную проблему в продакшене одинаково каждый раз. Он превращает племенные знания ("попробуй перезапустить" или "посмотри логи") в чёткие шаги с командами, ответственными и проверками, которые подтверждают, что система снова здорова.

Runbook — это не постмортем. Постмортем объясняет, что случилось, почему это случилось и что вы измените, чтобы этого больше не повторилось. Runbook используют во время инцидента, когда времени мало и нужны безопасные, повторяемые действия.

Runbook особенно полезен, когда проблемы повторяются. Например: один и тот же алерт срабатывает каждую неделю (скачок CPU, накопление очереди, упавший cron), саппорт получает одинаковые обращения пользователей ("зацикленный вход", "платёж не уходит"), деплои часто вызывают предсказуемые поломки (миграции, конфиг, кэширование), или исправление известно, но помнит об этом только один человек.

Вот простой пример: после некоторых деплоев пользователи жалуются, что не могут войти. Без runbook дежурный догадывается: откатиться, перезапустить, править env, написать коллегам. С runbook он следует проверённому пути: подтверждает симптом, смотрит несколько сигналов, которые важны, применяет самое безопасное исправление и проверяет, что логин снова работает.

Хороший runbook снижает количество догадок и панику. Он не устраняет инциденты и не заменяет инженерную работу по устранению корня. Зато он даёт время, снижает риск (меньше случайных изменений в проде) и делает реакцию последовательной, даже если создатель фичи недоступен.

Выбирайте ошибки, которые стоит превратить в runbooks

Не каждый алерт заслуживает runbook. Начните с проблем, которые постоянно втягивают людей в один и тот же цикл: одинаковые вопросы в Slack, одни и те же "кто умеет чинить это?", и повторяющиеся ручные шаги, живущие в чьей‑то памяти.

Выбирайте проблемы, которые либо часто происходят, либо наносят ощутимый вред бизнесу (потерянные входы, упавшие платежи, застрявшие задания). Если вы ещё не можете описать надёжный обход, отложите и напишите короткую заметку «известные симптомы» вместо полноценного runbook.

Простой фильтр для первых 3–5 runbooks:

• Повторяется: случалось больше одного раза за последние недели.
• Влияние: блокирует клиентов или доход, даже если редкое.
• Предсказуемость: у вас есть известный обход, даже если корень проблемы не понятен полностью.
• Поглотитель времени: обычно занимает больше 15–30 минут на решение.
• Владение: есть команда, которая может его поддерживать.

Большинство команд находит быстрые победы в одних и тех же областях: вход и авторизация (токены, сессии, редирект‑петли), платежи и вебхуки (повторы, проверки подписи), фоновые задачи и очереди (застрявшие воркеры, «poison»‑сообщения) и таймауты/лимиты API (медленные эндпоинты, сбои апстрима).

Структура runbook: поля, которые должны быть всегда

Runbook помогает только если по нему легко пробежаться в стрессовой ситуации. Единая структура также ускоряет создание следующего runbook.

Начните с шапки, которая даёт базовую информацию одним взглядом:

• Название инцидента (используйте ту же формулировку, что и в алерте)
• Уровень серьёзности
• Затронутый сервис или фича
• Последнее обновление (имя и дата)

Если runbook устарел, люди будут сомневаться в нём.

Далее добавьте однострочную цель, которая описывает, что значит «исправлено» простыми словами. Не "перезапустить сервер", а "пользователи снова могут войти и уровень ошибок вернулся в норму в течение 10 минут". Это не даст людям остановиться слишком рано.

Чётко укажите, для кого предназначен runbook. Сотрудник поддержки нуждается в других деталях, чем дежурный инженер, основатель или подрядчик. Если читатель — не технический, дайте простые проверки и куда нажимать, а не только внутренняя терминология.

Перечислите требуемые доступы заранее, чтобы люди не упёрлись в блокировку во время инцидента:

• Дашборды (метрики и трекинг ошибок)
• Логи (приложение и инфраструктура)
• Админ‑панель (пользователи и биллинг)
• Облачная консоль (деплои и секреты)
• Система фич-флагов или конфигураций

Потом держите несколько стандартных полей, чтобы каждый runbook был знакомым: предпосылки и заметки по безопасности (что не делать), контакт для эскалации, примечание по откату и небольшой блок верификации — как подтвердить восстановление.

Пошаговые действия, которые можно выполнить

Начните с примечания по безопасности. Поставьте рискованные вещи вперёд, чтобы никто «хорошо желая» не сделал хуже в 2 ночи. Будьте конкретны: «Не удаляйте данные, не ротируйте ключи и не перезапускайте весь кластер без одобрения руководителя инцидента.» Если шаг может вызвать даунтайм, скажите об этом прямо.

Пишите шаги как маленькие действия, которые можно сделать примерно за минуту. Каждый шаг должен начинаться с глагола (Проверьте, Сравните, Выполните, Откатите). Оставляйте шаги сфокусированными: один шаг — одна цель — один ожидаемый результат.

Когда включаете команды, сделайте их удобными для копирования. Используйте плейсхолдеры и укажите, откуда они берутся (тикет, логи, дашборд). Сначала — проверки только для чтения, затем — изменения.

# 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

После важных шагов добавляйте «что вы должны увидеть». Если ожидаемый вывод пустой, укажите это. Если успех означает падение метрики, назовите метрику и нормальный диапазон.

Постройте явную точку останова. Если в логах появляется другая ошибка, чем предполагает runbook, или команда возвращает permission denied, следующий шаг не «попробуй ещё сильнее». Нужно:

• Остановить изменения
• Захватить ключевые сигналы (время, request ID, последний деплой)
• Эскалировать владельцу, указанному для этой системы

Триаж и диагностика: находите причину без догадок

Когда срабатывает алерт, ваша первая цель — понять форму проблемы, а не искать хитрое решение. Runbook должен сделать первые 10 минут предсказуемыми, даже если система шумная.

Начните со масштаба. Это один пользователь (данные аккаунта), один регион (edge или маршрутизация) или все (основная зависимость)? Быстрый ответ не даст вам копаться не в том месте.

Быстрые проверки, которые часто объясняют «внезапные» падения

Перед глубокими логами проверьте обычные подозреваемые:

• Недавние деплои, rollout’ы или миграции за последние 30–60 минут
• Изменения конфига (env vars, секреты, строки подключения) и истёкшие креденшалы
• Фич‑флаги или эксперименты, изменившие правила таргетинга
• Инциденты зависимостей (БД, очередь, провайдер авторизации) и лимиты
• Сдвиги по ёмкости (застрявшее autoscaling, новый источник трафика, всплеск cron)

Затем возьмите несколько чисел, которые помогут выбрать направление: тренд ошибки, задержки, глубина очереди и количество подключений к базе (или степень насыщения). Если можно, сравните «сейчас» с «последним часом» и «тем же временем вчера».

Найдите первое полезное сообщение об ошибке

Логов может быть бесконечно много. Фильтруйте по падающему эндпоинту или имени задания, затем ищите самую раннюю ошибку в цепочке (не последний стек‑трэйс). Возьмите один request ID, user ID или узкое окно по времени и следуйте, пока не найдёте первое «почему».

Если мониторинга нет (часто в поспешных прототипах), runbook должен сказать, что собрать вручную перед изменениями:

• Точное время начала проблемы и как она была обнаружена
• Пару примерных user ID или request ID, которые падают
• Один полный ответ с ошибкой и один успешный ответ (если есть)
• Текущая версия приложения/коммит и состояние фич‑флагов
• Скриншот или экспорт ключевых графиков, которые у вас есть

Этот небольшой пакет доказательств предотвращает догадки и упрощает передачу дела другому.

Владельцы и эскалация: кто что делает и когда

Runbook работает только если указано, кто за это отвечает. «Владелец» должен быть ролью (а не только человеком), который дежурит или отвечает за сервис. Добавьте резервную роль на случай, если первичный спит, в отпуске или уже занят другим инцидентом.

Также определите, кто может одобрять рискованные действия. Чётко опишите, что для вашей команды считается «рискованным»: всё, что может привести к потере данных, даунтайму, утечке безопасности или блокировке клиента. Примеры: откат миграции базы, ротация auth‑секретов, отключение контроля безопасности или запуск деструктивного скрипта очистки.

Опишите, когда звонить и когда эскалировать. Нечёткие правила типа «позвонить, если плохо» создают задержки.

• Звонить немедленно, если ошибки при логине превышают X% в течение Y минут или ключевой эндпоинт возвращает 5xx.
• Звонить, если любой инцидент с влиянием на клиентов длится дольше Z минут без подтверждённого пути к восстановлению.
• Сообщать в безопасность сразу, если подозревается утечка секретов, неожиданный админ‑доступ или возможная инъекция.
• Эскалировать, если для фикса требуется одобрение, которого у вас нет.
• Эскалировать, если после безопасной меры вы не можете подтвердить улучшение.

Потом перечислите порядок эскалации, чтобы никто не спорил во время инцидента:

• Первичный дежурный
• Резервный дежурный
• Техлид сервиса
• Безопасность (если затрагивает auth, секреты или подозрительный трафик)
• Поддержка вендора (облако, платёжные системы, email), когда доказательства указывают за пределы вашего кода

Добавьте короткую заметку для саппорта: одна‑две фразы для пользователей и чего не обещать. Пример: "Мы расследуем сбои входа и работаем над исправлением. Ваши данные в безопасности. Следующее обновление через 30 минут."

Проверки верификации: как подтвердить, что фиксация сработала

Фикс не считается реальным, пока вы не сможете это доказать. Верификационные проверки — это маленькие, повторяемые измерения, которые вы запускаете сразу после изменения, чтобы убедиться, что система снова здорова.

Соотносьте проверки с тем, что испытывали пользователи. Если проблема была в логинах, не ограничивайтесь «ошибки упали». Убедитесь, что люди действительно могут входить, и проверьте уровень ошибок и здоровье auth‑сервиса.

Держите просто: один smoke‑тест + несколько метрик

Цель — smoke‑тест, который любой дежурный может выполнить, и 2–3 сигнала из мониторинга:

• Smoke‑тест (пользовательский поток): выполните одно реальное действие end‑to‑end (войти, создать запись, завершить тестовый чек‑аут) и опишите, что считается успехом.
• Ключевые метрики: выберите несколько, которые должны измениться сразу (процент 5xx, ошибки авторизации, глубина очереди, p95 задержки, логи ошибок для конкретного эндпоинта).
• Проверки системы: подтвердите здоровье зависимостей (подключения к БД, процент попаданий в кэш, статус третьих сторон, если они вовлечены).
• Проверка регрессии: повторите действие, вызвавшее инцидент (тот же маршрут, тот же payload‑шаблон, то же состояние фич‑флагов).
• Ограждения: убедитесь, что во время фикса не были раскрыты секреты или включены отладочные настройки.

Если фиксом был откат, добавьте проверку отката: подтвердите, что версия X снова в продакшене, проверьте, что проблемный эндпоинт возвращает 200, и что уровень ошибок вернулся к базовому.

Установите окно наблюдения и чёткую линию «готово»

После фикса наблюдайте графики и логи 15–60 минут. Запишите, что вы ожидаете оставаться стабильным и какой порог означает возврат проблемы.

Завершите одной строкой «готово», например: «Готово, когда smoke‑тест пройдёт дважды, уровень ошибок держится ниже 1% в течение 30 минут и не появляются новые связанные алерты.» Затем задокументируйте:

• что изменили (коммит, конфиг, флаг, деплой или откат)
• какие проверки вы запускали и их результаты
• что вы сделаете в следующий раз, чтобы ловить это раньше

Секция команд: сделайте копирование безопасным и предсказуемым

Самый быстрый способ превратить runbook в инструмент (а не в документ, которому не доверяют) — сделать команды безопасными для копирования и сложными в неправильном использовании. Относитесь к блоку команд как к мини‑продукту: чёткие входные данные, ожидаемый вывод, явные предупреждения.

Начните с команд только для чтения. Пишите команды на запись (рестарты, правки конфига, миграции) позже и добавляйте однострочное предупреждение над ними.

Шаблон, который хорошо работает:

• Используйте плейсхолдеры вроде <service>, <env>, <region>, <user_id>, <incident_id> и покажите один заполненный пример "известно рабочий".
• Добавляйте команды с пометкой "НЕ ЗАПУСКАТЬ", когда люди часто тянутся к ним в стрессе.
• Указывайте требуемые права заранее (имя роли, доступ к системе и нужно ли право на запись в прод).
• Требуйте запись в журнал изменений: время, точная команда, результат и id тикета/инцидента.
• Говорите, как выглядит «успех» для каждой команды (ожидаемый вывод или число, которое должно измениться).

# 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

Если вы унаследовали неясные команды деплоя или сгенерированные AI‑скрипты для операций, дайте их на ревью перед тем, как они станут «стандартом». Маленькие ошибки (не тот namespace, опасный подстановочный символ, отсутствие шага подтверждения) могут создать повторяющиеся инциденты.

Частые ошибки, которые делают runbooks бесполезными

Runbooks под давлением ломаются по предсказуемым причинам — чаще всего из‑за ясности.

Первая ловушка — это отсутствие ответственности. Runbook, который говорит «кто‑то из бэкенда должен посмотреть логи», будет проигнорирован в 2 утра. Каждой повторяющейся проблеме нужен явно указанный владелец (роль или человек) и чёткий путь эскалации.

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

Проверьте эти вещи перед публикацией:

• Нет владельца или контакта дежурного
• Шаги, предполагающие племенные знания (где логи или какая среда настоящая)
• Отсутствуют проверки верификации, поэтому симптом кратко уходит и возвращается
• Команды устарели после изменений в инфраструктуре (переименованные сервисы, новые регионы, другой инструмент деплоя)
• «Фиксы», которые слишком рискованны или расплывчаты, типа "перезапустить всё" или "изменить конфиг осторожно"

Верификация — то, что чаще всего пропускают, и именно она предотвращает повторные алерты. После каждого исправления добавляйте быстрое доказательство, например: «вход успешен для тестового пользователя», «уровень ошибок упал ниже X» и «нет новых 5xx в течение 10 минут».

Наконец, сделайте формулировки стрессоустойчивыми. Если шаг может навредить, укажите безопасные пределы и механизм отката.

Пример runbook: повторяющиеся сбои входа после деплоя

Этот пример охватывает распространённый сценарий: логин ломается сразу после деплоя.

Сценарий: через 5–10 минут после деплоя пользователи сообщают, что не могут войти. Сайт загружается, но кнопка логина крутится, затем появляется "Something went wrong."

Сигнал алерта: процент ошибок API для /auth/login подскакивает с <1% до 20%+. В саппорте появляются тикеты типа «пароль верный, но вход не проходит».

Владельцы: дежурный инженер (primary), релиз‑капитан (approver для отката), лидер саппорта (коммуникация с пользователями).

Триаж и диагностика

Подтвердите масштаб и последнее изменение перед попытками фикса.

• Подтвердите влияние: новые пользователи, существующие или оба? Один регион или все?
• Проверьте последний деплой: что изменилось в auth, конфиге, env vars или миграциях БД?
• Посмотрите логи на первую ошибку после времени деплоя (ищите 401 vs 500, отсутствующие env vars, ошибки подписи токенов).
• Проверьте зависимости: identity provider, БД, кэш, статус сервиса email.

Смягчающие шаги (выбирайте самый безопасный)

Используйте наименее разрушительный вариант первым и останавливайтесь, как только система восстановится.

• Выключите фич‑флаг, связанный с логином (если есть), чтобы вернуть трафик на предыдущий путь.
• Верните auth‑конфиг к последней известной рабочей версии (обычные причины: callback URL, JWT secret, домен cookie).
• Перезапустите auth‑сервис, чтобы подхватить исправленный конфиг (только после проверки доступности секретов).
• Откатьте деплой к предыдущей версии, если ошибки продолжаются после отката конфига.

Проверки верификации

Подтвердите и UX, и метрики.

• Выполните реальный логин (тестовый пользователь) и убедитесь, что создаётся сессия.
• Уровень ошибок возвращается к базовому в течение 10–15 минут, и в логах нет новых всплесков.

После инцидента обновите runbook с точным паттерном логов, ключом конфига, который вызвал сбой, правилом принятия решения об откате и пред‑деплойной проверкой (например: "проверить наличие обязательных auth env vars в production").

Следующие шаги: поддерживайте runbooks в актуальном состоянии и уменьшайте повторения

Runbook экономит время только если он отражает текущее состояние системы. Самый быстрый путь к устаревшей документации — считать runbook «сделанным» после однократного написания.

После каждого инцидента потратьте 10 минут, пока детали свежи, и внесите мелкие правки: обновите формулировку симптомов, добавьте недостающую строку лога, которая помогла бы, и зафиксируйте новые нюансы из процесса фикса.

Перед закрытием тикета проведите быструю проверку удобства использования:

• Шапка заполнена (сервис, среда, последнее обновление, известные риски)
• Владельцы и путь эскалации указаны и актуальны
• Шаги были протестированы недавно (не просто написаны)
• Проверки верификации определены (что считается успехом)
• Команды безопасны для копирования (ограниченные, обратимые и документированные)

Задайте простой cadence для ревью. Ежемесячный работает для занятых команд, но лучшие триггеры — «после каждого инцидента» и «после рефакторинга или обновления зависимостей» для сервисов, которые ломаются чаще всего.

Если вы замечаете одни и те же сбои после каждого деплоя, возможно, дело не в runbook. Это может быть проблема в кодовой базе, особенно в приложениях, сгенерированных AI, где авторизация, секреты и архитектура выглядят нормально в демонстрации, но разваливаются в продакшене.

Если вы унаследовали AI‑сгенерированное приложение и постоянно тушите одни и те же пожары, FixMyMess (fixmymess.ai) специализируется на диагностике и ремонте таких кодовых баз: исправление логики, усиление безопасности, рефакторинг и подготовка к деплою. Короткий аудит может превратить повторяющиеся "племенные" фиксы в стабильные изменения и дать вам runbooks, которые соответствуют реальному поведению системы.