TickScope — Minecraft monitoring for Prometheus and Grafana

Upgrading from 1.x: 2.0 changes several metric names and expresses tick duration and ping in seconds. Update dashboards and alerts with the migration guide.

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_tick_duration_seconds{statistic="p99"} 0.0216
mc_tps{window="1m"} 20.0
mc_players_online 4
mc_world_entities_by_type{world="world",type="chicken"} 35

Highlights

• 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

Quick start

1. Download the latest jar from the Files tab at the top of this page.
2. Put TickScope-*.jar in the server's plugins/ directory and restart.
3. 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.

Grafana dashboard

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.

Collection health and alerting

Track collection freshness and failures even when the HTTP endpoint remains reachable. Folia sampling publishes partial coverage and bounds outstanding work per player. World exclusions and an entity-type allowlist help control collection scope.

See health metrics, filters, and setup instructions, the Prometheus alert rules, and the optional per-server dashboard.

Documentation

The full manual lives in the TickScope wiki. See the 2.0 metric migration guide for changed names and units.

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

Compatibility

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.

Minecraft 26.3 is listed for compatibility, and CI compiles against its Paper API. Paper's 26.3 server builds are currently alpha; runtime compatibility has not been smoke-tested.

Paper exposes a single server tick, so TickScope publishes exact mc_tick_duration_seconds, 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_tick_duration_seconds; this is average tick duration per player-active region rather than a global percentile. Per-world entity totals, tile-entity totals, and the entity-type breakdown are unavailable on Folia, because walking a world crosses region ownership boundaries; per-world chunk and player counts, and all other server, player, event, JVM, and process metrics, remain available.

On Paper those three series come from a slower scan (entity-types.interval-ticks, 600 ticks by default). It inspects at most entity-types.chunks-per-tick loaded chunks on each tick, 32 by default. A scan may therefore span multiple ticks; its totals are an approximate view of the world over that interval.

Support

• 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.