⚠️ Statistics are present only in Java Edition. Bedrock Edition has no equivalent of statistics in-game ⚠️

Minecraft Exporter for Prometheus

This is a Prometheus Minecraft exporter, created as part of the minectl 🗺 project.

It collects metrics from different sources of the game

• RCON
• NBT Files
• Advancement file
• Player stats file

Getting started

Short getting started guide with systemd unit file on ubuntu linux

Create Systemd unit file

tee /etc/systemd/system/minecraft-exporter.service <<EOF
[Unit]
Description=Minecraft Exporter
Wants=network-online.target
After=network-online.target
[Service]
User=minecraft_exporter
Group=minecraft_exporter
Type=simple
ExecStart=/usr/local/bin/minecraft-exporter \
  --mc.rcon-password=<rcon password if needed>
[Install]
WantedBy=multi-user.target
EOF

Install Minecraft Exporter

MINECRAFT_EXPORTER_VERSION=0.6.1
curl -sSL https://github.com/dirien/minecraft-prometheus-exporter/releases/download/v$MINECRAFT_EXPORTER_VERSION/minecraft-exporter_$MINECRAFT_EXPORTER_VERSION.linux-$ARCH.tar.gz | tar -xz
cp minecraft-exporter /usr/local/bin
chown minecraft_exporter:minecraft_exporter /usr/local/bin/minecraft-exporter
systemctl start minecraft-exporter.service
systemctl enable minecraft-exporter.service

RCON

RCON is a protocol that can be used to remotely execute commands to your Minecraft server.

To enable rcon on your minecraft server add the following to the java field in your minectl manifest:

    ...
    java:
      xmx: 2G
      xms: 2G
      rcon:
        password: test
        port: 25575
        enabled: true
        broadcast: true
    edition: java
      ...

See server config examples for details and usage of the minectl 🗺 manifest file.

Alternatively you need to edit your server.properties on your server.

Be sure that following flags are set for the minecraft-exporter binary:

--mc.rcon-address=":25575"  
--mc.rcon-password=<rcon-password>

or

export MC_RCON_ADDRESS=":25575"
export MC_RCON_PASSWORD=<rcon-password>

Files

To access the files, take care that the minecraft-exporter binary is started with the flag

Details for the specific stats can be found here -> https://minecraft.fandom.com/wiki/Statistics

--mc.world=path/to/world

or

export MC_WORLD=path/to/world

API

Due to restrictions of the API from mojang https://api.mojang.com/user/profiles/[uuid]/names we switched to the project of Electroid

Mojang, the developers of Minecraft, provides multiple APIs for websites and servers to fetch identity information about users. Requests do not accept authentication tokens, however they are heavily rate limited and fragmented among several endpoints. The purpose of this project is to package several of the most commonly used APIs into a single GET request with no rate limiting and no need for client-side caching.

Usage ⚙

usage: minecraft-exporter [<flags>]

Flags:
  -h, --help                     Show context-sensitive help (also try --help-long and --help-man).
      --web.config.file=""       [EXPERIMENTAL] Path to configuration file that can enable TLS or authentication.
      --web.telemetry-path="/metrics"  
                                 Path under which to expose metrics.
      --web.listen-address=":9150"  
                                 Address to listen on for web interface and telemetry.
      --web.disable-exporter-metrics  
                                 Disabling collection of exporter metrics (like go_*)
      --mc.config-path="config.yml"  
                                 Path to YAML file with config.
      --mc.world="/minecraft/world"  
                                 Path the to world folder
      --mc.rcon-address=":25575"  
                                 Address of the Minecraft rcon.
      --mc.rcon-password=MC.RCON-PASSWORD  
                                 Password of the Minecraft rcon.
      --mc.name-source="mojang"  How to retrieve names of players: offline, bukkit, mojang.
      --mc.mod-server-stats=MC.MOD-SERVER-STATS  
                                 Additional server stats for papermc, purpurmc, forge, or fabric.
      --log.level=info           Only log messages with the given severity or above. One of: [debug, info, warn, error]
      --log.format=logfmt        Output format of log messages. One of: [logfmt, json]
      --version                  Show application version.

Config 🔧

You can override CLI flags using config file. By default, config.yml located in the current directory is used. Path to config file can be changed using --config-path CLI flag.

Key in config file	Equivalent CLI flag	ENV variable	Description
metrics-path	--web.telemetry-path	WEB_TELEMETRY_PATH	Path under which to expose metrics.
listen-address	--web.listen-address	WEB_LISTEN_ADDRESS	Address to listen on for web interface and telemetry.
disable-exporter-metrics	--web.disable-exporter-metrics	WEB_DISABLED_EXPORTER_METRICS	Disabling collection of exporter metrics (like go_*)
web-config	--mc.config-path	MC_CONFIG_PATH	Path to YAML file with config for the mc variables
world-path	--mc.world	MC_WORLD	Path to the world folder.
rcon-address	--mc.rcon-address	MC_RCON_ADDRESS	Address for the Minecraft RCON.
rcon-password	--mc.rcon-password	MC_RCON_PASSWORD	Password for the Minecraft RCON.
name-source	--mc.name-source	MC_NAME_SOURCE	How to retrieve names of players: offline, bukkit, mojang.
mod-server-stats	--mc.mod-server-stats	MC_MOD_SERVER_STATS	Set server for additional stats (papermc, purpurmc, forge, or fabric)

Disable exporter metrics

With the flag --web.disable-exporter-metrics you can disable collection of exporter metrics (like go_*). This is useful if you want just see the minecraft metrics and not the exporter metrics.

