Як налаштувати geyser plugin для стрімінгу даних

Geyser plugin — це механізм Solana-валідатора, який дозволяє отримувати оновлення акаунтів, транзакцій та статусів слотів у реальному часі через спільну пам'ять (shared memory). На відміну від RPC-підписок, Geyser працює локально на машині валідатора і забезпечує мінімальну затримку, що робить його основним інструментом для індексації та стрімінгу даних у production-системах.

Нижче — покрокова інструкція від підготовки середовища до діагностики затримок, із конкретними конфігураційними параметрами та межами застосування.

Встановлення та конфігурація geyser

Підключення до валідатора

Передумови: працюючий Solana-валідатор (fullnode або archive), зібраний із підтримкою Geyser; доступ до конфігурації запуску валідатора; достатньо RAM для додаткових буферів спільної пам'яті.

Geyser plugin підключається як динамічна бібліотека (`.so` на Linux, `.dylib` на macOS) під час запуску валідатора. Валідатор завантажує бібліотеку та створює спільні пам'яткові буфери для обміну даними.

Увага: наведені приклади конфігурації слід розглядати як референсні. Точна схема параметрів залежить від версії Solana та конкретного плагіна. Перед застосуванням у production перевірте актуальну схему у вихідному коді плагіна та документації вашої версії.

Мінімальний конфігураційний файл для підключення плагіна містить такі ключові поля:

• libpath — абсолютний шлях до скомпільованої бібліотеки плагіна
• accounts_selector — фільтр акаунтів за публічними ключами або власниками
• transaction_selector — фільтр транзакцій за згаданими адресами

Валідатор запускається з додатковим прапорцем:

agave-validator ... --geyser-plugin-config /path/to/geyser-config.json

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

Очікуваний результат: у логах валідатора з'являються повідомлення про успішне завантаження плагіна та ініціалізацію буферів спільної пам'яті. Плагін готовий до прийому даних.

Перевірка: після запуску виконайте тестову транзакцію, що зачіпає акаунт із селектора, і переконайтеся, що оновлення надійшло на сторону споживача.

План відкату: видалити прапорець --geyser-plugin-config з команди запуску валідатора та перезапустити його. Плагін не залишає артефактів у стані валідатора.

Ризики: якщо плагін зазнає аварійного завершення, поведінка валідатора залежить від версії Solana — у деяких версіях це може призвести до збою валідатора. Обов'язково перевірте цю поведінку для вашої версії в тестовому середовищі перед розгортанням на production.

Формати виводу: JSON, gRPC, flatbuffers

Існують три основні офіційні плагіни, кожен із власним форматом серіалізації та протоколом доставки:

Вибір формату визначається архітектурою споживача:

• JSON — лише для розробки, логування або одноразової міграції даних. Не використовувати в production при високому throughput.
• gRPC — універсальний варіант для production, коли споживач даних знаходиться на окремій машині в тій самій дата-центровій мережі.
• FlatBuffers — коли потрібна максимальна продуктивність і споживач працює на тому самому вузлі, що й валідатор.

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

Оптимізація пропускної здатності

Пропускна здатність Geyser обмежена трьома факторами: розміром буферів спільної пам'яті, швидкістю серіалізації у плагіні та здатністю споживача обробляти дані без створення зворотного тиску (backpressure).

1. Розмір буферів спільної пам'яті. Кожен тип даних (акаунти, транзакції, статуси слотів) має окремий буфер. Якщо буфер заповнюється швидше, ніж плагін встигає його читати, оновлення втрачаються. Типові параметри, що потребують налаштування:

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

Орієнтир: якщо в логах валідатора фіксуються повідомлення про переповнення буфера (buffer overflow), збільште відповідний параметр. Контролюйте, щоб сумарний обсяг буферів не перевищував доступну RAM з урахуванням потреб самого валідатора.

2. Агресивна фільтрація через селектори. Найефективніший спосіб зменшити навантаження — не передавати зайві дані. Налаштуйте accounts_selector та transaction_selector максимально вузько:

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

3. Налаштування gRPC-параметрів. Для gRPC-плагіна:

• Стиснення — увімкніть deflate або gzip, якщо споживач і валідатор з'єднані через мережу. На локальному з'єднанні (loopback) стиснення може додати затримку без виграшу в пропускній здатності.
• Максимальний розмір фрейму — збільште значення за замовчуванням, якщо передаються великі акаунт-дані. Занадто малий фрейм призводить до фрагментації повідомлень і додаткових системних викликів.
• Потоки (streams) — gRPC-плагін підтримує множинні потоки. Розділіть логіку споживання за потоками, якщо це дозволяє архітектура downstream-системи.

