Проблема эксплуатационной инструкции видна в первый сбой: сервис отвечает ошибками, а оператор не понимает, с какого шага начать и как ограничить воздействие. Цена неточного текста — несколько людей одновременно меняют состояние системы, исходные метрики теряются, а откат объявляют успешным только потому, что команда завершилась без ошибки.
Типичный симптом нужно описать наблюдаемыми признаками: например, «5xx выше 5% на POST /payments в одном регионе», а не «сервис нездоров». Если инструкция не задаёт область, условие запуска и проверку результата, читатель может отключить здоровый трафик, выполнить команду на другой версии или вернуть конфигурацию без восстановления данных.
Хороший runbook не перечисляет команды ради полноты. Он связывает симптом с областью, предварительным условием, одним изменением, обратным действием и наблюдаемым результатом. Каждый шаг отвечает на четыре вопроса: что должно быть истинно до команды, что изменится, какой вывод ожидается и когда нужно остановиться.
Такой порядок отделяет факт от гипотезы. Сначала оператор сохраняет сигнал и ограничивает scope. Затем меняет один рычаг. После этого ждёт заданное окно и сравнивает метрику с критерием. Если критерий не выполнен или появился новый риск, оператор запускает rollback по заранее описанному условию. Окончание команды не равно восстановлению сервиса.
Symptom фиксирует метрику, endpoint и время. Scope показывает, кого затронула проблема: регион, релиз, долю трафика или конкретный tenant. Precondition подтверждает доступ, версию, наличие backup или сохранённого dashboard. Action меняет одно состояние. Rollback возвращает его при указанном условии. Verification задаёт метрику и окно наблюдения.
Эти поля защищают от разных ошибок. Без scope оператор расширит локальный сбой до всей системы. Без precondition он применит команду к неправильной версии. Несвязанные команды усложнят причинность: после них нельзя понять, что помогло. Без verification текст заканчивается слишком рано — на синтаксически успешном вызове, а не на подтверждённом результате.
Модальность тоже должна быть явной. Слова «проверьте», «убедитесь» и «при необходимости» ничего не задают, пока рядом нет объекта и критерия. В терминах RFC 2119 обязательное условие можно пометить как MUST, допустимое исключение — как SHOULD, необязательную диагностику — как MAY. В русской инструкции достаточно написать «обязательно», «рекомендуется» или «можно», если правило остаётся однозначным.
Перед изменением состояния сохраните наблюдаемый факт. Нужен минимальный набор, по которому можно сравнить до и после: scope, версия, временное окно и исходная метрика. Для опасной команды укажите право доступа, namespace и способ увидеть diff. Не вставляйте секреты, настоящие hostname и локальные alias, которых читатель не сможет проверить.
Я выбираю самый узкий обратимый рычаг, который действительно покрывает scope. Это не универсальное правило: если ошибка уже записала несовместимые данные, одного feature flag недостаточно. Матрица ниже помогает назвать цену выбора до команды, а не после неудачного отката.
| Рычаг | Когда подходит | Цена и риск | Что проверить до запуска |
|---|---|---|---|
| Feature flag | Проблема включается отдельным путём и данные совместимы | Малый blast radius; нужна рабочая ветка выключения и владелец флага | Scope флага, текущая версия и время распространения |
| Версионируемая конфигурация | Ошибка в параметре, а код менять не нужно | Откат обычно короткий, но конфигурация может приходить с задержкой | Diff, порядок публикации и фактическое значение на инстансе |
| Предыдущий артефакт | Причина в коде и быстрый локальный рычаг не покрывает сбой | Радиус больше и операция дольше; возможна несовместимость с миграцией данных | Совместимость схемы, артефакт и критерий остановки |
Сигнал остановки должен быть отдельной строкой: например, «при росте 5xx в незатронутом scope или при появлении ошибок записи прекратить rollout и вернуть flag». Он не заменяет критерий восстановления. Остановка говорит, когда нельзя продолжать, а verification — когда допустимо завершить операцию.
| Симптом | Вероятная причина | Проверка | Действие |
|---|---|---|---|
| 5xx выше порога на одном endpoint | Новая версия или флаг затрагивает ограниченный scope | Сравнить release, регион, долю трафика и error rate за одинаковое окно | Ограничить воздействие флагом; при ухудшении вернуть его |
| Timeout растёт, 5xx не меняется | Зависимость отвечает медленно или исчерпан ресурс | Сопоставить p95/p99, trace и лимиты пула с baseline | Не повторять запросы вслепую; остановить изменение и проверить зависимость |
| 409 при повторной операции | Состояние уже изменено или нарушена идемпотентность | Проверить operation id, запись состояния и время первого вызова | Не выполнять повторно; выбрать безопасный путь чтения или ручного разбора |
| После отката ошибка остаётся | Откатил один рычаг, но причина вне его scope | Сравнить метрики до, после action и после rollback | Остановиться, зафиксировать результат и передать расследование владельцу |
| Команда завершилась успешно | Изменился только control plane, data plane ещё не восстановлен | Проверить пользовательский сигнал и заданное окно наблюдения | Не закрывать инцидент до прохождения verification |
Ниже — учебная проверка карточки runbook. Функция принимает шесть полей и отклоняет объект без содержательного rollback или наблюдаемой verification. Она не проверяет права, shell, облако и реальную исполнимость команды. Её задача — поймать структурный пробел до публикации инструкции.
function validateRunbookCard(card) {\n const required = ['symptom', 'scope', 'precondition', 'action', 'rollback', 'verification'];\n if (!card || typeof card !== 'object') return { ok: false, reason: 'runbook-must-be-object' };\n const missing = required.filter((key) => typeof card[key] !== 'string' || card[key].trim().length < 10);\n if (missing.length) return { ok: false, reason: 'runbook-fields-missing', missing };\n if (!/rollback|откат|вернуть/i.test(card.rollback)) return { ok: false, reason: 'rollback-must-be-explicit' };\n if (!/провер|verify|метрик|threshold/i.test(card.verification)) return { ok: false, reason: 'verification-must-be-observable' };\n return { ok: true, order: required };\n}\n\nconst card = validateRunbookCard({\n symptom: '5xx выше 5 процентов на POST /payments',\n scope: 'region eu-west, release 42, 10 percent traffic',\n precondition: 'есть доступ к flag и сохранён dashboard за 15 минут',\n action: 'отключить flag payments-v2 для 10 процентов трафика',\n rollback: 'вернуть flag payments-v2 после проверки результата',\n verification: 'проверить error rate и p95 в течение 10 минут',\n});\nconsole.log(card.ok, card.order.join(' → '));\n// true symptom → scope → precondition → action → rollback → verification\n\nconst incomplete = { ...card };\ndelete incomplete.rollback;\nconsole.log(validateRunbookCard(incomplete).reason);\n// runbook-fields-missingВ примере первая строка показывает, что карточка прошла структурную проверку, а вторая — что пропущенное поле обнаруживается до публикации. Этот код не разрешает выполнять операцию: он не знает права, shell, облако, реальную команду и корректность порога. В настоящем runbook команда должна ссылаться на локальный механизм изменения и на конкретный сигнал. Если эти сведения нельзя проверить, их нужно оставить как явно обозначенные placeholders, а не заполнять вымышленными значениями.
Структурная проверка не знает, кому разрешён доступ, как устроены shell и облако, есть ли backup, lock и реальные пороги. Она не выполняет команду и не доказывает, что rollback действительно возвращает исходное состояние. Поэтому runbook нельзя считать разрешением менять production: approval, окно операции и владельца изменения задаёт локальный процесс.
Архивная NIST SP 800-61 Revision 2 (2012) показывает цикл подготовки, обнаружения и анализа, containment, восстановления и действий после инцидента. NIST пометил Rev. 2 как withdrawn и заменил её Rev. 3 (2025), поэтому этот цикл здесь приведён как историческая модель, а не как текущая нормативная схема. Актуальная Rev. 3 связывает incident response с CSF 2.0, но по-прежнему не знает ваших сервисных зависимостей, команд и порогов остановки. RFC 2119 помогает различить обязательное и рекомендуемое действие, но не тестирует исполнимость конкретной команды.
Не добавляйте в текст вымышленные замеры или производственные результаты ради гладкого примера. Учебная карточка должна оставаться учебной и не содержать секретов, настоящих адресов и необратимых команд. Если значение неизвестно, лучше назвать, где его проверить, чем подменить неизвестное числом.
Инструкция готова, когда читатель может по первым абзацам определить симптом и scope, до команды проверить precondition, выполнить одно ограниченное действие, увидеть ожидаемый output, запустить rollback по явному условию и подтвердить восстановление метрикой за заданное окно. Если для любого шага нельзя назвать наблюдаемый результат, текст ещё не готов: вернитесь к условию, границе или проверке.