Post-Incident Report English: Writing Effective Postmortems

Introduction

Післяоперативний огляд (також званий постінцидентним оглядом або PIR) є письмовим документом, який аналізує, що пішло не так під час інциденту, чому це сталося і що команда зробить, щоб запобігти цьому в майбутньому. Написання хорошого постмортму англійською вимагає точності — кожне слово має значення, тому що ці документи читають інженери, менеджери, а іноді і клієнти. Стиль письма також навмисно бездоганний, що вимагає певного лінгвістичного вибору, який багато нерідних письменників вважають неінтуїтивним.

Словник постмодернізму

Знання основного словника післясмертної допомоги дозволяє вам читати, писати і обговорювати події точно.

** Терміни на графіку: **

• Інцидент стався о 14:32 UTC, коли була введена перша попереджаюча сигналізація
• «Приблизно через 20 хвилин після початкового розгортання, кількість помилок почала зростати.»
• Сервіс був відновлений о 16:14 UTC, що дало загальну тривалість переривання 1 годину 42 хвилини
• «Вік виявлення був 8 хвилин — проміжок часу між початком інциденту і першим попередженням, яке було піднято.»

** MTTR ** означає середній час відновлення — середній час, який знадобиться для відновлення служби після інциденту. Ви можете написати: “Наш MTTR для цього класу інциденту становить приблизно 45 хвилин на основі останніх п’яти випадків.”

Корінь проблеми проти факторів, що сприяють:

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

Використання правильного розрізнення між кореневою причиною і факторами, що сприяють, важливо - багато інцидентів мають кілька факторів, що сприяють, але тільки одну кореневу причину.

Невідомий автор літопису

Культура «безвинних постмоделей», яку вперше запровадили такі компанії, як Google і Etsy, вважає, що інциденти спричинені системними збоями, а не окремими помилками. Стиль письма відображає це.

** Не називайте людей як причину: **

• Замість: “John розгорнув без запуску тестів і спричинив перерву.”
• Написати: « Розгортання було виконано без запуску пакету тестування інтеграції. Інциденту спричинила відсутність обов’язкового ворота перед розгортанням в CI pipeline. ”

** Використовуйте пасивний голос для опису дій: **

• Зміна конфігурації була застосована без запуску канарського розгортання
• «Період попередження був встановлений занадто високо, що затримало виявлення»
• «Відновлення було розпочато о 15:47 UTC»

** Людська помилка як помилка проектування системи: **

• «Інженер не знав, що ця зміна потребувала міграції бази даних — в Runbook це не було чітко зазначено»
• «Подзвонив інженер не був повідомлений вчасно, тому що шлях ескалації не був задокументований»

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

Визначити точний час

Розділ часової шкали часто є найбільш технічно складним для написання. Точність важлива.

Відомості про час:

• Процитовано 2014-02-14.  «At 14:32 UTC, the deployment of version 2.4.1 began.» (англійською)
• «Три хвилини потому, перші помилки 5xx з’явилися в панелі моніторингу.»
• Приблизно о 14:41 UTC** — на основі часових штампів журналу — рівень помилок перевищив 5% порог
• До 15:00 UTC**, 100% трафіку до служби оплати повертає помилки

** Послідовні сполучення: **

• «** Після** початкового відновлення, рівень помилок зменшився, але не повернувся до базисного рівня.»
• “Одночасно, команда бази даних почала досліджувати виснаження бази з’єднань.”
• “В результаті, було прийнято рішення про початок повного відновлення до версії 2.3.8.”

** Хеджування від непевності: **

• «Вважається, що проблема почалася до того, як було викликано попередження, на основі шаблону повільних запитів в журналах доступу»
• «Точна дата початку деградації невідома — журнали вказують, що вона могла початися ще в 14:20 UTC»

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

Записувати корекційні дії

Виправлення дій є найважливішою частиною постмортему — вони визначають, що насправді зміниться. Слабкі коригуючі дії використовують неясну мову; сильні дії є конкретними, власними і обмежені часом.

** Слабкий (уникайте): **

• «Покращення контролю»
• «Інженери повинні бути більш обережними з розгортанням»
• Нам потрібна краща документація

Сильний (використання):

• “Додати попередження про винятки платіжного процесора з порогом більше 10 помилок на хвилину. Власник: Команда платформи. Процитовано 2016-06-30. 
• « Оновити підручник розгортання, щоб включити обов’язковий перевірковий список перед розгортанням, який вимагає результатів тестів інтеграції. Власник: DevOps lead. Процитовано 2016-06-23. 
• “Запланувати перегляд всіх служб, у яких відсутній структурований журнал помилок. Власник: інженер-менеджер. Процитовано 2016-07-07.  2016-07-07