4. Асинхронна обробка на боці споживача. Споживач повинен читати з gRPC-стріму або mmap-регіону без блокування. Якщо обробка одного повідомлення займає час, використовуйте чергу з окремим робочим пулом. Блокування читання створює зворотний тиск, який через спільну пам'ять впливає на валідатор і може спричинити втрату даних.

Діагностика затримок стріму

Затримка (latency) у Geyser-стрімі — це різниця між моментом, коли валідатор обробив слот, і моментом, коли споживач отримав відповідні оновлення. Діагностика вимагає послідовної ізоляції причини на кожному етапі конвеєра.

Крок 1. Вимірювання відставання за слотами. Найпростіший індикатор — різниця між поточним слотом валідатора та найновішим слотом у стрімі споживача. Отримайте поточний слот валідатора через RPC-виклик getSlot або з його логів. Порівняйте з максимальним слотом у отриманих оновленнях. Константне відставання понад 1–2 слоти вказує на проблему в конвеєрі.

Крок 2. Перевірка буферів спільної пам'яті. У логах валідатора шукайте повідомлення про переповнення буферів або пропущені оновлення. Якщо такі є, причина — у недостатньому розмірі буфера або повільній серіалізації в плагіні. Збільште буфер або перейдіть на легший формат (наприклад, з JSON на gRPC).

Крок 3. Перевірка навантаження CPU валідатора. Geyser-плагін працює в тому самому процесі, що й валідатор. Виміряйте частку CPU, яку споживає валідатор із підключеним плагіном, і порівняйте з базовим виміром без плагіна. Якщо різниця значна (особливо з JSON-плагіном при великій кількості оновлень), це пряма причина затримки — плагін конкурує за CPU з основною логікою консенсусу валідатора.

Крок 4. Діагностика мережевого сегмента (для gRPC). Якщо споживач на окремій машині:

• Виміряйте RTT між валідатором і споживачем. gRPC поверх TCP чутливий до джиттера (коливань затримки).
• Перевірте, чи не досягнуто ліміту кількості відкритих з'єднань або файлових дескрипторів на стороні валідатора.
• Увімкніть деталізоване логування gRPC-плагіна (якщо підтримується вашою версією) для фіксації часу відправки кожного повідомлення.

Крок 5. Перевірка споживача. Виміряйте час між отриманням повідомлення та його обробкою. Якщо черга споживача зростає, проблема не в Geyser, а в downstream-обробці. Моніторте розмір черги та час обробки одного повідомлення — саме тут найчастіше прихована причина затримки, яку помилково приписують Geyser.

Типові причини затримок за фактом:

• Буфер спільної пам'яті занадто малий для обсягу відфільтрованих даних — оновлення втрачаються або блокуються.
• JSON-серіалізація великих акаунт-даних створює CPU-вузьке місце в процесі валідатора.
• Споживач не встигає обробляти потік, зворотний тиск передається через спільну пам'ять і сповільнює запис.
• Мережевий джиттер між валідатором і віддаленим gRPC-споживачем при недостатній пропускній здатності каналу.

Межі застосування geyser plugin

Geyser plugin — потужний, але не універсальний інструмент. Розуміння його обмежень запобігає архітектурним помилкам на етапі проєктування.

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

Вплив на стабільність валідатора. Плагін завантажується в процес валідатора. Аварійне завершення плагіна може (залежно від версії Solana) призвести до збою валідатора. Це робить Geyser непридатним для підключення до валідаторів, де uptime є критичним і не може бути компенсований швидким перезапуском.

Відсутність історичних даних. Geyser стрімить лише поточні оновлення, починаючи з моменту підключення. Для отримання історичного стану акаунтів потрібен окремий механізм — snapshot, RPC-виклик getAccountInfo або архівний валідатор.

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

Обмеження flatbuffers-плагіна. Формат FlatBuffers вимагає, щоб споживач мав доступ до тих самих файлів mmap на файловій системі валідатора. Це унеможливлює віддалене споживання та ускладнює контейнеризацію — потрібен спільний volume між контейнерами валідатора та споживача.

Обмеження масштабування споживачів. Один gRPC-плагін обслуговує кількох споживачів, але залишається єдиним точковим вузлом. При великій кількості споживачів із різними потребами у фільтрації доцільніше запустити кілька екземплярів Geyser-плагінів із різними селекторами, а не фільтрувати все на одному споживачі.

Коли Geyser є правильним вибором:

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

Коли варто шукати альтернативи:

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

Джерела

• Solana Documentation: Staking
• Solana Documentation: Stake Accounts