Операційні вимоги для «Incident runbook: типовий план реагування на інцидент валідатора» перевірено 2 серпня 2026 року. Для production використовуйте тільки реліз Agave, рекомендований для конкретного кластера, і звіряйте параметри з agave-validator --help . Офіційні вимоги Anza на цю дату орієнтують операторів на Ubuntu 24.04, щонайменше 12 ядер/24 потоки, 256 ГБ RAM, окремі швидкі NVMe та симетричний канал від 2 Гбіт/с; це рекомендації, а не гарантія достатньої продуктивності.

Incident runbook — це структурований набір інструкцій, який визначає послідовність дій оператора під час порушення нормальної роботи валідатора Solana. На відміну від загальних рекомендацій, runbook містить конкретні команди, порогові значення метрик, журнали для перевірки та критерії прийняття рішень. Його мета — мінімізувати час відновлення (MTTR) та запобігти ескалації інциденту.

Цей документ орієнтований на середовище з клієнтом Agave (колишній agave-validator), операційною системою Ubuntu 24.04 LTS та кластером mainnet-beta. Конкретні версії та шляхи слід перевірити у вашому інфраструктурному реєстрі перед застосуванням команд.

Що таке incident runbook

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

Ефективний runbook для валідатора містить такі обов'язкові елементи:

  • Ознаки інциденту — конкретні метрики, алерти або стани, які сигналізують про проблему (наприклад, skip rate вище 5% протягом 5 хвилин).
  • Передумови перевірки — мінімальний набір даних, який треба зібрати перед будь-якими діями (стан сервісу, останні записи журналу, мережева досяжність).
  • Послідовність кроків — впорядкований список дій із зазначенням очікуваного результату після кожного кроку.
  • Критерії ескалації — умови, за яких оператор зупиняє самостійне відновлення та залучає інших учасників інфраструктури.
  • Шлях відкату — дії для повернення до попереднього стану, якщо крок відновлення призвів до погіршення ситуації.

Runbook не замінює моніторинг, а працює в парі з ним: моніторинг виявляє відхилення, runbook визначає реакцію.

Класифікація інцидентів

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

P1: валідатор зупинився або delinquent

Найвищий рівень критичності. Валідатор не бере участі в консенсусі або позбавлений кредитів (delinquent). Ознаки:

  • Стан сервісу inactive або процес не існує.
  • Статус delinquent у команді solana validators або через RPC-запит до getVoteAccounts.
  • Відстань від root slot до останнього слота кластера перевищує епоху (приблизно 432 000 слотів для mainnet-beta).
  • Абсолютна відсутність записів у журналі валідатора протягом останніх 60 секунд за умови, що кластер активний.

Час початку реагування: негайно. Максимальний час до першої діагностичної дії — 5 хвилин.

P2: високий skip rate або повільна синхронізація

Валідатор працює, але якість участі в консенсусі деградувала. Ознаки:

  • Skip rate перевищує 5% протягом 5 хвилин (значення треба підтвердити через метрики вашої системи моніторингу, а не за одиничним заміром).
  • Відстань від root slot до останнього слота кластера стабільно зростає, але не досягла порогу delinquent.
  • Час обробки слота (slot processing time) стабільно перевищує 400 мс при нормативних значеннях близько 150–200 мс.
  • Кількість оптимістичних підтверджень (optimistic confirmations) знизилася або дорівнює нулю.

Час початку реагування: протягом 15 хвилин з моменту спрацьовування алерту.

P3: попередження моніторингу

Потенційна проблема, яка ще не вплинула на консенсус, але може ескалатувати. Ознаки:

  • Зростання використання ОЗП понад 80% від виділеного обсягу.
  • Зростання черги RPC-запитів або збільшення часу відповіді RPC-ендпоінтів.
  • Дискова черга вводу-виводу (IO wait) перевищує 20% протягом 10 хвилин.
  • Одноразовий стрибок skip rate до 2–5% з наступним відновленням.
  • Попередження в журналі валідатора рівня WARN, що повторюються (наприклад, Failed to fetch entry from neighbors).

