test-minecraft-exporter

name

test-minecraft-exporter

description

End-to-end docker-compose test harness for the minecraft-prometheus-exporter. Spins up an itzg/minecraft-server:latest vanilla server alongside a freshly built exporter and walks the user through verifying metrics in a live browser/Prometheus session. Use this skill whenever the user wants to "test the exporter end-to-end", "verify metrics against a real Minecraft server", "spin up a local MC server", "run the docker compose test", scrape /metrics from a vanilla MC server, or sanity-check a code change in this repo before opening a PR — including cases where the user just says "let me see if it works" or "run the exporter against MC" without naming the compose file.

Test the minecraft-prometheus-exporter end-to-end

This is a runbook for booting docker-compose.test.yml and confirming the exporter scrapes a real Minecraft server. Run these steps in order from the repo root.

Files this skill depends on

Both live at the repo root and are checked into git:

• docker-compose.test.yml — defines the minecraft (itzg/minecraft-server:latest, vanilla, RCON on, offline mode) and exporter services, plus a shared mc-data named volume so the exporter can read the world dir.
• Dockerfile.dev — multi-stage golang:1.26-alpine → chainguard/static build of the exporter from source. Compose builds this image automatically with --build.

If either file is missing, do not improvise — flag it to the user. The compose setup has UID/volume specifics that are easy to get wrong.

1. Bring the stack up

docker compose -f docker-compose.test.yml up -d --build

First boot takes ~90 seconds because the vanilla MC server has to download the JAR (resolved from VERSION: LATEST) and generate a world. The compose file has a service_healthy dependency on the MC container's mc-health healthcheck, so the exporter will only start once MC is ready — but docker compose up returns earlier than that. Tell the user this is expected; subsequent boots are much faster.

2. Endpoints

Once both containers are up, tell the user:

• Exporter metrics: http://localhost:9150/metrics
• Exporter landing page: http://localhost:9150/
• Minecraft server (Java client): localhost:25565

3. Identify the MC version

VERSION: LATEST means "whatever itzg's image considers latest at pull time" — useful but not self-documenting. Show the user which version was resolved so they know which client to use:

docker exec mc-exporter-test-server bash -c 'ls /data/*.jar'

The jar filename embeds the version (e.g. minecraft_server.26.1.2.jar).

4. Connect a client

The server runs with ONLINE_MODE=FALSE, so any Java Edition client at the matching version can connect with any username — no Mojang/Microsoft auth needed. Just add a server pointed at localhost:25565.

Until a player connects at least once, MC doesn't create world/playerdata/, world/stats/, or world/advancements/. With an empty server, /metrics will only show minecraft_exporter_build_info. That's expected, not a bug.

5. Force a flush and inspect metrics

After the user has logged in and done a few things in-game (mine a block, walk around, jump), push MC to flush its in-memory stats:

docker exec mc-exporter-test-server rcon-cli save-all

Then re-scrape:

curl -s http://localhost:9150/metrics | grep '^minecraft_'

You should now see populated series — minecraft_blocks_mined_total, minecraft_jumps_total, minecraft_movement_meters_total{means="walk"}, minecraft_player_online{player="..."}, etc.

Quick sanity-check RCON too:

docker exec mc-exporter-test-server rcon-cli list

6. The label-name quirk

The compose sets MC_NAME_SOURCE=offline. This means:

• RCON-derived series (minecraft_player_online) carry the readable player name (e.g. player="_diri"), because the RCON list command returns names directly.
• File-derived series (everything in world/stats/, world/playerdata/, world/advancements/) carry the raw UUID (e.g. player="8d34c913-…"), because the exporter only resolves names when name-source is mojang (calls playerdb.co) or bukkit (reads bukkit.lastKnownName from NBT).

In vanilla + offline mode neither alternative works: the offline UUID isn't registered with Mojang, and vanilla doesn't write the Bukkit name field. So offline (UUID-as-label) is the only honest choice for this test stack. If the user wants names everywhere they need a real online server or a Paper/Spigot/Purpur server. Don't try to "fix" this by switching MC_NAME_SOURCE — it will silently make things worse.

7. Tear down

docker compose -f docker-compose.test.yml down -v

The -v flag wipes the mc-data volume, so the next run starts from a fresh world. Drop -v if the user wants to keep the world (and their player progress) between runs — first boot is the slow one, subsequent boots reuse the existing world and skip generation.

Troubleshooting

permission denied on /mc/world/playerdata in the exporter logs: Confirm the exporter service in docker-compose.test.yml still has user: "1000:1000". The itzg image writes the world as UID 1000, and the chainguard/static base used by the exporter defaults to UID 65532, so without the UID override the read-only mount is unreadable. This is the single most likely thing to break if someone refactors the compose file.

Exporter starts before MC is ready and crashes on RCON dial: Shouldn't happen — the compose file uses depends_on: minecraft: condition: service_healthy. If it does, check whether someone removed the healthcheck or the condition: block.

/metrics only ever shows minecraft_exporter_build_info: No player has joined the server yet. Connect at least once, do something in-game, then rcon-cli save-all and re-scrape. The exporter has no synthetic mode — empty world means empty metrics.

MC won't pull a new version / boot loops: VERSION: LATEST can occasionally lag behind a brand-new Minecraft release while itzg's image catches up. Pin to a specific version (e.g. VERSION: "1.21.4") in the compose file as a workaround.