Шаблон инструкции на случай инцидента, которой будут пользоваться новые инженеры

Почему люди игнорируют runbook-инструкции

Большинство runbook-инструкций проваливаются по простой причине: они читаются как документы о правилах, а не как инструкции. Когда срабатывает алерт, никому не нужен экскурс в историю, руководство по названиям или абзац про ответственность. Нужное — это первое безопасное действие. И быстро.

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

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

Слабые runbook-инструкции обычно ломаются в одних и тех же местах:

• Первое действие спрятано где-то в середине страницы.
• Нет нужного дашборда или вида логов.
• Шаги используют расплывчатые слова вроде "исследовать" или "проверить", но не говорят как именно.
• Фоновые примечания стоят прямо посреди срочных действий.

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

Расплывчатые формулировки вызывают другую задержку. "Посмотрите на ошибки" звучит понятно, пока новый инженер не спросит, какие ошибки считать, какой диапазон времени брать и какое число означает проблему. Хорошие runbook-инструкции убирают такие догадки. Они называют сигнал, порог и следующий шаг.

Есть быстрый тест. Дайте страницу человеку, который её не писал, и попросите пройти по ней во время учебного алерта. Если он останавливается, чтобы спросить, куда нажать, что означает фраза или плохое ли это число, runbook ещё не готов. Он может быть точным, но люди всё равно им не будут пользоваться.

Что показать в первую минуту

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

Поставьте название дашборда в первой строке runbook-инструкции. Используйте точное имя, по которому его ищут в инструменте мониторинга. Если у дашборда есть production- и staging-версия, сразу укажите, какую открыть. "Проверьте дашборд" — этого недостаточно.

Затем назовите первый график, который нужно открыть. Выберите один график, который быстро отвечает на главный вопрос: сервис действительно сейчас нездоров? Для многих команд это частота ошибок, задержка, глубина очереди или объём запросов. Выберите один и поставьте его ближе к началу. Если человеку нужны три вкладки и шесть графиков, прежде чем он поймёт, что происходит, инструкция уже слишком длинная.

Покажите, как выглядит норма, простыми числами. "CPU меняется" почти ничего не говорит. "Задержка обычно 120–250 мс, с короткими всплесками после деплоев" даёт конкретную точку сравнения.

Блок первой минуты обычно должен включать точное имя дашборда, первый график, который нужно открыть, нормальный диапазон для этого графика, текущего владельца и правило для быстрой эскалации. Последний пункт особенно важен. "Эскалируйте, если ошибки держатся выше 5% в течение 10 минут" — это работает. "Эскалируйте при серьёзных проблемах" — нет.

Короткий пример лучше любого вылизанного абзаца: "Откройте Checkout API - Production. Сначала посмотрите на 5xx error rate за последние 15 минут. Норма — ниже 0,3% вне окон деплоя. Owner: Payments team. Эскалируйте немедленно, если checkout полностью недоступен или если 5xx остаётся выше 2% в течение 5 минут." Новый инженер сможет действовать по такому тексту.

Как делать шаги короткими

В 2 часа ночи длинные объяснения только тормозят. Полезный on-call runbook даёт по одному понятному действию за раз, чтобы уставший инженер мог работать, а не разбирать стену текста.

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

Начинайте каждый шаг с глагола. "Откройте", "проверьте", "запустите", "сравните" и "эскалируйте" легко просканировать, потому что взгляд сразу цепляется за действие. Мягкие начала вроде "Возможно, стоит" или "Следующее, что можно сделать" только раздувают текст и прячут суть.

Не смешивайте клики по экрану и команды в терминале в одном предложении. Разделяйте их, даже если они идут подряд.

Короткий пример

• Откройте Grafana.
• Выберите дашборд Payments API.
• Поставьте диапазон времени на "Last 15 minutes".
• Запустите kubectl get pods -n payments.
• Сравните перезапуски pod'ов со всплеском ошибок.

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

Фоновые примечания по-прежнему важны, но они не должны стоять внутри шага. Перенесите их ниже основного действия или в конец страницы. "Проверьте недавние деплои, которые часто вызывают проблемы с кэшем в одном регионе, и при необходимости откатите" заставляет человека делать слишком много сразу. Разбейте это на две строки: "Откройте историю деплоев." Затем: "Если последний деплой совпадает с началом инцидента, откатите его." После этого добавьте примечание про кэш.

Останавливайтесь, когда читатель понимает две вещи: что делать и какого результата ждать. "Перезапустите worker. Глубина очереди должна начать снижаться в течение 2 минут." Этого достаточно для основного пути. Если нужно больше деталей, вынесите их в заметки, а не в сам шаг.

Хороший runbook часто выглядит немного резко. Это хороший знак.

Пишите решения, которые людям нужно принять

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

Описывайте каждое решение как простой выбор if/then. Если частота ошибок выше 5% в течение 10 минут, делайте откат. Если CPU высокий, но запросов обычно столько же, сначала проверьте последний job или деплой, прежде чем что-то перезапускать. Это намного проще, чем "если всё выглядит плохо" или "если система кажется медленной".