Час початку реагування: протягом 1 години. Дії можуть бути відкладені до робочого часу, якщо інцидент не ескалує.

Кроки реагування для кожного рівня

Реагування на P1

Крок 1. Перевірка стану процесу та сервісу.

Середовище: Ubuntu 24.04 LTS, systemd.

Команда:

systemctl status agave-validator.service

Очікуваний результат: активний стан (active/running). Якщо стан inactive або failed — перейдіть до кроку 2. Якщо active — перейдіть до кроку 3.

Крок 2. Аналіз журналу перед перезапуском.

Команда:

journalctl -u agave-validator.service --no-pager -n 200

Шукайте: panic, out of memory, fatal, assertion failed. Якщо виявлено out of memory — перевірте наявність dump-файлу в /var/crash/ та переконайтеся, що параметр OOMScoreAdjust у конфігурації systemd налаштовано коректно. Не перезапускайте сервіс без аналізу причини зупинки — це може призвести до повторної аварії та пошкодження стану.

Крок 3. Перевірка мережевої досяжності сусідів.

Команда:

solana gossip --num-nodes 10

Очікуваний результат: не менше 5 сусідів з актуальними слотами. Якщо сусідів менше або їхні слоти застарілі — проблема в мережі, а не в самому валідаторі. Перевірте правила фаєрвола, зокрема порти 8000–8020 (UDP/TCP) та 8800 (UDP).

Крок 4. Перезапуск сервісу (тільки після виконання кроків 1–3).

Команда:

sudo systemctl restart agave-validator.service

Одразу після перезапуску:

journalctl -u agave-validator.service -f

Очікуваний результат: журнал показує завантаження леджера, підключення до gossip-мережі та початок обробки слотів. Якщо протягом 120 секунд не з'явилися записи про обробку слотів — ескалюйте інцидент.

Крок 5. Перевірка прогресу синхронізації.

Команда:

solana catchup <IDENTITY_PUBKEY>

Очікуваний результат: відсоток catchup зростає. Якщо значення None або не зростає протягом 30 секунд — перевірте доступність snapshot-серверів та вільний місце на диску.

Ризики кроку 4: Перезапуск під час активної синхронізації може призвести до повторного завантаження snapshot, що займає значний час. Якщо валідатор не delinquent, а лише відстає, розгляньте можливість дочекатися природного наздоганяння перед перезапуском.

Шлях відкату: Якщо після перезапуску валідатор не може завантажити леджер, перевірте цілісність останнього snapshot та за потреби відновіть з резервної копії каталогу леджера.

Реагування на P2

Крок 1. Збір діагностичних даних.

Команда:

solana validator-info <IDENTITY_PUBKEY>

Зафіксуйте: поточний слот, root slot, skip rate, версію клієнта.

Крок 2. Перевірка ресурсів сервера.

Команди:

free -h
iostat -x 1 3
mpstat 1 3

Очікуваний результат: вільна ОЗП не менше 20%, iowait не більше 10%, завантаження CPU не перевищує кількість ядер. Якщо будь-який показник виходить за межі — проблема в інфраструктурі, а не в клієнті.

Крок 3. Перевірка стану акаунта валідатора.

Команда:

solana vote-account <VOTE_PUBKEY>

Перевірте: чи не заблоковано акаунт, чи достатньо SOL для оплати транзакцій голосування (мінімально близько 0.5 SOL на рахунку vote account, але точне значення залежить від поточного тарифу).

Крок 4. Перевірка підключених сусідів та їхньої якості.

Команда:

solana gossip --num-nodes 20 | sort -k5 -n -r | head -10

Якщо більшість сусідів мають низький stake або високу латентність — розгляньте оновлення списку entrypoints у конфігурації.

Крок 5. Перевірка наявності оновлень клієнта.

Команда:

agave-validator --version

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

Реагування на P3

Крок 1. Фіксація попередження.

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

Крок 2. Перевірка тренду.

