Тримати Minecraft-сервер просто — доки щось не починає гальмувати і ніхто не може пояснити чому. ServerScope — відповідь Etoryx на цю прогалину: платформа моніторингу та спостережуваності для серверів Paper і Folia, що перетворює стан сервера на те, на що справді можна дивитися — живі метрики, збережена історія, сповіщення, вебпанель і JSON API.
Це розповідь про те, як він проєктувався і які рішення його сформували.
Проблема невидимості стану сервера
Більшість проблем із продуктивністю на Minecraft-сервері непомітні, доки не починають заважати. Сервер почувається нормально, потім підвантажується чанк, підскакує кількість сутностей або плагін робить забагато роботи під час події — і гравці раптом помічають лаги.
Стандартні інструменти відповідають лише на найзагальніше питання. Одне число тікрейту каже, що щось не так, але не де. Адміністратор лишається гадати між світами, чанками та плагінами і часто перезапускає сервер, просто щоб прибрати симптом, який так і не діагностував.
ServerScope виходить із простої засади: адміністратор має могти подивитися на сервер і зрозуміти його стан — просто зараз і в динаміці — без під'єднання зовнішнього профайлера й читання сирих логів.
Що ставить за мету ServerScope
Мета — операційна видимість на Paper і Folia, реалізована через кілька пов'язаних підсистем, а не через одну команду:
- безперервно збирати живі метрики й зберігати обмежену історію;
- діагностувати проблеми та піднімати сповіщення зі зрозумілими рівнями важливості;
- відкривати все через ігрові команди, вебпанель і JSON API;
- лишатися достатньо дешевим, щоб працювати у продакшені постійно.
Інструмент моніторингу, що помітно погіршує те, що він вимірює, провалився. Низькі накладні витрати — це функція, а не приємне доповнення.
Усередині архітектури
ServerScope побудований як набір взаємодійних модулів, а не як моноліт:
- Колектори безперервно збирають операційні метрики.
- Сховище зберігає дані в SQLite — асинхронно, пакетно й з обмеженням розміру, щоб записи не блокували сервер, а база не росла безмежно.
- Діагностика та сповіщення аналізують зібрані дані й формують повідомлення за рівнями важливості.
- Рушій профілювання спостерігає за вибраним набором подій Bukkit/Paper.
- Вебсервер віддає і панель, і JSON API.
Саме збереження даних відрізняє живий показник від справжньої спостережуваності. Оскільки історія живе в SQLite (serverscope-mvp.db), а не лише в пам'яті, тренди зберігаються і їх можна вивчити вже після того, як момент минув, — а не лише глянути на них у реальному часі.
Сумісність з Paper і Folia
Folia змінює правила. Замість одного основного потоку сервер ділиться на регіони, що тікають незалежно в пулі потоків. Код, який припускає один глобальний основний потік, на Folia не просто повільніший — він некоректний.
ServerScope ставиться до потоків як до першочергової турботи, а не як до цілі порту:
| Аспект | Paper | Folia |
|---|---|---|
| Планування | Глобальний планувальник | Регіональні / глобальний планувальники |
| Спільний стан | Один основний потік | Володіння за регіонами |
| Безпечний доступ | Основний потік | Потік регіону-власника |
Практичне правило плагіна — ніколи не читати й не змінювати стан сервера з неправильного потоку та повністю прибирати сховище й вебсервер зі шляху тіків. Він розрахований на Paper або Folia 1.21+ і Java 21+.
Що плагін робить сьогодні
Ці можливості є в проєкті в його теперішньому вигляді.
Він безперервно збирає ключові сигнали — TPS, MSPT, тренди кількості сутностей, продуктивність чанків і профілі виконання подій плагінів. Рушій профілювання спостерігає за подіями на кшталт player_interact, block_break, block_place, entity_damage, inventory_click і creature_spawn, позначаючи повільні, часті чи аномальні.
Коли щось виходить за межі, система сповіщень реагує за важливістю: сповіщення CRITICAL доходять до адмінів у грі, а повідомлення рівня WARN з'являються в консолі та вебінтерфейсі — для умов на кшталт низького TPS, високого MSPT, надлишку сутностей або незвичної активності чанків.
Усе доступне трьома способами: через ігрові команди, вбудовану вебпанель і JSON API.
/serverscope
/serverscope status
/serverscope reload
/serverscope report
/serverscope findings
/serverscope alerts
/serverscope web regenerate-token
Вебшар за замовчуванням слухає 127.0.0.1:8080 і захищений автоматично згенерованим токеном для кожного сервера (перевипускається командою web regenerate-token). Він підтримує CORS і зворотні проксі, застосовує налаштовуване обмеження частоти запитів і обмежує відповіді 2 МБ JSON. Доступ регулюється гранульованими правами на кшталт serverscope.admin і serverscope.alerts.
Обмеження та проєктні рішення
Більшу частину роботи визначили два обмеження.
Перше — накладні витрати. Монітор, що навантажує сервер, суперечить власній меті, тож дорогі частини навмисно тримаються поза гарячим шляхом: записи у сховище асинхронні, пакетні й обмежені, а вебсервер працює незалежно від циклу тіків.
Друге — коректність на Folia. Підтримка регіонної моделі потоків — це не прапорець, який вмикають; це припущення, що проходить крізь увесь код. Закладати його від самого початку виявилося значно дешевше, ніж доробляти потім.
Безпека отримала таке саме ставлення — за замовчуванням, а не заднім числом: панель слухає localhost і вимагає токен з коробки, тож її публікація — це свідомий вибір, а не випадковість.
Висновки і що далі
Найясніший висновок: спостережуваність — це збереження даних плюс стриманість. Зберігання обмеженої історії перетворює миттєвий показник на те, що справді можна розслідувати, а винесення кожного дорогого шляху за межі циклу тіків і робить це безпечним для живого сервера.
Якщо хочете прочитати код або спробувати його на своєму сервері — і те, й інше відкрите:
- Modrinth: ServerScope на Modrinth
- GitHub: Etoryx/ServerScope
Якщо ви плануєте плагін або мод для Minecraft і хочете, щоб його робили з тією ж турботою про накладні витрати й коректність на платформі, напишіть мені — це саме те, чим займається Etoryx.