Spark Web API - веб-интерфейс для мониторинга сервера

Spark Web API - плагин для Paper серверов Minecraft, который разворачивает локальное веб-API для получения данных от профайлера Spark. Если вы когда-нибудь хотели выводить статистику TPS, MSPT или загрузку процессора на внешний дашборд или в бота - это именно то, что нужно.

Зачем нужен этот плагин

Стандартный Spark отлично показывает данные прямо в игре через команду /spark health, но что если вы хотите мониторить сервер снаружи? Например, прикрутить графики к веб-панели или сделать бота в Discord/Telegram, который будет писать текущий TPS по запросу.

Обычный Spark не отдаёт данные по HTTP. Тут и пригодится Spark Web API - он поднимает маленький веб-сервер прямо внутри вашего Paper сервера и отдаёт метрики в JSON формате. Просто шлёте GET-запрос - получаете цифры. Никаких костылей с парсингом логов или консольных команд.

Установка на Paper сервер

Для начала - немного нюансов. Даже если у вас Paper для Minecraft 1.21+, где Spark уже встроен, вам всё равно понадобится отдельная версия плагина. Встроенный Spark не умеет отдавать данные наружу.

Порядок установки:

1. Скачайте и установите standalone версию Spark на ваш Paper сервер
2. Скачайте Spark Web API (берите JAR файл с -all в конце имени)
3. Закиньте оба плагина в папку plugins
4. При запуске сервера обязательно укажите системное свойство paper.preferSparkPlugin=true

Пример команды запуска:

java -Dpaper.preferSparkPlugin=true -jar paper-1.21-129.jar

Если не выставить paper.preferSparkPlugin, Paper может использовать встроенный Spark вместо плагин-версии, и Web API просто не заработает.

Совет от практика: На BungeeHost (https://bungee.host) этот плагин разворачивается в пару кликов - просто закиньте JAR в папку plugins через файловый менеджер и перезапустите сервер. Хостинг оптимизирован под Paper, так что проблем с портами или сетью не возникнет.

Конфигурация

При первом запуске плагин создаст конфиг-файл. Там можно настроить порт, выбрать какие маршруты включить, и добавить кастомные HTTP-заголовки к ответам.

yaml port: 3000 routes: tps: true mspt: true sys_cpu: false proc_cpu: false gc: false headers: enabled: false

По дефолту включены только TPS и MSPT - самые ходовые метрики. Системный и процессный CPU, а также GC выключены. Если они вам нужны - просто переключите false на true и перезапустите сервер.

API endpoints - что можно получить

Все ответы возвращаются в JSON. Базовый URL - http://ваш-сервер:порт/api/.

GET /api/tps - тики сервера

Возвращает TPS (тики в секунду) за 4 периода: 10 секунд, 1 минута, 5 минут, 15 минут.

{ "tenSeconds": 19.999926688268733, "oneMinute": 20.000035730063832, "fiveMinutes": 20.00000458740105, "fifteenMinutes": 19.94021043987079 }

Максимум - 20 TPS, это норма для здорового сервера. Если видите значения ниже 15-16 - сервер лагает, надо копать в сторону оптимизации.

Если Spark не может получить TPS, эндпоинт вернёт 500 Internal Server Error.

GET /api/mspt - миллисекунды на тик

MSPT (Milliseconds Per Tick) - более точная метрика, чем TPS. Показывает, сколько миллисекунд сервер тратит на обработку одного игрового тика. Возвращает данные за 10 секунд и 1 минуту, с разбивкой на min, max, mean и median.

{ "tenSeconds": { "min": 6.523605, "max": 2692.747083, "mean": 66.92731750515465, "median": 23.108289 }, "oneMinute": { "min": 6.523605, "max": 2692.747083, "mean": 66.92731750515465, "median": 23.108289 } }

Практический совет: Обращайте внимание на max - если он скачет до 2692 ms, значит в какой-то момент сервер жутко лагнул. Это может быть взрыв энтити, загрузка чанков или тяжёлый редстоун-краш. median (медиана) покажет типичную картину без учёта выбросов.

GET /api/gc - сборщик мусора

Информация о Garbage Collector (сборщике мусора Java). Показывает частоту, среднее время, количество сборок и общее время для каждого типа GC.

{ "G1 Young Generation": { "name": "G1 Young Generation", "frequency": 22328, "avgTime": 81, "totalCollections": 3, "totalTime": 243 }, "G1 Old Generation": { "name": "G1 Old Generation", "frequency": 0, "avgTime": 0, "totalCollections": 0, "totalTime": 0 } }

GC паузы - одна из главных причин микрофризов в Майнкрафт. Если avgTime растёт, а frequency падает - возможно, пора увеличить heap или сменить алгоритм сборщика.

GET /api/cpu/sys - загрузка системы

Загрузка CPU всей системы в процентах за 10 секунд, 1 минуту и 15 минут.

{ "tenSeconds": 0.20461582280862525, "oneMinute": 0.31800215079510524, "fifteenMinutes": 0.39118254849183964 }

GET /api/cpu/proc - загрузка процесса Minecraft

Загрузка CPU именно процессом сервера Minecraft. Тоже за три периода.

{ "tenSeconds": 0.025064927938294894, "oneMinute": 0.030417615615548597, "fifteenMinutes": 0.06684861042724896 }

Сравнивая системный и процессный CPU, можно понять - лагает сам сервер или на машине что-то другое жрёт ресурсы.

Сводная таблица эндпоинтов

Эндпоинт	Что возвращает	Периоды
/api/tps	TPS сервера	10с, 1м, 5м, 15м
/api/mspt	MSPT (мин, макс, сред, медиана)	10с, 1м
/api/gc	Статистика сборщика мусора	текущие данные
/api/cpu/sys	Загрузка CPU системы	10с, 1м, 15м
/api/cpu/proc	Загрузка CPU процесса Minecraft	10с, 1м, 15м

Для кого этот плагин

Spark Web API - must-have для админов, которые держат сервер на BungeeHost (https://bungee.host) и хотят мониторить его состояние не заходя в игру. Особенно полезен, если у вас есть веб-дашборд, бот или внешняя система алертов. Если вы просто играете с друзьями на домашнем сервере - вам это скорее всего не понадобится, обычного /spark health хватит за глаза.

Но если вы серьёзно подходите к администрированию - скачайте Spark Web API и настройте автоматический сбор метрик. Когда сервер начнёт лагать, вы увидите это на графиках ещё до того, как игроки начнут жаловаться.