Як написати SRE Runbook англійською мовою

Runbook є документованою процедурою, яка вказує інженеру на виклику, що саме робити, коли відбувається певний інцидент або операційний сценарій. Хороший runbook заощаджує час, зменшує помилки і знижує стрес від відповіді на інциденти о 3 годині ранку. Погана книга дій - така, яка є неясною, застарілою або важко дотримуватися - може зробити інциденти гіршими.

Для не рідних англомовних людей, які пишуть підручники, викликом є створення чітких, однозначних інструкцій, які стресований інженер може швидко виконати. Цей підручник містить інформацію щодо структури, мови і стилю, які вам потрібні.

---

Цей хід називається Runbook

Runbook не є документом з розробки або навчальним посібником. Це процедурна посилання - як контрольний список пілота. Він повинен бути:

• ** Специфічний ** — написано для одного сценарію, а не як загальний посібник
• ** Actionable ** — кожен крок говорить читачеві, що робити, а не що знати
• ** Поточні ** — застарілі книги запуску є небезпечними
• ** Сканування ** — використовувати нумеровані кроки, а не абзаци

---

Стандартна структура Runbook

1. Європа Заголовок і метадані

Назва: Процедура відгуку платіжної служби з високою затримкою

• Сервіс: payments-api | Власник: Команда платежів | Останнє оновлення: 2026-06-14*
• Попередження: PaymentsAPILatencyHigh — затримка P99 > 2 секунди на 5 хвилин *

2. Огляд

Одне або два речення, що описують сценарій і типову причину.

• “Ця книга описує процедуру відповіді на підвищену затримку у API платежів. Поширені причини включають виснаження бази даних, тайм-аути вниз по течії, і піки трафіку, що перевищують здатність автомасштабування.”*

3-й. Ступінь важкості та ескаляційний шлях

• ”** Серйозність: ** P1 (вплив на прибуток). Передайте це керівнику групи платежів, якщо не вирішите проблему протягом 30 хвилин. Повідомити керівника інженерії, якщо вплив на клієнта перевищує 15 хвилин. “*

4. Попередні умови

• “Перед тим, як виконувати цей підручник, переконайтеся, що у вас є: *
• • Доступ до консолі виробничого AWS *
• • Доступ до панелі керування Datadog (посилання нижче) * *- Канал payments-api відкрито в Slack” *

5. Кроки діагностики

Цей розділ говорить інженеру на гарячому, як зрозуміти, що відбувається.

6. Кроки розв’ язання

У цьому розділі інженер-послугівник наказує, як виправити цю помилку.

7-й. Постінцидентні дії

Що робити після того, як інцидент буде вирішено.

---

Запис діагностичних кроків

Використовуйте чіткі, пронумеровані наказові речення. Кожен крок має мати одну дію.

Добра діагностична мова

• “1. Відкрити панель керування API платежів Datadog: [посилання]”*

• “2. Перевірте графік затримки P99 за останні 30 хвилин. Зауважте, чи є пік поступовим або раптовим — поступові піки вказують на вичерпання ресурсів; раптові піки вказують на подію або розгортання трафіку. ”*

• “3. Перевірте метрику бази даних з’єднань: перейдіть до RDS → payments-db → Performance Insights.”*

• “4. Перевірити на недавні розгортання: запустити gh run list --workflow=deploy --repo=payments-api --limit=5.”*

“5. Перевірити на наявність аномалій у потоці даних у журналах шлюзів API. Фільтр за service=payments для вражених вікон часу.”

Дерева рішень

Використовувати явну умовну логіку, якщо наступний крок залежить від того, що знайде інженер:

• “Якщо пул з’ єднань переповнений (активні з’ єднання > 90%):” * *” → Перейти до ** Розділу А: Вичерпання бази даних з’ єднання **” *

“Якщо нещодавнє розгортання корелює з піком затримки:” ” → Перейти до ** Розділу B: Процедура повернення* ”*

“Якщо не знайдено проблем з розгортанням або з’ єднанням:” ” → Перейти до Розділу C: Дослідження піку трафіку”

---

Запис кроків розв’ язання

Кроки розв’ язання повинні бути навіть більш точними, ніж діагностичні кроки. Тепер інженер робить дії, які можуть вплинути на виробництво.

Використовувати імперативний настрій

Записувати кожну дію як пряму команду. Не використовувати пасивний голос або звук « х »:

** Слабкий (пасивний/захищений): **

“Розгортання, ймовірно, слід відкласти, якщо буде підтверджено, що проблема пов’ язана з останнім випуском.”

** Сильна (імператив): **

“Якщо проблема підтверджена як пов’ язана з розгортанням, негайно відновити за допомогою наступної команди:“

Включити точні команди

• “Запустіть наступну команду, щоб перезапустити підпрограми платіжних операцій:” *
• “kubectl rollout restart deployment/payments-worker -n production ”*

“Щоб повернутись до попереднього розгортання:”

• “kubectl rollout undo deployment/payments-api -n production ”*

“Перевірити, чи завершено розгортання:”

• “kubectl rollout status deployment/payments-api -n production “*

Включити очікувані результати

Скажи інженеру, як виглядає успіх:

• “Затримка P99 повинна почати знижуватися протягом двох- трьох хвилин після перезапуску. Якщо затримка не покращиться протягом п’яти хвилин, перейдіть до ескалації. “*

---

Постінцидентні дії

