A Bukkit plugin to exports Minecraft server metrics to Prometheus.
Built for Paper, Spigot, Bukkit, Folia (experimental) and other forks.
If you're running multiple Minecraft servers behind a BungeeCord proxy, you might also be interested in Bungeecord Prometheus Exporter for additional metrics!
Copy the prometheus-exporter.jar into your Bukkit plugins directory and start your Minecraft server.
After startup, the Prometheus metrics endpoint should be available at localhost:9940/metrics (assuming localhost is the server hostname).
The metrics port can be customized in the plugin's config.yml (a default config will be created after the first use).
The plugin exports a variety of metrics about your Minecraft server to Prometheus. These metrics can be used to monitor the health and performance of your server.
The metrics are exposed at localhost:9940/metrics by default. See the rest of the README for more information on how to configure Prometheus to scrape these metrics.
The plugin can be configured to perform custom health checks on your server. These checks can be used to monitor the health of your server and alert you if something goes wrong.
The aggregated health checks are exposed at localhost:9940/health by default.
See Health Checks for more information on how to build your own health checks in your plugins.
The default configuration file will be created after the first use of the plugin.
# Note that the HTTP server binds to localhost by default.
# If your Prometheus runs on another host or inside a Kubernetes cluster
# set this to any reachable IP or 0.0.0.0 to listen on all interfaces.
host: localhost
# The port can be changed in case it conflicts with any other application.
port: 9940
# Metrics can be enabled individually. Metrics which are disabled
# by default may have a performance impact on your server.
# See the rest of the README for more information.
enable_metrics:
jvm_threads: true
jvm_gc: true
players_total: true
whitelisted_players: true
entities_total: true
living_entities_total: true
loaded_chunks_total: true
jvm_memory: true
players_online_total: true
tps: true
tick_duration_average: true
tick_duration_median: true
tick_duration_min: false
tick_duration_max: true
player_online: false
player_statistic: falseAdd the following job to the scrape_configs section of your Prometheus configuration:
- job_name: 'minecraft'
static_configs:
- targets: ['localhost:9940']
labels:
server_name: 'my-awesome-server'You can use labels in your Prometheus scrape configuration to distinguish between multiple servers:
- job_name: 'minecraft'
static_configs:
- targets: ['localhost:9940']
labels:
server_name: 'server1'
- targets: ['localhost:9939']
labels:
server_name: 'server2'- Navigate to Grafana -> Dashboards -> Import
- Paste in or upload minecraft-server-dashboard.json
- Update "JVM Memory Used" to reflect your server max memory (Default 8G)
- Edit (bottom right widget) -> Options -> Gauage -> Max
You can also build your own dashboards using the metrics exported by the plugin. See available metrics for a list of all the metrics exported by the plugin.
The following metrics are exported by the plugin:
| Label | Description | Folia Support |
|---|---|---|
| mc_players_total | Unique players on server (online + offline) | ✅ |
| mc_whitelisted_players | Players count on the white list | ❌ |
| mc_loaded_chunks_total | Chunks loaded per world | ❌ |
| mc_players_online_total | Online players per world | ✅ |
| mc_entities_total | Entities loaded per world (living + non-living) | ❌ |
| mc_villagers_total | Villagers | ❌ |
| mc_world_size | World size in bytes | ✅ |
| mc_jvm_memory | JVM memory usage | ✅ |
| mc_jvm_threads | JVM threads info | ✅ |
| mc_tps | Server tickrate (TPS) | ❌ |
| mc_tick_duration_median | Median Tick Duration (ns, usually last 100 ticks) | ❌ |
| mc_tick_duration_average | Average Tick Duration (ns, usually last 100 ticks) | ❌ |
| mc_tick_duration_min | Min Tick Duration (ns, usually last 100 ticks) | ❌ |
| mc_tick_duration_max | Max Tick Duration (ns, usually last 100 ticks) | ❌ |
Warning
The following feature is against Prometheus best-practices and is not recommended for production servers.
There is an option to export per-player statistics like the number of blocks mined, mobs killed, items used, etc. The amount of data stored in Prometheus can dramatically increase when this is enabled as individual time-series will be generated for each player that has ever been seen on the server. The statistic collection may also have an impact on the Minecraft server performance for bigger servers but it has not been measured or tested.
On the other hand this should be quite safe for small private servers with limited players.
You can enable the experimental player export in the config.yaml.
enable_metrics:
player_online: true
player_statistic: trueThis will enable the additional metrics.
| Label | Description | Folia |
|---|---|---|
| mc_player_statistic | Player statistics | ❌ |
| mc_player_online | Online state by player name | ❌ |
There's an additional sample Grafana dashboard with player statistics enabled to get you started.
You can find the full list here. Use the "Resource location" for the metrics label with removing the "minecraft:" part and converted to uppercase. This doesn't support all statistics in the list because they are provided by the upstream Spigot libraries.
| Plugin version | Min Minecraft version | Min Java version |
|---|---|---|
| 3.x.x | 1.17.1 | 17 |
| 1.0.0 - 2.x.x | 1.11.x | 11 |
- Java 17 is required for the latest version of the plugin.
- There is a known issue with Azul JVM.
- There is currently rudimentary support for Folia servers. Only selected metrics are supported.
- The plugin has been tested recently on
- Minecraft 1.20.1
- Minecraft 1.20.4
By integrating your own plugin with the Minecraft Prometheus Exporter, you can:
- Monitor your plugin's performance: Collect metrics about your plugin's performance and resource usage.
- Provide custom health checks: Monitor the health of your plugin and alert you if something goes wrong.
You can easily collect metrics about your own plugin.
<dependency>
<groupId>io.prometheus</groupId>
<artifactId>simpleclient_common</artifactId>
<version>...</version>
</dependency>This pseudocode shows how you would count invocations of a plugin command.
public class MyPluginCommand extends PluginCommand {
// Register your counter
private Counter commandCounter = Counter.build()
.name("mc_my_plugin_command_invocations_total")
.help("Counter for my plugin command invocations")
.register();
@Override
public boolean execute(CommandSender sender, String commandLabel, String[] args) {
// Increment your counter;
commandCounter.inc();
// Do other stuff
return true;
}
}You can easily collect metrics about your own plugin.
- Get the latest
minecraft-prometheus-exporter-3.0.0.jarfrom the releases page. - Add the jar to your project's classpath.
Create your custom health check by extending the HealthCheck class.
public class CustomHealthCheck implements HealthCheck {
@Override
public boolean isHealthy() {
return true; // Your custom health check logic
}
}Register your health check in your plugin's onEnable method or similar.
This will add your health check to the list of health checks that are aggregated and exposed by the Minecraft Prometheus Exporter
public class MyPlugin extends JavaPlugin {
@Override
public void onEnable() {
// Register your health check
getServer().servicesManager.load(HealthChecks.class).add(new CustomHealthCheck());
}
}
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
![renovate[bot] avatar](https://avatars.githubusercontent.com/in/2740?v=4 "renovate[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent
