Monitoring Overview — Monitoring

Architecture

Minecraft server (plugin)
  │
  ├── Heartbeat (every 30 s)
  │     POST /api/v1/monitoring/heartbeat
  │
  ├── Metric snapshots (taken every 60 s, sent every 60 s)
  │     POST /api/v1/monitoring/metrics
  │
  └── Events (as they happen)
        POST /api/v1/monitoring/events
        │
        ▼
   voxelbench.com
        │
        ├── Raw snapshots (kept 48 h)
        ├── 5-minute aggregates (kept 7 days)
        ├── 1-hour aggregates (kept 30 days)
        ├── 1-day aggregates (kept 1 year)
        ├── Events (90 days; security and moderation: your plan's viewing period)
        └── Alert evaluation and notifications

Every request carries the server's link token. The intervals are plugin settings: remote-monitoring.collect-interval (60 seconds by default, 30 at least) sets how often a snapshot is taken, and remote-monitoring.send-interval (60 seconds by default, 60 at least) how often they are sent, up to 60 snapshots per request. When voxelbench.com cannot be reached, the plugin keeps the snapshots it could not send (120 by default) and sends them once the site answers again. The heartbeat interval is fixed. The settings are described in Configuration.

Collected Metrics

A snapshot describes the whole interval since the previous one, not a single instant:

Metric	Description
TPS	Ticks per second over the interval (target: 20)
MSPT	Average tick time in milliseconds, with the worst tick and the 95th percentile
Ticks over 50 ms, lag	Ticks that went over the 50 ms budget, and seconds spent below 18 TPS
Players	Players online, and the server's player slots
Entities, tile entities, loaded chunks	What the worlds hold
RAM	JVM heap used and maximum (MB), and heap still used after garbage collection
Process memory	Memory used by the whole Java process, and the container's memory limit (Linux)
CPU	The Java process (% of the whole machine), the whole machine (% of all processes), and the available cores
Garbage collection	Pause time and number of collections during the interval, and stop-the-world pause time
Ping, busiest worlds	Average player ping, and the three busiest worlds

On Folia, TPS and tick times carry the worst region, alongside the average over all regions and the detail of each region. A server paused by Minecraft because it is empty says so, and its tick figures are left out of the charts and of TPS and MSPT alerts. Snapshots never contain player names. Some of these fields need a recent plugin; an older one sends fewer. The exact fields are listed in Monitoring.

Data Retention

Data is automatically aggregated and cleaned up to keep storage efficient:

Granularity	Resolution	Retention
Raw	~1 point/minute	48 hours
5-minute	1 point/5min	7 days
1-hour	1 point/hour	30 days
1-day	1 point/day	1 year

This means you get minute-level precision for the last 2 days (one point per snapshot, every 60 seconds by default), 5-minute precision for the last week, hour-level precision for the last month, and one point a day for a year. How far back you can read depends on your plan (see Plans & Limits).

Events

Events	Retention
Lifecycle, performance, benchmark, custom	90 days
Security and moderation (they name players)	7 days on Pro, 30 days on Enterprise, 7 days once your plan has lapsed

On a hosting provider account, security and moderation events are kept 30 days.

Resolved alerts are kept 90 days. The content of each notification (email or Discord) is kept only until it is delivered, 24 hours at most; the record that it was sent (channel, status, time) is kept 30 days. If your plan has lapsed and VoxelBench has accepted nothing from a server for 30 days, all of its measurements and events are deleted. Deleting a server, or your account, deletes all of its monitoring data at once.

Online/Offline Detection

The plugin sends a lightweight heartbeat every 30 seconds. When no heartbeat has arrived for 90 seconds (three missed heartbeats), the server is shown as offline: fast enough to catch a crash, while tolerating a brief network hiccup.

The heartbeat also says how long ago the main thread last ticked, so the dashboard can tell apart a server that went quiet from one that is frozen (heartbeats still arrive, but no tick for 10 seconds), paused by Minecraft because it is empty, stopped on purpose, or whose monitoring was paused from the game. See Monitoring Dashboard for how each state is shown, and Metric Alert Rules to be warned.

Enabling Monitoring

Monitoring needs a plan that includes it (Pro, Enterprise or a hosting provider account) and two switches: one on VoxelBench, one in the plugin. The order does not matter.

Link your server to your account with /bench link (see Server Linking).
Turn it on at VoxelBench. Open Dashboard → Monitoring: under Set up monitoring, every linked server is listed with its switch. The same switch sits in the Monitoring tab of each server's settings (Dashboard → Servers → Manage).
Turn it on in the plugin. Run this in the server console, or in game with the voxelbench.monitor.web permission:
```
/bench monitor remote on
```
It writes remote-monitoring.enabled: true into the plugin's configuration, starts sending, and tells you in chat what is left to do. You can also edit plugins/VoxelBench/config.yml yourself:
```
remote-monitoring:
  enabled: true
```
then run /bench reload, which applies it: no restart is needed.

If the plugin starts sending before step 2, voxelbench.com refuses its data: the plugin pauses and checks again every minute (every 10 minutes while your plan does not include monitoring), then starts on its own. /bench monitor remote status shows where it stands.

The Monitoring page shows, for each server, three steps (Linked to your account, Turned on at VoxelBench, The plugin sends data), their real state, and what is still missing. Once data flows, the server appears under Monitored servers; open it for its dashboard.

To stop, run /bench monitor remote off: the plugin tells voxelbench.com that monitoring was paused on purpose, so it is not taken for a crash, then stops sending.

Plugin Older Than 1.9.0

These versions have no /bench monitor remote on, and start remote monitoring only when the server starts: /bench reload does not start it. Turn monitoring on at VoxelBench first, then set enabled: true in config.yml and restart the server. A plugin that sends while monitoring is still off at VoxelBench is refused, writes enabled: false back into its config and stops; if that happened, set it to true again and restart. Updating the plugin removes both constraints.