Skip to content

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

Rules that keep it working

  • 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 hidden side variable. 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 by player=~"$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.

Edit and check

  1. Change dashboard.json by hand, or in Grafana's editor (see below).
  2. 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, and minecraft_ metrics only.
  3. Start minecraft-exporter's examples/ stack against a real WorldAPI, like WORLDAPI_URL=https://minecraft.mairwunnx.com/worldapi/api/v1 (read-only). A WORLDAPI_TOKEN fills the chat table.
  4. Copy dashboard.json to the exporter's examples/grafana/dashboards/minecraft.json. Grafana reloads it within seconds.
  5. Open http://localhost:3000 and 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.

Editing in Grafana's editor

  1. Save the panel in Grafana.
  2. Open Export → Export as JSON, with “Share dashboard with another instance” off. That option adds ${DS_…} inputs, which provisioning can't fill.
  3. Replace dashboard.json with the export and trim its metadata to name: the namespace, uid, and resourceVersion belong to your Grafana. Run scripts/check.py again.

Screenshot and changelog

  • 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's examples/mock/, so every panel draws something: copy dashboard.json to examples/grafana/dashboards/minecraft.json, run docker compose up -d in examples/mock/, and open http://localhost:3300.
  • After a change, add a line to CHANGELOG.md in the same push: under the topmost “## X.Y.Z” section while that version isn't released (gh release view vX.Y.Z fails), 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

Clone this wiki locally