Repository navigation
Architecture
The exporter reads WorldAPI on every scrape and answers with constant metrics: each scrape shows the server as it is now. Between scrapes it keeps only what must survive: event and console counters, cached slow data, and which endpoints the token may read.
| Path | What it does |
|---|---|
main.go |
Flags and environment variables, /metrics, /probe, /healthz, the exporter's own metrics |
internal/config/ |
The targets file behind /probe, URL and token checks, durations |
internal/worldapi/ |
The few WorldAPI endpoints the exporter reads, and their JSON |
internal/collector/target.go |
One server: a scrape reads WorldAPI in parallel and sends constant metrics |
internal/collector/server.go |
Server, performance, JVM, worlds, online players |
internal/collector/stats.go |
Player statistics from leaderboards, cached and refreshed a batch per scrape |
internal/collector/events.go |
Counters fed by GET /events, counted from the exporter's start |
internal/collector/private.go |
What a token opens: the host, the console, plugins, moderation, what crowds each world |
- Prometheus asks
/metricsor/probe?target=<name>. The exporter picks the target and sets a deadline:EXPORTER_TIMEOUTor half a second before Prometheus' own timeout. - In parallel, it reads
GET /server,/server/performance,/worlds(and each world),/players/online, and/server/systemwhen the token may. - Also in parallel, it refreshes a batch of slow data, reads new events since the last scrape, and reads the newest console lines.
- It turns the answers into metrics.
minecraft_upfollowsGET /serveralone. A failed request drops only its own metrics.
Leaderboards, the player list, plugins, moderation, and each world's entity summary cost a request each and change slowly. They sit in a queue: each scrape refreshes the stalest items older than EXPORTER_STATS_INTERVAL, 6 at a time anonymously or 12 with a token. This keeps a scrape within WorldAPI's anonymous limit of 120 requests a minute with bursts of 30. An item that fails keeps its last answer for five intervals or 10 minutes, whichever is longer, then its metrics drop. A world that unloads takes its summary away at once.
GET /events and GET /server/logs feed counters. The first poll only marks where to start, so counters count from the exporter's start like any Prometheus counter. Events are read by time and id, up to 50 pages of 200 per scrape. Known event types and advancement frames start at zero, so the first event shows as an increase. Plugins' recorded topics join them from GET /extensions.
A refusal (401 or 403) is not an error. The exporter marks the endpoint as closed for 10 minutes, skips it until then, and shows it in minecraft_exporter_endpoint_allowed. Any other failure counts in minecraft_exporter_request_errors_total.
- Names start with
minecraft_and follow Prometheus conventions:_totalfor counters, base units (seconds, bytes, meters). - A released name never changes: a rename is a major version.
- Labels stay bounded: worlds, entity types (the top ten WorldAPI names), players, event types, death causes. Never a label from free text, such as a chat message.
Next: Development.
For server owners
For developers