• “1. Посилання на цю сторінку може вести до статті: Канал «Слабкий» (англ. Slack channel) — канал у мережі Slack

• “2. Оновити квиток на інцидент в PagerDuty з кореневою причиною і розв’язанням.”*

• “3. Якщо Runbook потребує оновлення на основі цього інциденту, відкрийте PR зі змінами і присвоїть його керівнику команди для перегляду. ”*

• “4. Заплануйте пост-морт, якщо інцидент тривав більше 30 хвилин або мав вплив на клієнта. “*

---

Поширені помилки при написанні Runbook

** Використання пасивного голосу для інструкцій. ** « Службу слід перезапустити » є неоднозначним. « Перезапустити службу » не є.

Недосягнення очікуваного результату. Інженери, що перебувають у стресі, повинні знати, чи спрацювало те, що вони тільки що зробили. Завжди скажи, як виглядає успіх.

** Застарілі посилання і команди. ** Runbook з недійсним посиланням на панель приладів або застарілим командою CLI гірше, ніж взагалі не мати runbook. Переглянути підручники після кожної відповідної зміни системи.

** Занадто багато сторінок. ** Runbooks не є навчальними посібниками. Обмежити пояснення до мінімуму, необхідного для прийняття рішення. Якщо вам потрібні додаткові відомості, посилайтеся на окремий документ.

---

Добре написаний підручник з керування є одним з найцінніших документів, які може мати команда. Найкращий час для написання - це в тихий період, відразу після перегляду недавнього інциденту. Мова повинна бути достатньо ясною, щоб втомлений інженер, не знайомий з системою, міг успішно її слідувати опівночі. Це стандарт, за яким треба писати.

Національний склад населення: англійською мовою: англійською мовою: англійською мовою: англійською мовою: англійською мовою: англійською мовою: англійською мовою: англійською мовою: англійською мовою: англійською мовою: англійською мовою: англійською мовою: англійською мовою: англійською мовою: англійською мовою: англійською мовою: англійською мовою: англійською мовою: англійською мовою: англійською мовою: англійською мовою: англійською мовою: англійською мовою: англійською мовою: англійською мовою: англійською мовою: англійською мовою: англійською мовою: англійською мовою: англійською мовою: англійською мовою

Написання ефективних SRE runbooks не просто про перелік команд; це про комунікацію чітко і точно, так що кожен - незалежно від їхнього досвіду - може швидко зрозуміти і виконати рішення. Для не рідних англомовних носіїв це може бути особливо складним завдяки щільності технічної термінології і часто формальної фрази, що використовується в операційній документації. Давайте розглянемо деякі конкретні області, де ретельний вибір слів може значно поліпшити розуміння і зменшити потенційні непорозуміння.

Одна поширена проблема виникає під час перегляду коду. Уявіть, що ви отримуєте коментар до запитів на збирання: « Цій частині бракує достатньої кількості деталей щодо процедур відновлення ». Людина, для якої мова є рідною, може відразу зрозуміти, що це означає: план відновлення повинен бути надійним і чітко визначеним. Однак для когось, хто все ще розвиває свою професійну англійську, це може здатися неоднозначним. Краще було б написати: « Щоб забезпечити успішне відновлення, чи не могли б ви додати чіткі кроки, які описують процес перенесення даних після відновлення, зокрема перевірки для підтвердження цілісності даних? » Таким чином ви отримаєте * конкретні * інструкції і вилучите будь- які потенційні неоднозначності щодо того, що очікується. Аналогічно, в обговореннях Slack, коротке повідомлення на кшталт «Видалити погіршену службу» не допоможе. Замість цього, розгляньте: “Дослідити кореневу причину погіршеної роботи, що впливає на користувачів в регіоні X. Будь ласка, задокументуйте свої висновки, включаючи метричні дані, що показують тяжкість і тривалість проблеми, і запропонуйте стратегію усунення. “Додаток деталей - вказуючи * регіон *, посилаючись на * метричні дані * - негайно підвищує комунікацію.

Іншою ключовою областю є структурування описів PR. Замість простого затвердження «Оновлені попередження про моніторинг», націляйтеся на щось на зразок: «Впроваджено нові пороги попередження в Grafana, щоб проактивно повідомляти команду на виклику про збільшення використання ЦП, що перевищує 90% під час годин пік. Ця зміна має на меті скоротити середній час виявлення (MTTD) і поліпшити загальну стабільність системи. Подробиці налаштування задокументовано у [посилання на config doc].] Включення * meal * (« зменшити MTTD »), певної метрики, за якою слідкують, і посилання на документацію, що підтримує, демонструє досконале розуміння і надає контекст для переглядачів. Зверніть увагу на пасивний голос проти активного голосу також важливо; активний голос - “Ми реалізували…” - загалом ясніше, ніж пасивний голос - “Попередження були реалізовані…” - особливо при описі дій, здійснених вашою командою.

Нарешті, будьте обережні з жаргоном. Хоча технічні терміни є необхідними, послідовно пояснюйте їх значення у контексті підручника. Замість того, щоб постійно використовувати « затримку », розгляньте можливість визначення її як « час, який потрібно запиту для пересування з пристрою користувача до наших серверів і назад ». Це допоможе убезпечити, щоб всі розуміли цю термінологію однаково. Намагайтеся досягти ясності понад усе інше - трохи довше, більш описове пояснення завжди краще, ніж неоднозначна або потенційно неправильно інтерпретована інструкція.