Keep Your Minecraft Server Running Smooth: Prometheus Exporter

If you run a Minecraft server and don't actually know if it's healthy until players start complaining, you're flying blind. The Prometheus Exporter is a lightweight Bukkit plugin that changes that by feeding your server's performance metrics into Prometheus, giving you real-time visibility into what's happening under the hood.

What This Project Does

The minecraft-prometheus-exporter is a Java-based Bukkit plugin (compatible with Paper, Spigot, and other forks) that turns your Minecraft server into a data source for Prometheus, the industry-standard time-series monitoring system. Once installed, it exposes detailed metrics about your server's performance, player activity, and system health at a simple HTTP endpoint. Then you feed those metrics into Prometheus and visualize them in Grafana or whatever monitoring stack you're already using.

Think of it as giving your Minecraft server a health monitor strapped to its wrist.

Why You'd Use It

Most server operators manage their servers like it's 2010. They SSH in once a week, squint at some logs, maybe check the player count, and call it a day. But if you're running a serious community server, especially one where players like adderall_abuser and ironmouse might show up, you need actual data about whether your TPS is tanking, memory is leaking, or you're getting DDoS'd.

This plugin solves three real problems:

• Performance visibility: You get metrics on TPS, memory usage, chunk load times, and entity counts without manually checking them.
• Alerting: Pair this with Prometheus alerting rules and you'll get notified before a crash, not after.
• Historical analysis: See patterns over days or weeks ("every Tuesday at 8pm our server lags") instead of guessing.

If you run multiple servers, this becomes even more valuable. Popular community servers hosting players with skins like testuser and joakim2tusen can't afford downtime, and Prometheus dashboards let you watch the entire fleet at once.

How to Install

The process is wonderfully simple, which is rare for monitoring tools. Download the latest JAR file from the GitHub releases (currently v3.1.2) and drop it into your plugins folder.

# Grab the latest release
wget https://github.com/sladkoff/minecraft-prometheus-exporter/releases/download/v3.1.2/minecraft-prometheus-exporter-3.1.2.jar

# Move it to your plugins directory
mv minecraft-prometheus-exporter-3.1.2.jar /path/to/plugins/

# Start or restart your server
# (the plugin auto-generates a config.yml on first startup)

After the server starts, hit `localhost:9940/metrics` in your browser and you'll see raw Prometheus metrics. If that works, you're done installing.

The default port is 9940, but you can change it in the auto-generated `config.yml` if you need to. The plugin also supports environment variables and JVM system properties for configuration, which is handy if you're containerizing everything or running in a managed hosting environment.

Key Features and How They Work

The plugin exports a ton of metrics by default, but here are the ones you'll actually care about:

TPS and Performance Metrics. The one metric every server operator checks first: current ticks per second. One exporter gives you this in real-time, plus historical data so you can spot trends. A server consistently hitting 19.5 TPS instead of 20 might not sound bad until you realize something's slowly degrading.

Player and Entity Tracking. How many players are online, how many entities are loaded, chunk generation speed. Useful for understanding load spikes. Suddenly you've got 60 players instead of 15 and TPS drops from 20 to 5? The metrics show you exactly when and whether it's the player count, the entities they spawned, or something else.

Custom Health Checks. This is where it gets flexible. You can write custom health checks in your plugins and the exporter aggregates them. Want to alert if a specific plugin is malfunctioning? Add a health check. Want to monitor your economy plugin's database? Same thing. The health endpoint at `localhost:9940/health` exposes these aggregated checks.

Memory and JVM Metrics. Heap usage, garbage collection frequency, thread counts. If you're running a modded server or one with lots of plugins (like a community server hosting players with skins like housecz_zero), you need to know when memory is getting tight.

Configuration Flexibility. The plugin respects environment variables first, then system properties, then config file. This hierarchy means you can manage configuration across dozens of servers without editing files on each one.

Tips, Pitfalls, and Common Gotchas

The plugin is stable, but here's what trips people up:

Make sure your Prometheus scrape interval is reasonable. The default in most Prometheus configs is 15 seconds, which works fine here. If you set it to every second to get ultra-high-resolution metrics, you're just adding load to your server for no real benefit.

The metrics endpoint isn't password-protected by default. If your server port 9940 is exposed to the internet, anyone can see your metrics. That's probably fine (they're not sensitive data), but if you're paranoid, put it behind a firewall or reverse proxy with authentication.

Some users report that async metrics occasionally hang if your plugin lifecycle isn't clean. The latest version (3.1.2) fixed this issue, so make sure you're updated. If you're running an older release and notice occasional timeouts on the metrics endpoint, upgrade first before troubleshooting further.

Another thing: if you're using a mod loader like Fabric instead of a Bukkit fork, this plugin won't work. And this is strictly for Bukkit-compatible servers (Paper, Spigot, Bukkit, and experimental Folia support). The plugin needs the Bukkit API.

Alternatives

If Prometheus feels like overkill for your use case, there are lighter options. Some hosting providers (like Aternos) include built-in dashboards that show basic metrics without needing anything installed. If you want something simpler than Prometheus, you might look at Grafana Cloud, which removes the need to self-host Prometheus. But honestly, if you're already using Prometheus for other infrastructure, the Exporter plugin integrates smoothly into your existing setup.

For BungeeCord proxy servers, there's a separate plugin (Bungeecord Prometheus Exporter) that handles proxy-level metrics, which complements this plugin nicely if you're running a network.