Repository navigation
Editing the dashboard
Pavel Erokhin edited this page Nov 9, 2026
·
4 revisions
dashboard.json in the repository is the only source of the dashboard. Edit it, never a copy.
| Path | What it does |
|---|---|
dashboard.json |
The dashboard |
scripts/check.py |
What CI checks on every push |
media/*.png |
The screenshots in both READMEs and on grafana.com, one per group of rows |
-
The uid stays
minecraft-worldapi. Links, the READMEs, grafana.com, and Moonlands point at/d/minecraft-worldapi. - The title stays “Minecraft server (minecraft-exporter)”, as on grafana.com. Imports match it, and Grafana refuses two dashboards with one title in a folder.
-
The file stays a v2 dashboard (
apiVersion: dashboard.grafana.app/v2), which needs Grafana 13. Only v2 rows hide by a condition: “Your world” and the server's rows show by the hiddensidevariable. Don't hide a row by repeating it: over an empty variable Grafana still draws it once. -
Data sources come only from the variables:
${datasource}for Prometheus,${worldapi}for Infinity.${DS_…}inputs work on import but not in a provisioned file. -
Every query filters by
instance="$instance", and per-player ones byplayer=~"$player"too. -
Only
minecraft_metrics that minecraft-exporter documents. A new metric lands in the exporter first, and the dashboard's release follows the exporter's. -
Counters that start with the exporter (events, deaths by cause) lose their first event under
increase(). The exporter seeds what it can at zero. “Deaths by cause” subtracts the value at the start of the range instead. - A panel that needs a WorldAPI permission says so in its description, as “Needs a WorldAPI token with logs:read.”
- Panels follow the same look: stats for headline numbers, one axis per graph, status colors only for thresholds, thin lines.
Panel titles and descriptions are English, with curly quotes and no hyphen as a dash.
- Change
dashboard.jsonby hand, or in Grafana's editor (see below). - Run
python3 -I scripts/check.py. It checks for a v2 file, the uid and title, unique panel ids, the grid, data sources through variables, andminecraft_metrics only. - Start minecraft-exporter's
examples/stack against a real WorldAPI, likeWORLDAPI_URL=https://minecraft.mairwunnx.com/worldapi/api/v1(read-only). AWORLDAPI_TOKENfills the chat table. - Copy
dashboard.jsonto the exporter'sexamples/grafana/dashboards/minecraft.json. Grafana reloads it within seconds. - Open
http://localhost:3000and look: every panel shows data, nothing overlaps, the tables have all their columns. Fresh Prometheus data needs half an hour before the bar charts fill.
- Save the panel in Grafana.
- Open Export → Export as JSON, with “Share dashboard with another instance” off. That option adds
${DS_…}inputs, which provisioning can't fill. - Replace
dashboard.jsonwith the export and trim itsmetadatatoname: the namespace, uid, and resourceVersion belong to your Grafana. Runscripts/check.pyagain.
- When the look changes, refresh the screenshots in
media/: 1600 px wide, the last 24 hours, one per group of rows. Take them on the made-up server in minecraft-exporter'sexamples/mock/, so every panel draws something: copydashboard.jsontoexamples/grafana/dashboards/minecraft.json, rundocker compose up -dinexamples/mock/, and openhttp://localhost:3300. - After a change, add a line to
CHANGELOG.mdin the same push: under the topmost “## X.Y.Z” section while that version isn't released (gh release view vX.Y.Zfails), or under a new section with the next version. - Commits are short imperative English lines, one logical change each: “Show deaths by killer”.
Next: Releasing
Server owners
Developers