Repository navigation
Configuration
Each setting is an environment variable or a flag. A flag wins over its variable.
| Variable | Flag | Default | What it does |
|---|---|---|---|
WORLDAPI_URL |
--worldapi.url |
The WorldAPI behind /metrics, an http or https URL ending in /api/v1
|
|
WORLDAPI_TOKEN |
--worldapi.token |
A WorldAPI token. Without one the exporter reads as an anonymous visitor | |
WORLDAPI_TOKEN_FILE |
--worldapi.token-file |
A file whose first line is the token, for Docker secrets. WORLDAPI_TOKEN wins when both are set |
|
EXPORTER_TARGETS |
--targets |
A YAML file of servers behind /probe?target=<name>
|
|
EXPORTER_PLAYERS |
--players |
true |
Per-player metrics with a player label. false adds every player up into one series and drops the online players' details |
EXPORTER_STATS_INTERVAL |
--stats-interval |
60s |
How often each player statistic, and other slow data, is read again |
EXPORTER_TIMEOUT |
--timeout |
10s |
The longest a scrape may take |
EXPORTER_LISTEN |
--listen |
:10059 |
Where to serve metrics |
--version |
Print the version and exit |
Durations take Go's form (90s, 2m) or plain seconds (90). EXPORTER_PLAYERS takes true, false, 1, 0, yes, no, on, or off. Anything else falls back to the default with a warning in the log.
The exporter needs WORLDAPI_URL, EXPORTER_TARGETS, or both. It refuses to start without either, and with a URL that doesn't end in /api/v1.
| Path | What it gives |
|---|---|
/metrics |
The server at WORLDAPI_URL, plus the exporter's own metrics (Go runtime, process, build info, request errors) |
/probe?target=<name> |
One server from the targets file, without the exporter's own metrics |
/healthz |
ok while the exporter runs |
/ |
A page with the version and a link to /metrics
|
A scrape ends after EXPORTER_TIMEOUT or half a second before Prometheus' own scrape timeout, whichever comes first. A request that runs out of time drops only its own metrics, and the rest of the scrape still arrives.
Player statistics come from WorldAPI's leaderboards, one request each. The exporter caches them and refreshes the stalest ones a batch per scrape: 6 at a time anonymously, 12 with a token. This keeps a scrape within WorldAPI's limit for anonymous clients: 120 requests a minute, bursts of 30. Raise EXPORTER_STATS_INTERVAL to send fewer requests, or lower it for fresher numbers.
One exporter can read many servers, the way the blackbox exporter does it. List them in a YAML file:
targets:
survival:
url: http://survival:8110/api/v1
token_file: /run/secrets/survival # or token: …, or nothing for anonymous reads
creative:
url: http://creative:8110/api/v1
players: false # overrides EXPORTER_PLAYERS for this server- Save it, for example as
targets.yml, and mount it into the container. - Point
EXPORTER_TARGETSat it:EXPORTER_TARGETS=/etc/minecraft-exporter/targets.yml. - Scrape each server by name, as Prometheus shows.
Each target takes url, one of token or token_file, and an optional players. The exporter rejects an unknown key, a target without a valid URL, and a target with both token and token_file. It reads the file once, at start, so restart it after a change.
Next: WorldAPI token.
For server owners
For developers