diff --git a/CHANGELOG.md b/CHANGELOG.md index 5f115051..f9f3bc01 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [v3.0.0] - 2024-02-29 + +### Added +- [#198](https://github.com/sladkoff/minecraft-prometheus-exporter/issues/198): Add rudimentary support for Folia (see README.md for limitations) + +### Changed +- [#228](https://github.com/sladkoff/minecraft-prometheus-exporter/pull/228): [Breaking] Update minimum Java version to 17 + +### Fixed +- [#155](https://github.com/sladkoff/minecraft-prometheus-exporter/issues/155): World size metric lags server with big world +- [#208](https://github.com/sladkoff/minecraft-prometheus-exporter/issues/208): Failed to find tick times buffer via reflection in 1.20.4 +- [#226](https://github.com/sladkoff/minecraft-prometheus-exporter/pull/226): Server lags when exporting chunk and player metrics + ## [v2.6.0] - 2024-01-02 Special thanks to all new and old contributors :star: @@ -158,6 +171,7 @@ Special thanks to all new and old contributors :star: ### Added - Initial exporter +[v3.0.0]: https://github.com/sladkoff/minecraft-prometheus-exporter/compare/v2.6.0...v3.0.0 [v2.6.0]: https://github.com/sladkoff/minecraft-prometheus-exporter/compare/v2.5.0...v2.6.0 [v2.5.0]: https://github.com/sladkoff/minecraft-prometheus-exporter/compare/v2.4.2...v2.5.0 [v2.4.2]: https://github.com/sladkoff/minecraft-prometheus-exporter/compare/v2.4.1...v2.4.2 diff --git a/README.md b/README.md index 5f38e67c..a61560b5 100644 --- a/README.md +++ b/README.md @@ -8,21 +8,25 @@ # Minecraft Prometheus Exporter -A **Bukkit plugin** which exports Minecraft server stats for Prometheus. +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](https://github.com/weihao/bungeecord-prometheus-exporter) for additional metrics! ## Quick Start -Drop the prometheus-exporter.jar into your Bukkit plugins directory and start your Minecraft server. +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). -## Plugin config +## Installation & Configuration + +### Plugin config -Here's a default config with annotations. +The default configuration file will be created after the first use of the plugin. ```yml # Note that the HTTP server binds to localhost by default. @@ -53,11 +57,11 @@ enable_metrics: player_statistic: false ``` -## Prometheus config +### Prometheus config Add the following job to the ``scrape_configs`` section of your Prometheus configuration: -### Single server +#### Single server ```yml - job_name: 'minecraft' @@ -67,7 +71,7 @@ Add the following job to the ``scrape_configs`` section of your Prometheus confi server_name: 'my-awesome-server' ``` -### Multiple servers +#### Multiple servers You can use labels in your Prometheus scrape configuration to distinguish between multiple servers: @@ -82,16 +86,18 @@ You can use labels in your Prometheus scrape configuration to distinguish betwee server_name: 'server2' ``` -## Import Grafana Dashboard +### Import Grafana Dashboard 1. Navigate to Grafana -> Dashboards -> Import 1. Paste in or upload [minecraft-server-dashboard.json](https://raw.githubusercontent.com/sladkoff/minecraft-prometheus-exporter/master/dashboards/minecraft-server-dashboard.json) 1. Update "JVM Memory Used" to reflect your server max memory (Default 8G) 1. Edit (bottom right widget) -> Options -> Gauage -> Max -## Available metrics +You can also build your own dashboards using the metrics exported by the plugin. See [available metrics](#available-metrics) for a list of all the metrics exported by the plugin. + +### Available metrics -These are the stats that are currently exported by the plugin. +The following metrics are exported by the plugin: | Label | Description | Folia Support | |--------------------------|----------------------------------------------------|---------------| @@ -110,7 +116,7 @@ These are the stats that are currently exported by the plugin. | mc_tick_duration_min | Min Tick Duration (ns, usually last 100 ticks) | ❌ | | mc_tick_duration_max | Max Tick Duration (ns, usually last 100 ticks) | ❌ | -## Player metrics (experimental!) +### Player metrics (experimental!) :warning: **The following feature is against Prometheus best-practices and is not recommended for production servers!** @@ -136,18 +142,38 @@ This will enable the additional metrics. | mc_player_statistic | Player statistics | ❌ | | mc_player_online | Online state by player name | ❌ | -There's a sample [dashboard](https://raw.githubusercontent.com/sladkoff/minecraft-prometheus-exporter/master/dashboards/minecraft-players-dashboard.json) -available to get you started. +There's an additional sample [Grafana dashboard](https://raw.githubusercontent.com/sladkoff/minecraft-prometheus-exporter/master/dashboards/minecraft-players-dashboard.json) +with player statistics enabled to get you started. You can find the full list [here](https://minecraft.fandom.com/wiki/Statistics#List_of_custom_statistic_names). 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. -## Collect metrics about your own plugin +### Compatibility + +| 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 | + +#### Notes + +– Java 17 is required for the latest version of the plugin. +- There is a known [issue](https://github.com/sladkoff/minecraft-prometheus-exporter/issues/197) 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 + +## Plugin Integration + +By integrating your own plugin with the Minecraft Prometheus Exporter, you can **monitor your plugin**: Collect metrics about your plugin's performance or usage. + +### Collect metrics about your own plugin You can easily collect metrics about your own plugin. -### Include the Prometheus dependency +#### Include the Prometheus dependency ```xml @@ -157,9 +183,9 @@ You can easily collect metrics about your own plugin. ``` -### Collect metrics +#### Collect metrics -This pseudo code shows how you would count invocations of a plugin command. +This pseudocode shows how you would count invocations of a plugin command. ```java public class MyPluginCommand extends PluginCommand { @@ -171,7 +197,7 @@ public class MyPluginCommand extends PluginCommand { .register(); @Override - public boolean execute​(CommandSender sender, String commandLabel, String[] args) { + public boolean execute(CommandSender sender, String commandLabel, String[] args) { // Increment your counter; commandCounter.inc(); @@ -183,24 +209,3 @@ public class MyPluginCommand extends PluginCommand { } ``` - -### Compatibility - -#### Minecraft Server - -##### Officially supported - -> 1.11.x – 1.20.x - -##### Tested -- 1.20.1 -- 1.20.4 - -#### Java - -- Java 11 or higher is required (Java 8 is not supported due to [this issue](https://github.com/sladkoff/minecraft-prometheus-exporter/issues/161)) -- There is a known [issue](https://github.com/sladkoff/minecraft-prometheus-exporter/issues/197) with Azul JVM - -#### Folia - -There is currently rudimentary support for Folia servers. Only selected metrics are supported. diff --git a/pom.xml b/pom.xml index af3c5634..8e62bf29 100644 --- a/pom.xml +++ b/pom.xml @@ -6,7 +6,7 @@ de.sldk.mc minecraft-prometheus-exporter - 2.6.1-SNAPSHOT + 3.0.0 jar diff --git a/src/main/java/de/sldk/mc/MetricsController.java b/src/main/java/de/sldk/mc/MetricsController.java index 029b3e6e..2e7f9982 100644 --- a/src/main/java/de/sldk/mc/MetricsController.java +++ b/src/main/java/de/sldk/mc/MetricsController.java @@ -10,6 +10,7 @@ import org.eclipse.jetty.server.Response; import org.eclipse.jetty.util.Callback; +import java.io.IOException; import java.io.OutputStreamWriter; import java.nio.charset.StandardCharsets; import java.util.logging.Level; @@ -25,7 +26,7 @@ public MetricsController(PrometheusExporter exporter) { @Override - public boolean handle(Request request, Response response, Callback callback) throws Exception { + public boolean handle(Request request, Response response, Callback callback) { try { metricRegistry.collectMetrics().get(); @@ -44,9 +45,9 @@ public boolean handle(Request request, Response response, Callback callback) thr return true; } - private void writeMetricsToResponse(Request request, Response response) throws Exception { - try (var out = Response.asBufferedOutputStream(request, response); - var writer = new OutputStreamWriter(out, StandardCharsets.UTF_8)) { + private void writeMetricsToResponse(Request request, Response response) throws IOException { + var out = Response.asBufferedOutputStream(request, response); + try (var writer = new OutputStreamWriter(out, StandardCharsets.UTF_8)) { TextFormat.write004(writer, CollectorRegistry.defaultRegistry.metricFamilySamples()); writer.flush(); } diff --git a/src/main/resources/plugin.yml b/src/main/resources/plugin.yml index a5b47c70..d0026677 100644 --- a/src/main/resources/plugin.yml +++ b/src/main/resources/plugin.yml @@ -1,7 +1,7 @@ name: PrometheusExporter -version: 2.6.1-SNAPSHOT +version: 3.0.0 author: sldk main: de.sldk.mc.PrometheusExporter -website: sldk.de +website: https://github.com/sladkoff/minecraft-prometheus-exporter api-version: 1.16 folia-supported: true