Оцініть, чи є це разове відхилення чи частина зростаючого тренду. Для цього перегляньте метрики за останні 24 години. Зростаючий тренд використання ОЗП або дискового вводу-виводу може свідчити про наближення P2.

Крок 3. Профілактичні дії.

Залежно від типу попередження: очистка старих snapshot-файлів, перевірка налаштувань зберігання леджера (ledger retention), перегляд конфігурації моніторингу на предмет хибних алертів.

Комунікація під час інциденту

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

Правила комунікації за рівнями:

  • P1: Негайне сповіщення всієї інфраструктурної команди. Якщо інцидент стосується делегованого стейку — сповіщення делегаторів протягом 30 хвилин з першою оцінкою ситуації. Подальші оновлення — кожні 30 хвилин або при зміні статусу. Формат: факт → вплив → поточні дії → наступне оновлення.
  • P2: Сповіщення інфраструктурної команди. Делегатори інформуються лише у разі ескалації до P1 або якщо інцидент триває більше 1 години.
  • P3: Фіксація в системі обліку без активного сповіщення. Включається до регулярного звіту.

Формат першого повідомлення при P1:

Час: [UTC]. Валідатор [identity pubkey] зупинився / став delinquent. Причина попередньо невідома. Почато діагностику за runbook P1. Наступне оновлення через 30 хвилин або раніше за наявності результатів.

Поширені помилки комунікації:

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

Post-mortem: аналіз після інциденту

Post-mortem проводиться після кожного інциденту рівня P1 та за рішенням команди — після P2, що тривав більше 1 години або мав нетипову причину. Мета — не знайти винного, а виявити системну вразливість.

Обов'язкові розділи post-mortem:

  • Хронологія — точний час виявлення, початку реагування, кожного ключового кроку та повного відновлення. Усі часові позначки в UTC.
  • Вплив — кількісна оцінка: тривалість простою, кількість пропущених слотів, втрата кредитів, вплив на делегаторів (без вигадування цифр — лише підтверджені дані).
  • Коренева причина — найглибший рівень причини, який можна усунути. Наприклад, не «процес зупинився через OOM», а «відсутність моніторингу вільної ОЗП з попередженням при 80% призвела до того, що зростання споживання не було виявлено до моменту kill».
  • Що спрацювало добре — елементи runbook, моніторингу або комунікації, які прискорили відновлення.
  • Що потребує покращення — конкретні кроки з призначеними відповідальними та термінами.

Типові помилки post-mortem:

  • Формальний підхід: опис без аналізу причини, що призводить до повторення інциденту.
  • Надмірна деталізація журналу без виділення ключових моментів прийняття рішень.
  • Відсутність конкретних action items із термінами та відповідальними.

Оновлення runbook на основі досвіду

Кожен завершений post-mortem має призводити до оновлення runbook. Якщо інцидент розкрив сценарій, не описаний у поточній версії, runbook треба доповнити. Якщо існуючий крок виявився неефективним — його треба змінити.

Правила оновлення:

  • Додавання нового сценарію: лише після підтвердження, що ситуація не є одноразовою аномалією. Одноразові аномалії фіксуються в post-mortem, але не обов'язково стають частиною runbook.
  • Зміна порогових значень: тільки на підставі даних моніторингу за тривалий період (не менше 2 тижнів). Наприклад, якщо skip rate 5% як поріг P2 виявився надто чутливим і спричиняв хибні алерти, нове значення обґрунтовується статистикою спрацьовувань.
  • Зміна команд: кожна команда, що вноситься до runbook, має бути перевірена на тестовому середовищі або, щонайменше, на валідаторі, що не бере участі в mainnet.
  • Версіонування: кожне оновлення runbook фіксується з датою, описом змін та посиланням на post-mortem, що став підставою.

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

Наступний логічний крок: після налаштування runbook інтегруйте його кроки у систему моніторингу як автоматизовані або напівавтоматизовані процедури (playbooks), щоб зменшити залежність від ручної реакції оператора в критичні перші хвилини інциденту.

Джерела