Формула для сильної виправної дії: ** дієслово дії + конкретний результат + власник + термін **.

Ключовий словник

Term	Definition
postmortem	A written analysis of an incident — what happened, why, and what will change
root cause	The fundamental underlying reason an incident occurred
contributing factor	A condition that made an incident more likely or more severe
MTTR	Mean Time to Recovery — average time to restore a service after failure
detection time	The time between an incident starting and the team becoming aware of it
blameless postmortem	A postmortem culture that attributes incidents to system failures, not individual blame
corrective action	A specific, owned, time-bound step to prevent a recurrence
outage duration	The total length of time a service was unavailable or degraded

Практичні поради

1. ** Спочатку напишіть хронологію, а потім аналіз. ** Відновлення подій у хронологічному порядку змушує вас бути точним щодо того, що ви знаєте, і що ви виводите. Ця дисципліна протікає через решту документа.
2. ** Використовуйте « система не зробила… » замість « ніхто не помітив… ». ** Якщо ви звинувачуєте когось, переформулюйте це як системну помилку: яке попередження, перевірка або процес мали б виявити це, але не зробили?
3. ** Відрізнити основну причину від факторів, що сприяють. ** Напишіть окреме речення для кожного. Якщо ви виявите, що перераховуєте більше ніж одну кореневу причину, перегляньте — зазвичай є одна, а інші є факторами, що сприяють.
4. ** Перечитайте кожну з виправлених дій і запитайте: хто робить що, до якого часу? ** Якщо ви не можете відповісти на всі три запитання, елемент дії не готовий.

Conclusion

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

Наприклад, англійська мова має такі категорії: непрямий і прямий

Будьмо чесними - постмортем може відчувати себе як мінне поле. Ціль полягає в тому, щоб навчитися на помилках, а не приписувати провину, але мова, яку ми використовуємо, часто повертається до традиційних шаблонів пошуку помилки. Для не-рідних англомовних носіїв, це може бути особливо складним завданням, оскільки нюансована фраза навколо відповідальності і підзвітності вимагає ретельного розгляду. Ключовим зсувом є відхід від фраз, які означають, що хтось “зробив щось не так” - наприклад, “він зробив помилку” або “вона була винною”. Замість цього, зосередьтеся на описі обставин, які призвели до проблеми. Точність у часових і детальних факторах також має вирішальне значення; неясність створює плутанину і перешкоджає ефективним виправленням. Це не про те, щоб визначити, хто «викликав» проблему, але зрозуміти * що * сталося і * чому *, зосереджуючись на спостережуваних фактах, а не суб’єктивних інтерпретаціях. Подумайте про це як про документування ланцюга подій - серії тригерів і реакцій - а не про вказування пальцем.

Розглянемо такий сценарій: Під час нещодавнього розгортання служба погіршилася через несподівану затримку мережі. Типовим (потенційно проблематичним) коментарем може бути: « Джон не стежив за мережею належним чином ». Це негайно негативно позначить Джона. Безвинний пост-морт замість цього стверджує: «Панелі моніторингу не вдалося попередити про тривале збільшення часу ping, перевищуючи визначений поріг 50 мс. Недавня зміна налаштувань балансування навантаження призвела до залежності від старішого сервера DNS, що призвело до періодичних перевиконання тайм- аута. Бачите різницю? Вона зосереджена на недоліках системи і процесу, а не на індивідуальній продуктивності. Іншою корисною фразою є « погіршився через » — замість « він погіршив ситуацію » ви можете написати « Проблема була погіршена через затримку у застосуванні останнього латку безпеки ». Це демонструє чітке розуміння факторів, які сприяли виникненню проблеми, без призначення відповідальності.

Для не-рідних носіїв особливо, активно вивчаючи і використовуючи такі фрази як «з-за», «в результаті», «зумовлені» (у чисто фактичному сенсі) і «під впливом» може значно поліпшити ясність і професіоналізм. Практика опису технічних ситуацій в цей спосіб буде будувати впевненість і плавність. Не бійтеся просити про пояснення - це цілком прийнятно сказати: “Чи можете ви допомогти мені переформулювати це, щоб переконатися, що це повністю бездоганно?” Більшість інженерів розуміють важливість цього підходу і раді запропонувати вказівки. Пам’ятайте, фокус завжди повинен бути на системних вдосконаленнях, а не на оцінці індивідуальної продуктивності.

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