Числа нужны простые и конкретные. Используйте пороги, временные окна и чёткие сигналы из дашборда или логов. Новые инженеры не должны переводить расплывчатые фразы вроде "большой всплеск", "высокая нагрузка" или "серьёзное влияние" в действие.

Хорошо работает короткий формат:

• Если ошибки checkout держатся выше 3% в течение 5 минут, эскалируйте incident lead.
• Если один node нездоров, а трафик стабилен, удалите этот node, прежде чем перезапускать сервис.
• Если задержка репликации базы данных превышает 30 секунд, остановите попытки failover и зовите помощь.
• Если использование памяти растёт после свежего деплоя, делайте откат, прежде чем менять правила масштабирования.

Каждый выбор должен опираться на один сигнал, которому можно доверять. Избегайте решений, которые зависят от пяти вкладок, чутья или внутреннего знания команды. Если инженеру нужно сравнивать две метрики, назовите обе и объясните, почему они важны.

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

Прямо укажите, что не нужно менять во время triage. Диагностику держите отдельно от чистки. Если команда ещё выясняет причину, не делайте изменения схемы, широкие правки конфигурации, полную очистку кэша или несколько перезапусков сразу. Такие действия могут стереть следы и создать вторую проблему.

Лучшие runbook-инструкции не пытаются покрыть все крайние случаи. Они делают первые несколько решений очевидными, измеримыми и безопасными.

Собирайте runbook в правильном порядке

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

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

Практическая последовательность

1. Подтвердите алерт и затронутый сервис.
2. Откройте основной дашборд и сравните текущие графики с нормальным трафиком, задержкой и уровнем ошибок.
3. Проверьте последний деплой, изменение feature flag или обновление конфигурации.
4. Выберите ветку в runbook, которая соответствует увиденному сигналу.
5. Сначала сделайте самое маленькое безопасное действие.

Шаг с ветвлением очень важен. Runbook не должен читаться как одна длинная стена инструкций. Он должен разветвляться там, где расходятся признаки. Если ошибки выросли сразу после деплоя, идите по ветке деплоя. Если трафик нормальный, а падает одна зависимость, идите по ветке зависимости. Под давлением людям лучше помогают две-три понятные дороги, чем десять абзацев теории.

Маленькие действия лучше драматичных. Перезапустите один worker, прежде чем перезапускать весь сервис. Откатите одно изменение конфигурации, прежде чем отключать половину системы. Маленький шаг ограничивает ущерб и показывает, вообще туда ли вы идёте.

Оставьте след

Runbook должен также напоминать инженеру, чтобы он записал, что увидел и что изменил. Держите заметку короткой: время, симптом, действие, результат. Например: "02:14, рост ошибки на 18 процентов, deploy 884 выглядел подозрительно, сделали откат, ошибки вернулись к норме за 3 минуты."

Такая запись помогает следующему человеку, ускоряет передачу инцидента и превращает один стрессовый случай в лучший runbook на следующий день.

Простой пример инцидента

В 9:10 утра payment API начинает выдавать таймауты. Клиенты ещё могут просматривать сайт, но checkout зависает, обращения в поддержку начинают расти, и дежурному инженеру нужен один экран, который отсекает шум.

Runbook должен начинаться с дашборда, а не с теории. Первый блок должен показывать две вещи рядом: задержку и частоту ошибок для payment API. Если обе метрики растут одновременно, инженер понимает, что проблема уже происходит и её видят клиенты. Если сначала растёт задержка, а потом появляются ошибки, обычно это указывает на медленную зависимость, а не на полный отказ.

Открывающие шаги могут быть такими короткими:

1. Откройте дашборд payment API.
2. Подтвердите, что всплеск начался около 9:10 утра.
3. Проверьте, был ли деплой в предыдущие 10 минут.
4. Если деплой не совпадает по времени, проверьте панели базы данных.

Под давлением люди начинают гадать. Runbook должен убрать это угадывание.

Если в 9:05 утра вышел деплой и график сразу испортился, инженер проверяет ещё один сигнал, прежде чем действовать: оставался ли объём запросов нормальным? Если трафик ровный, а новая версия совпадает с началом всплеска, делайте откат. Не заставляйте инженера спорить с этим 15 минут.

Если деплой не подходит по времени, следующая ветка проверяет замедление базы данных. Дашборд должен показывать задержку запросов, нагрузку на соединения и число неудачных запросов. Если сначала удваивается задержка запросов, а через минуту растут ошибки API, скорее всего приложение ждёт базу данных. В этот момент инженер эскалирует к владельцу базы данных или к infra lead, уже имея нужные доказательства.

Runbook заканчивается двумя понятными исходами: откатить плохой деплой или эскалировать с временными метками, просмотренными графиками и уже исключённой неправильной веткой. Именно это делает runbook удобным для нового инженера в 9:12 утра, а не только читаемым в спокойный день.

