Using spark with clan.me

clan.me soft-depends on spark. If spark is installed on your server, the clan.me plugin reads TPS, MSPT, and CPU directly from spark's API on every heartbeat. If spark is not installed, everything falls back to the plugin's own native measurement with no change in behaviour.

What spark adds

With spark installed, your dashboard gains four things it can't collect otherwise:

• Trusted TPS — read directly from spark's API, the same source as /spark tps. This eliminates the occasional discrepancy between what spark reports and what the clan.me dashboard shows.
• MSPT percentiles — p95 and p99 tick times alongside the mean. These catch spikes that an average smooths over. Shown as sub-values under the MSPT card in the Snapshot panel.
• System CPU % — system-level CPU utilisation from spark's cpuSystem() API. A metric the clan.me plugin cannot collect without spark. Shown in the Snapshot panel and charted over time in the Server Health section.
• MSPT on Spigot — MSPT normally requires Paper's getAverageTickTime() API, which Spigot does not expose. When spark is installed on a Spigot server, clan.me reads MSPT from spark instead, giving Spigot servers real tick-time data.

A small “via spark” tag appears in the Snapshot freshness header whenever spark is the metrics source, so you always know where the numbers came from.

Auto-detection

No configuration is required. When the clan.me plugin starts, it checks for spark in two ways:

1. Via the Bukkit plugin manager (catches spark installed as a standalone plugin).
2. Via Class.forName() (catches spark bundled internally in Paper 1.21+, which is not registered as a plugin but is available on the classpath).

If either check succeeds, spark is used for all subsequent heartbeats. The console logs Metrics source: spark at startup so you can confirm detection. There is no spark-related setting in config.yml.

Metrics from spark

The clan.me plugin calls three spark API methods on every heartbeat:

• spark.tps() — returns TPS for 10s, 1m, 5m, and 15m windows. clan.me uses the 1m, 5m, and 15m values.
• spark.mspt() — returns mean(), percentile(0.95), and percentile(0.99) tick times.
• spark.cpuSystem() — returns system CPU utilisation across time windows. clan.me stores the most recent value.

All spark calls are wrapped in try/catch Throwable, so an API version mismatch will fail silently and fall back to native measurement rather than crashing the heartbeat task.

MSPT on Spigot

On a plain Spigot server without spark, the MSPT card in your Snapshot reads “Paper only” and the MSPT bars are hidden from the TPS chart. This is because Spigot does not expose the getAverageTickTime() API that MSPT measurement normally requires.

With spark installed on Spigot, clan.me reads MSPT from spark instead. The Snapshot card shows a real tick-time value, the p95 sub-value appears alongside it, and the TPS chart gains MSPT bars. This is a genuine capability gain, not available without spark on Spigot.

Without spark

Roughly 70% of clan.me servers run without spark. Everything below works identically whether spark is installed or not:

• TPS (1m, 5m, 15m) from Bukkit's native API
• Heap memory usage and JVM GC pressure
• Entity and chunk counts per world
• Player sessions, new vs returning, retention, player roster
• Server config snapshot, plugin list, restart history
• All eight alert types across all four delivery channels

spark is additive. Installing it after you've already been running clan.me adds CPU and MSPT percentile history going forward. There is no retroactive backfill, but all new heartbeats will carry the enriched data immediately.

For the full integration overview, see the spark integration page.