Skip to content

Architecture

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

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.

Where things live

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

One scrape

  1. Prometheus asks /metrics or /probe?target=<name>. The exporter picks the target and sets a deadline: EXPORTER_TIMEOUT or half a second before Prometheus' own timeout.
  2. In parallel, it reads GET /server, /server/performance, /worlds (and each world), /players/online, and /server/system when the token may.
  3. Also in parallel, it refreshes a batch of slow data, reads new events since the last scrape, and reads the newest console lines.
  4. It turns the answers into metrics. minecraft_up follows GET /server alone. A failed request drops only its own metrics.

Slow data

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.

Events and console lines

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.

Permissions

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.

Rules for metrics

  • Names start with minecraft_ and follow Prometheus conventions: _total for 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.

Clone this wiki locally