Ошибки, которые тратят время впустую

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

Одна из частых ошибок — превращать одну страницу в свалку всех инцидентов, которые когда-либо были у команды. Оставьте runbook для действий. Глубокий фон, редкие баги и детали postmortem вынесите в отдельные заметки. Страница для дежурства должна быстро отвечать на один вопрос: что я проверяю и что делаю дальше?

Ещё одна трата времени — прятать команды внутри длинных абзацев. Предложение вроде "можно посмотреть логи на API pod'ах, а потом, возможно, перезапустить worker, если память выглядит высокой" заставляет искать настоящую инструкцию. Поставьте команду на отдельную строку или в короткий code block и сразу сделайте понятным результат. "Если частота ошибок держится выше 5% в течение 10 минут, перезапустите worker-a" — гораздо лучше, чем "если выглядит плохо, подумайте о перезапуске".

Расплывчатые пороги создают ту же проблему. "Высокая задержка" в 3 часа ночи ничего не значит. Дайте число, временное окно и источник истины. Если команда использует Grafana или Sentry, назовите график или алерт, который решает шаг. Люди не должны гадать, нормально ли сегодня 400 мс или это реальная проблема.

Runbook становится неудобным и тогда, когда шаги triage и заметки для postmortem живут в одном потоке. Triage отвечает на вопрос, что делать сейчас. Заметки postmortem объясняют, почему баг случился в прошлом месяце. Смешивание этих вещей сбивает фокус.

Старые названия доставляют больше проблем, чем многие команды ожидают. Если сервис раньше назывался "billing-v2", а теперь это "payments-api", новый инженер может открыть не тот дашборд, перезапустить не ту задачу или эскалировать не к тому владельцу. Такое часто случается после миграций и смены команды.

Прежде чем публиковать runbook, попросите кого-то нового пройти по нему на фальшивом алерте. Посмотрите, где человек останавливается. Обычно именно эти паузы и показывают потери времени.

Быстрые проверки перед тем, как команда начнёт пользоваться runbook

Runbook должен работать для самого нового дежурного, а не только для того, кто его написал. Дайте его инженеру, который знает продукт, но плохо знает именно этот сценарий сбоя. Если он тормозит уже в первую минуту, странице нужна доработка.

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

Самое безопасное первое действие должно быть очевидным. Новые инженеры замирают, когда любой вариант кажется рискованным. Прямо укажите низкорисковый шаг первым: проверить частоту ошибок, приостановить rollout или увести трафик с сломанного пути, если это уже разрешено. Если runbook говорит "исследуйте" без объяснения, где смотреть и чего не трогать, перепишите его.

Эскалация должна ощущаться простой и механической. Чёткие пороги лучше расплывчатых оценок. Используйте прямые триггеры вроде:

• эскалируйте, если вход в аккаунт у клиентов не работает больше 5 минут
• эскалируйте, если возможна потеря данных
• эскалируйте, если первое безопасное действие не меняет метрику
• эскалируйте, если за 2 минуты не удаётся определить владельца сервиса
• эскалируйте, если runbook и дашборд не совпадают с реальностью

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

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

Хорошее правило простое: новый инженер должен уметь найти дашборд, сделать первое безопасное действие, понять, когда эскалировать, и знать, кто владеет сервисом, не спрашивая никого. Если нет — это всё ещё черновик.

Что делать дальше с вашими runbook-инструкциями

Runbook становится лучше после реальных инцидентов, а не после долгих документальных ревью. Каждый раз, когда команда разбирает алерт, выделяйте десять минут, пока детали свежие, и задавайте один простой вопрос: что на странице помогло, а что было проигнорировано?

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

Маленькие правки важнее полной переписи. Runbook остаётся полезным только если команда относится к нему как к рабочим заметкам, а не как к политике.

Хорошо работает простой цикл проверки. После каждого инцидента ответственный отмечает запутанные, пропущенные или устаревшие шаги. Владелец сервиса обновляет runbook в течение дня-двух. Новый инженер проходит по странице и говорит, где бы он остановился. Команда хранит runbook у тех, кто владеет сервисом.

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

Проверка с новым инженером стоит усилий. Дайте ему страницу, алерт и ничего больше. Если он останавливается после третьего шага и спрашивает: "Какой дашборд открыть?" или "Кто решает, что это уже влияет на клиентов?", значит, в runbook всё ещё есть пробел.

Для стартапов и небольших команд эта работа часто откладывается, потому что одни и те же люди выпускают фичи, отвечают клиентам и закрывают on-call. В такой ситуации может помочь внешний разбор. Oleg Sotnikov на oleg.is проводит review incident-документов и on-call-процессов в рамках fractional CTO advisory, с практическим фокусом на более короткие runbook-инструкции, понятное владение и меньшее число лишних шагов под давлением.

Держите правило простым: один владелец, один review после каждого инцидента и один быстрый проход страницы новым человеком каждые несколько недель.

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