Disabling metrics

To disable certain metrics, just add corresponding key to disabled-metrics section with true value in your config file. You should use keys that used by Minecraft to store players' stats.

Example config (--mc.config-path/MC_CONFIG_PATH)

disabled-metrics:
  minecraft:bred_animals: true # Disable "minecraft_animals_bred_total" metric
  minecraft:creeper: true # Disable all metrics related with creepers
  minecraft:custom: false # "false" values will be ignored, so this line does nothing
listen-address: ':9151' # Change address of web server. "--web.listen-address" will be ignored if this line is present here

Known Issues ⚠️️

minecraft-exporter is heavily dependent on the username of the player. If you are using mods like EssentialsX and hide or change the default grouping of players, then minecraft-exporter will may not work properly.

If you encounter any issues, please let me know by opening an GitHub issue in this repository.

Collectors 📊

The exporter collects a number of statistics from the server (with example of the labels):

```bash

HELP minecraft_animals_bred_total The number of times the player bred two mobs

TYPE minecraft_animals_bred_total counter

minecraft_animals_bred_total{player="ediri"} 0

HELP minecraft_bells_rung_total The number of times the player rang a bell

TYPE minecraft_bells_rung_total counter

minecraft_bells_rung_total{player="ediri"} 0

HELP minecraft_blocks_mined_total Statistic related to the number of blocks a player mined

TYPE minecraft_blocks_mined_total counter

minecraft_blocks_mined_total{block="birch_log",namespace="minecraft",player="ediri"} 2 minecraft_blocks_mined_total{block="clay",namespace="minecraft",player="ediri"} 1 minecraft_blocks_mined_total{block="coal_ore",namespace="minecraft",player="ediri"} 16 minecraft_blocks_mined_total{block="crafting_table",namespace="minecraft",player="ediri"} 2 minecraft_blocks_mined_total{block="dirt",namespace="minecraft",player="ediri"} 19 minecraft_blocks_mined_total{block="grass",namespace="minecraft",player="ediri"} 38 minecraft_blocks_mined_total{block="grass_block",namespace="minecraft",player="ediri"} 18 minecraft_blocks_mined_total{block="oak_leaves",namespace="minecraft",player="ediri"} 5 minecraft_blocks_mined_total{block="oak_log",namespace="minecraft",player="ediri"} 11 minecraft_blocks_mined_total{block="oak_planks",namespace="minecraft",player="ediri"} 1 minecraft_blocks_mined_total{block="oxeye_daisy",namespace="minecraft",player="ediri"} 1 minecraft_blocks_mined_total{block="seagrass",namespace="minecraft",player="ediri"} 5 minecraft_blocks_mined_total{block="spruce_leaves",namespace="minecraft",player="ediri"} 11 minecraft_blocks_mined_total{block="spruce_log",namespace="minecraft",player="ediri"} 13 minecraft_blocks_mined_total{block="stone",namespace="minecraft",player="ediri"} 2 minecraft_blocks_mined_total{block="tall_grass",namespace="minecraft",player="ediri"} 1 minecraft_blocks_mined_total{block="tall_seagrass",namespace="minecraft",player="ediri"} 5 minecraft_blocks_mined_total{block="vine",namespace="minecraft",player="ediri"} 2 minecraft_blocks_mined_total{block="wall_torch",namespace="minecraft",player="ediri"} 1

HELP minecraft_cake_slices_eaten_total The number of times the player ate cake

TYPE minecraft_cake_slices_eaten_total counter

minecraft_cake_slices_eaten_total{player="ediri"} 0

HELP minecraft_cleaned_armors_total The number of times the player washed dyed leather armor with a cauldron

TYPE minecraft_cleaned_armors_total counter

minecraft_cleaned_armors_total{player="ediri"} 0

HELP minecraft_cleaned_banner_total The number of times the player washed a banner with a cauldron

TYPE minecraft_cleaned_banner_total counter

minecraft_cleaned_banner_total{player="ediri"} 0

HELP minecraft_damage_dealt_total The amount of damage the player has dealt of different types (in tenths of 1♥)

TYPE minecraft_damage_dealt_total counter

minecraft_damage_dealt_total{player="ediri",type="absorbed"} 0 minecraft_damage_dealt_total{player="ediri",type="hit"} 610 minecraft_damage_dealt_total{player="ediri",type="resisted"} 0

HELP minecraft_damage_received_total The amount of damage the player has taken of different types (in tenths of 1♥)

TYPE minecraft_damage_received_total counter

minecraft_damage_received_total{player="ediri",type="absorbed"} 0 minecraft_damage_received_total{player="ediri",type="blocked_by_shield"} 0 minecraft_damage_received_total{player="ediri",type="resisted"} 0 minecraft_damage_received_total{player="ediri",type="taken"} 2295

HELP minecraft_deaths_total The number of times the player died

TYPE minecraft_deaths_total counter

minecraft_deaths_total{player="ediri"} 9

HELP minecraft_entities_killed_total Statistics related to the number of entities a player killed

TYPE minecraft_entities_killed_total counter

minecraft_entities_killed_total{entity="pig",player="ediri"} 2

HELP minecraft_exporter_build_info A metric with a constant '1' value labeled by version, revision, branch, and goversion from which minecraft_exporter was built.

TYPE minecraft_exporter_build_info gauge

minecraft_exporter_build_info{branch="",goversion="go1.16.5",revision="",version=""} 1

HELP minecraft_filled_cauldrons_total The number of times the player filled a cauldron with a water bucket

TYPE minecraft_filled_cauldrons_total counter

minecraft_fi