TickScope is a lightweight Prometheus exporter for Minecraft Paper and Folia servers. The dependency-free plugin exposes tick health, players, per-world counters, JVM and CPU statistics, and player event counters for dashboards in Grafana.
mc_mspt_ms{quantile="p99"} 21.6336
mc_tps{window="1m"} 20.0
mc_players_online 4
mc_world_entities_by_type{world="world",type="chicken"} 35
- Exact p50, p95, and p99 tick times from Paper's raw tick-duration window
- Player-active regional TPS and average MSPT summaries where the Folia-compatible server API exposes them (including Canvas)
- Per-world entities, entity types, tile entities, chunks, and players
- JVM memory, threads, garbage collection, process CPU, and uptime
- No runtime dependencies, outbound telemetry, database, or embedded framework
- Main-thread-safe snapshots; HTTP scrapes never call Bukkit or block a tick
- Optional bearer authentication and failure-safe configuration reloads
- One jar for Paper and Purpur 1.18.2+, plus Folia and Canvas on supported modern releases
- Download the latest release.
- Put
TickScope-*.jarin the server'splugins/directory and restart. - Scrape the default endpoint at
http://127.0.0.1:9101/metrics.
scrape_configs:
- job_name: minecraft
static_configs:
- targets: ["127.0.0.1:9101"]The default endpoint is open but bound to loopback. When Minecraft runs in Docker, follow the Docker installation notes before changing the bind address. Configure bearer authentication and TLS whenever metrics cross a network you do not fully control.
Download the dashboard JSON, import it into Grafana, and select the Prometheus data source that scrapes TickScope. A built-in server selector supports one Paper server or a network of independently labeled backends.
The full manual lives in the TickScope wiki:
| Guide | Covers |
|---|---|
| Installation | Requirements, upgrades, Prometheus, and Docker |
| Configuration | Every setting, bearer authentication, and commands |
| Metrics reference | Metric names, labels, semantics, and PromQL notes |
| Grafana and Prometheus | Scrape, remote-write, and dashboard examples |
| Design and privacy | Architecture, collection cost, and security model |
| Troubleshooting | Compatibility, missing series, and lag diagnosis |
| Development and releases | Building, testing, releases, and support |
| Metric stability | Compatibility guarantees for names, labels, and semantics |
Paper 1.18.2+, Paper-compatible Purpur servers, Folia, and Folia-compatible Canvas servers are
supported. Spigot, Bukkit, Velocity, and BungeeCord are not supported. Install TickScope on each
backend in a proxy network and assign each server a unique server-id.
Paper exposes a single server tick, so TickScope publishes exact mc_mspt_ms, mc_tick_samples,
and mc_tps series there. Folia has no truthful server-wide equivalent. On Folia, those series are
intentionally absent and are replaced by mc_folia_region_tps summaries sampled at online player
locations. Servers exposing regional average tick times, including Canvas, also receive
mc_folia_region_mspt_ms; this is average MSPT per player-active region rather than a global
percentile. Entity-by-type metrics are disabled on Folia because a world-wide entity walk would
cross region ownership boundaries. Other server, world, player, event, JVM, and process metrics
remain available.
- Download on GitHub
- Download on Modrinth
- Report a bug
- Request a feature
- Ask a question
- Report a security issue privately
TickScope is maintained by Gabe Zimbric and licensed under GPL-3.0-or-later.