minecraft-prometheus-exporter - GitLite

KO | EN

gitlite — search

#javascript #python #go #rust #deep-learning #nodejs #awesome #cli #kubernetes #awesome-list #pytorch #ios #mcp #openai

minecraft-prometheus-exporter

(★ 539)

A Bukkit plugin which exports minecraft server stats to Prometheus

파일 탐색기

최종 버전 다운로드 (.zip)

- - bug_report.md
  - feature_request.md
  - question.md
- - release.yml
  - test.yml
- FUNDING.yml
- stale.yml
- - minecraft-player-statistic-screenshot.png
  - minecraft-player-statistic.json
  - minecraft-screenshot.png
  - minecraft.json
- minecraft-general-dashboard.json
- minecraft-players-dashboard.json
- minecraft-server-dashboard.json
.gitignore
CHANGELOG.md
docker-compose.yml
LICENSE.md
pom.xml
README.md
renovate.json

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/sladkoff/minecraft-prometheus-exporter

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd minecraft-prometheus-exporter

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. Docker

쉬움 추천

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Docker Desktop 컨테이너를 빌드하고 실행하려면 필요합니다. 설치 후 실행해서 백그라운드에 켜두세요.

docker compose up -d --build

정의된 모든 컨테이너(서버, DB 등)를 한 번에 빌드하고 백그라운드에서 실행합니다.

✅ 터미널에 docker compose ps 를 입력해 컨테이너들이 Up 상태인지 확인하세요. README에 포트 번호가 적혀있다면 브라우저에서 http://localhost:포트번호 로 접속해보세요.

3. Maven (Java)

보통

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
JDK (Java) Java 프로젝트를 빌드/실행하려면 필요합니다.
Maven mvn 명령어를 쓰기 위한 빌드 도구입니다.

mvn clean install

Maven으로 의존성 설치와 빌드를 진행합니다.

✅ BUILD SUCCESS 메시지가 뜨면 성공입니다. target/ 폴더에 결과물이 생성됩니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![](https://img.shields.io/github/v/release/sladkoff/minecraft-prometheus-exporter?style=flat-square)](https://github.com/sladkoff/minecraft-prometheus-exporter/releases/latest)
[![](https://img.shields.io/github/issues-raw/sladkoff/minecraft-prometheus-exporter?style=flat-square)](https://github.com/sladkoff/minecraft-prometheus-exporter/issues)
[![](https://img.shields.io/github/license/sladkoff/minecraft-prometheus-exporter?style=flat-square)](https://github.com/sladkoff/minecraft-prometheus-exporter/blob/master/LICENSE.md)
[![](https://img.shields.io/badge/donate-Buy%20me%20a%20coffee-orange.svg?style=flat-square)](https://www.buymeacoffee.com/sldk)
[![](https://img.shields.io/discord/695717895451181156?color=%20%237289da&label=discord&style=flat-square)](https://discordapp.com/invite/Bh2M2tM)
[![](https://img.shields.io/gitter/room/sladkoff/minecraft-prometheus-exporter?style=flat-square)](https://gitter.im/minecraft-prometheus-exporter/community)

# Minecraft Prometheus Exporter

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

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

## Feature Overview

### Prometheus Exporter

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.

### Custom Health Checks

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](#health-checks) for more information on how to build your own health checks in your plugins.

## Installation & Configuration

#### Configuration Hierarchy

The Prometheus metrics exporter plugin supports multiple configuration sources for the HTTP endpoint (host/port). The configuration is applied in the following order of priority:

1. **Environment Variables:**
  - `MINECRAFT_PROMETHEUS_EXPORTER_HOST`
  - `MINECRAFT_PROMETHEUS_EXPORTER_PORT`  
    If these environment variables are set, their values will override all other settings.

2. **System Properties:**
  - `minecraft.prometheus.exporter.host`
  - `minecraft.prometheus.exporter.port`  
    If the environment variables are not provided, the plugin checks these system properties. They can be set when launching the JVM.

3. **Configuration File:**  
   If neither environment variables nor system properties are defined, the plugin falls back to the values in the configuration file.

### Plugin config

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.
# 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.
#
# These settings can be overridden by environment variables or system properties.
# Environment variables:
#   - MINECRAFT_PROMETHEUS_EXPORTER_HOST: Overrides the host setting (e.g., 0.0.0.0)
#   - MINECRAFT_PROMETHEUS_EXPORTER_PORT: Overrides the port setting (e.g., 9001)
#
# System properties (set during JVM startup):
#   -Dminecraft.prometheus.exporter.host=0.0.0.0
#   -Dminecraft.prometheus.exporter.port=9001
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: false
```

### Prometheus config

Add the following job to the ``scrape_configs`` section of your Prometheus configuration:

#### Single server

```yml
- job_name: 'minecraft'
  static_configs:
    - targets: ['localhost:9940']
      labels:
        server_name: 'my-awesome-server'
```

#### Multiple servers

You can use labels in your Prometheus scrape configuration to distinguish between multiple servers:

```yml
- job_name: 'minecraft'
  static_configs:
    - targets: ['localhost:9940']
      labels:
        server_name: 'server1'
    - targets: ['localhost:9939']
      labels:
        server_name: 'server2'
```

### 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

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

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)     | ❌             |

### Player metrics

> [!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.

```yaml
enable_metrics:
  player_online: true
  player_statistic: true
```

This 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](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.wiki/w/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.

### 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:

1. **Monitor your plugin's performance**: Collect metrics about your plugin's performance and resource usage.
2. **Provide custom health checks**: Monitor the health of your plugin and alert you if something goes wrong.

### Collect metrics about your own plugin

You can easily collect metrics about your own plugin.

#### Include the Prometheus dependency

```xml
<dependency>
    <groupId>io.prometheus</groupId>
    <artifactId>simpleclient_common</artifactId>
    <version>...</version>
</dependency>
```

#### Collect metrics

This pseudocode shows how you would count invocations of a plugin command.

```java
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;
  }

}
```

### Provide a health check from your own plugin

You can easily collect metrics about your own plugin.

#### Add compile-time dependency to your plugin

1. Get the latest `minecraft-prometheus-exporter-3.0.0.jar` from the [releases](https://github.com/sladkoff/minecraft-prometheus-exporter/releases) page.
2. Add the jar to your project's classpath.

#### Create a health check

Create your custom health check by extending the `HealthCheck` class.

```java
public class CustomHealthCheck implements HealthCheck {
    @Override
    public boolean isHealthy() {
        return true; // Your custom health check logic
    }
}
```

#### Register the health check

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

```java
public class MyPlugin extends JavaPlugin {

@Override
    public void onEnable() {
      // Register your health check
      getServer().servicesManager.load(HealthChecks.class).add(new CustomHealthCheck());
    }
}
```