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

Середовище перевірки: клієнт Agave (актуальна стабільна гілка), кластер mainnet-beta, Ubuntu 24.04 LTS, systemd, червень 2025. Конкретну версію та githash підтвердіть у своєму середовищі командою agave-validator --version.

Логи валідатора — це єдине джерело достовірної інформації про стан ноди в реальному часі. Без системного підходу до їх аналізу оператор діє наосліп: не бачить наближення десинхронізації, пропускає дискові деградації та втрачає час на діагностику після фактичного відстеження. Цей матеріал дає практичний інструментарій для читання, фільтрації та інтерпретації логів Agave.

Де знаходяться логи валідатора

Розташування логів залежить від того, як запущено процес валідатора.

systemd (рекомендований спосіб). Усі stdout та stderr процесу потрапляють у journald. Фізичних файлів у файловій системі за замовчуванням немає — журнали зберігаються у бінарному форматі journald і обертаються автоматично відповідно до налаштувань /etc/systemd/journald.conf. Перевірити, чи ваш сервіс пише туди:

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

Файловий вивід (параметр --log). Якщо у файлі сервісу або в командному рядку вказано --log /path/to/agave-validator.log, Agave пише у вказаний файл у текстовому вигляді. Цей файл росте без обмеження, якщо ви не налаштували зовнішню ротацію (logrotate). Перевірте наявність цього параметра:

systemctl cat agave-validator.service | grep -- "--log"

Одночасний вивід. Agave може писати і в journald, і у файл одночасно, якщо вказано --log при запуску під systemd. Це корисно для резервного копіювання логів, але вимагає контролю вільного місця на диску.

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

Формат логів Agave

Agave використовує бібліотеку tracing (Rust). У стандартному (не-JSON) режимі кожен рядок має таку структуру:

[2025-06-10T14:23:01.456789Z INFO solana_core::replay_stage] replayed 320 shreds for slot 254876321

Розбір полів зліва направо:

  • Таймстемп — UTC, наносекундна точність, формат ISO 8601.
  • Рівень логування — один із п'яти рівнів tracing: ERROR, WARN, INFO, DEBUG, TRACE. Рівень за замовчуванням визначається змінною середовища RUST_LOG (типово info).
  • Модуль (target) — шлях до модуля Rust, що генерує повідомлення (наприклад, solana_core::replay_stage, solana_runtime::bank, solana_ledger::snapshot_utils). Це найважливіше поле для фільтрації: воно дозволяє ізолювати логи конкретної підсистеми.
  • Повідомлення — текстове описання події. Може містити числові значення (слоти, кількість shred-ів, розміри), але не має парсити структуровані поля.

JSON-формат. Увімкнення --log-format json змінює вивід на структурований JSON-об'єкт на кожен рядок. Це необхідно, якщо ви відправляєте логи в Loki, Elasticsearch або інший лог-аналізатор, який очікує структуровані дані. У JSON-режимі з'являються додаткові поля: target, span (контекст трасування), іноді shred_version та інші метадані залежно від модуля.

Ризик при зміні формату: перемикання з текстового формату на JSON або навпаки не вимагає перезапуску валідатора, якщо ви змінили лише конфігурацію логування. Але якщо ви змінили аргументи командного рядка — потрібен перезапуск сервісу, що означає коротку паузу в валідації.

Ключові типи повідомлень

Інформаційні: старт, синхронізація, snapshot

Ці повідомлення (рівень INFO) підтверджують нормальне функціонування. Ключові події, за якими слідкувати:

  • Старт валідатора: повідомлення від модуля solana_core::validator про успішну ініціалізацію, завантаження identity ключа, підключення до gossip-мережі.
  • Синхронізація: solana_rpc::rpc_subscriptions та solana_core::replay_stage повідомляють про обробку shred-ів, прогрес по слотах. Якщо ви бачите стабільний потік цих повідомлень — нода синхронізована.
  • Snapshot: solana_ledger::snapshot_utils повідомляє про створення та завантаження snapshot-ів. Формат типово містить слот snapshot-у та розмір.

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

Попередження: висока latency, пропущені слоти

Рівень WARN вказує на деградацію, яка ще не призвела до відмови, але потребує уваги:

  • Висока latency: повідомлення про затримку обробки слотів, перевищення таймаутів у replay stage. Часто пов'язане з навантаженням на CPU або дискову підсистему.
  • Пропущені слоти (skipped slot): валідатор не встиг обробити слот у відведений час. Окремі пропущені слоти — норма для мережі. Серійні пропуски — ознака проблеми.
  • Gossip-попередження: модуль solana_gossip може попереджати про обмеження кількості peer-з'єднань або проблеми з discovery.

Дія оператора: при появі WARN-повідомлень перевірте метрики (CPU, disk I/O, мережу) і збільште деталізацію логування для проблемного модуля, якщо потрібно.

Помилки: відмови підключення, дискові помилки

Рівень ERROR означає критичну подію:

  • Відмови підключення: неможливість з'єднатися з певними peer-ами або RPC-клієнтами. Може бути як наслідком зовнішньої проблеми (мережа), так і ознакою бану вашої IP-адреси.
  • Дискові помилки: помилки запису/читання в модулях solana_ledger::blockstore та solana_ledger::snapshot_utils. Це найнебезпечніший тип помилок — якщо диск не справляється, валідатор ризикує десинхронізацією.
  • Помилки верифікації shred-ів: solana_core::shred повідомляє про невдалу перевірку криптографічних підписів або цілісності даних.

Будь-яке ERROR-повідомлення вимагає негайної перевірки. Навіть одинична помилка диска може бути ознакою початку каскадної відмови.

