heathcliff26/minecraft-exporter

By heathcliff26

Updated about 14 hours ago

https://github.com/heathcliff26/minecraft-exporter

Image
Monitoring & Observability

767

minecraft-exporter

This is a prometheus exporter for minecraft stats. It collects metrics from the save folder, as well as over RCON. This includes advancements, player stats, Tick stats and dynmap stats. The exporter is implemented purely in golang for a small image and memory footprint.

Before i created this exporter, i used the one from Joshi425, which is why the dashboard looks nearly identical. However it seems the other exporter is abandoned, so i wrote my own. There is zero compatibility to the other exporter.

Table of Contents

Container Images

Image location
Container RegistryImage
Github Containerghcr.io/heathcliff26/minecraft-exporter
Docker Hubdocker.io/heathcliff26/minecraft-exporter
Tags

There are different flavors of the image:

Tag(s)Description
latestLast released version of the image
rollingRolling update of the image, always build from main branch.
vX.Y.ZReleased version of the image

Usage

Output of minecraft-exporter -h

Usage of minecraft-exporter:
  -config string
        Optional: Path to config file
  -env
        Used together with -config, when set will expand enviroment variables in config
  -version
        Show the version information and exit

An example configuration can be found here.

The container can be run with:

podman run -d -p 8080:8080 -v /path/to/world:/world:ro ghcr.io/heathcliff26/minecraft-exporter:latest

Metrics will be available under http://localhost:8080/metrics.

Running the container with config file:

podman run -d -p 8080:8080 -v /path/to/world:/world:ro -v /path/to/config.yaml:/config/config.yaml ghcr.io/heathcliff26/minecraft-exporter:latest -config /config/config.yaml

Metrics

The following metrics are generated from the save and will always be exported:

MetricDescription
minecraft_stat_blocks_minedBlocks a player mined
minecraft_stat_blocks_picked_upBlocks a player picked up
minecraft_stat_blocks_craftedItems a player crafted
minecraft_stat_deathsHow often a player died. Cause minecraft:deaths is used for total deaths
minecraft_stat_jumpsHow often a player has jumped
minecraft_stat_cm_traveledHow many cm a player traveled
minecraft_stat_xp_totalHow much total XP a player earned
minecraft_stat_current_levelHow many levels the player currently has
minecraft_stat_food_levelHow fed the player currently is
minecraft_stat_healthHow much health the player currently has
minecraft_stat_scoreThe score of the player
minecraft_stat_entities_killedEntities killed by player
minecraft_stat_damage_takenDamage taken by player
minecraft_stat_damage_dealtDamage dealt by player
minecraft_stat_playtimeTime in minutes a player was online
minecraft_stat_advancementsNumber of completed advancements of a player
minecraft_stat_sleptTimes a player slept in a bed
minecraft_stat_used_crafting_tableTimes a player used a crafting table
minecraft_stat_customCustom minecraft stat
Reduced Metrics

In order to save metrics usage, the option to reduce the metrics series that will be exposed can be enabled in the configuration.

If the option is enabled, all minecraft_stat_blocks_* metrics will only contain the total per player, instead of per block. This results in significantly less metrics, as there won't be a series per player per block.

RCON Metrics

The following metrics will be exposed when RCON is enabled:

MetricDescription
minecraft_player_onlineShow currently online players. Value is always 1
Forge Metrics

These metrics will be exposed when the server is forge:

MetricDescription
forge_tps_dimTPS of a dimension
forge_ticktime_dimTime a Tick took in a Dimension
forge_tps_overallOverall TPS
forge_ticktime_overallOverall Ticktime
forge_entity_countType and count of active entites
Paper Metrics

These metrics will be exposed when the server is paper:

MetricDescription
paper_tps_1m1 Minute TPS
paper_tps_5m5 Minute TPS
paper_tps_15m15 Minute TPS
Dynmap Metrics

These metrics will be exposed when dynmap is enabled:

MetricDescription
dynmap_tile_render_statTile Render Statistics reported by Dynmap
dynmap_chunk_loading_countChunk Loading Statistics reported by Dynmap
dynmap_chunk_loading_durationChunk Loading Statistics reported by Dynmap

Dashboard

There are 2 different dashboards, one for stats for the server and one for stats for players.

Minecraft - Server

The server can be imported from json.

Here is a preview:

Minecraft - Player

The server can be imported from json.

Here is a preview:

Docker Pull Command

docker pull heathcliff26/minecraft-exporter