Skip to content

Configuration

Pavel Erokhin edited this page Nov 9, 2026 · 2 revisions

Each setting is an environment variable or a flag. A flag wins over its variable.

Settings

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.

What it serves

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

Timeouts

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.

Statistics and the rate limit

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.

Many servers: the targets file

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
  1. Save it, for example as targets.yml, and mount it into the container.
  2. Point EXPORTER_TARGETS at it: EXPORTER_TARGETS=/etc/minecraft-exporter/targets.yml.
  3. 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.

Clone this wiki locally