Фільтрація та пошук у логах

Головна проблема логів валідатора — обсяг. Продукційна нода генерує сотні повідомлень на секунду. Без фільтрації знайти потрібне неможливо.

Фільтрація за рівнем. Базова і найчастіша операція — відокремити помилки від інформаційного шуму:

journalctl -u agave-validator.service -p err --no-pager

Фільтрація за модулем. Якщо ви знаєте, яка підсистема проблемна, ізолюйте її логи. Наприклад, тільки replay stage:

journalctl -u agave-validator.service --no-pager | grep "solana_core::replay_stage"

Фільтрація за часом. Звужуйте вікно до моменту інциденту:

journalctl -u agave-validator.service --since "2025-06-10 14:00:00" --until "2025-06-10 14:05:00" --no-pager

Комбінована фільтрація. Реальний сценарій: помилки диска за останню годину:

journalctl -u agave-validator.service -p err --since "1 hour ago" --no-pager | grep -i "blockstore\|snapshot"

Контекстна фільтрація. Щоб побачити кілька рядків навколо знайденого повідомлення (контекст події), використовуйте -C у grep:

journalctl -u agave-validator.service --no-pager | grep -C 5 "Bank stage failed"

Це показує 5 рядків до та 5 рядків після кожного збігу, що дозволяє зрозуміти, які події передували помилці.

Інструменти: journalctl, grep, лог-аналізатори

journalctl — основний інструмент для systemd-сервісів. Ключові параметри для щоденної роботи:

  • -f — режим слідкування (tail -f аналог). Ідеально для моніторингу в реальному часі.
  • -n [кількість] — показати останні N рядків.
  • --since / --until — часове вікно. Приймає формати: "2025-06-10 14:00:00", "1 hour ago", "yesterday".
  • -p [рівень] — фільтрація за пріоритетом (err, warn, info, debug).
  • --output=json — вивід у JSON-форматі для подальшої обробки.
  • --disk-usage — показати, скільки місця journald займає на диску.

grep — для шаблонного пошуку всередині потоку логів. Корисні патерни:

  • grep -i "error" — регістронезалежний пошук (Agave використовує великі літери для рівнів, але повідомлення можуть містити "error" у нижньому регістрі).
  • grep -E "WARN|ERROR" — одночасний пошук кількох рівнів.
  • grep -v "solana_rpc" — виключення модуля (корисно, щоб прибрати шум від RPC-запитів).

Лог-аналізатори. Для постійного моніторингу логів на продакшені journalctl та grep недостатні. Типовий стек:

  • Promtail + Loki + Grafana — найпоширеніший варіант у Solana-інфраструктурі. Promtail збирає логи з journald, Loki зберігає та індексує, Grafana дає дашборди з фільтрацією за рівнем, модулем, слотом.
  • ELK (Elasticsearch, Logstash, Kibana) — потужніший, але важчий у обслуговуванні. Підходить для великих інфраструктур з кількома нодами.
  • Vector — альтернатива Promtail з кращою продуктивністю та підтримкою складних трансформацій логів до відправки в Loki або Elasticsearch.

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

Типові патерни помилок у логах

Нижче наведено перевірені патерни, які зустрічаються найчастіше. Для кожного вказано модуль-джерело, текст повідомлення та рекомендовану дію.

1. Дискові помилки запису (blockstore)

Модуль: solana_ledger::blockstore

Ознаки: повідомлення про помилки fsync, No space left on device, Input/output error.

Дія: негайно перевірте df -h та smartctl. Якщо диск деградує — міняйте та відновлюйте з snapshot-у. Детальна діагностика дискових проблем із snapshot-ами розглядається в окремому матеріалі про діагностику snapshot failures.

2. Відставання за слотами (fork too old)

Модуль: solana_core::replay_stage, solana_core::fork_choice

Ознаки: повідомлення fork too old, dropping fork, стабільне зростання відстані до найвищого слота.

Дія: перевірте CPU та мережу. Якщо відстань перевищує кілька сотень слотів і не зменшується — готуйтеся до відновлення з snapshot-у. Процедура повного відновлення описана в матеріалі про відновлення валідатора після повної втрати даних.

3. Помилки gossip-мережі

Модуль: solana_gossip::gossip_service

Ознаки: failed to add peer, gossip pull request failed, різке зменшення кількості peer-з'єднань.

Дія: перевірте мережеве з'єднання сервера, наявність фаєрвола, що блокує UDP/TCP порти gossip-мережі. Перевірте, чи не змінилася ваша IP-адреса.

4. Помилки верифікації shred-ів

Модуль: solana_core::shred

Ознаки: shred verification failed, invalid shred.

Дія: одиничні помилки верифікації — нормальне явище в мережі (можуть бути пов'язані з атаками або пошкодженнями в транзиті). Якщо помилки масові — перевірте стан пам'яті (ECC-помилки) та мережевий інтерфейс.

5. Вичерпання ресурсів

Ознаки: процес валідатора зникає з journalctl без повідомлення про graceful shutdown; у dmesg або /var/log/syslog з'являються повідомлення Out of memory: Killed process від OOM killer.

Дія: перевірте dmesg -T | grep -i oom. Якщо підтверджується — збільште RAM або зменште параметри валідатора (наприклад, --limit-ledger-size).

6. Дублікати слотів (duplicate slot)

Модуль: solana_core::replay_stage

Ознаки: duplicate slot, duplicate fork.

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

Загальне правило: будь-яка помилка, що повторюється більше ніж 5–10 разів на хвилину, або будь-яка одиночна дискова помилка — це привід для негайного розслідування. Не чекайте, поки помилка переросте в десинхронізацію.

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

Джерела