Building a Minecraft Server Dashboard with Grafana and Prometheus

You want to see your server's health at a glance. Player counts over time. TPS trends. Memory usage spikes that correlate with specific events. A single dashboard that shows everything.

Grafana and Prometheus together give you this. Prometheus scrapes metrics from your server every few seconds. Grafana displays those metrics as graphs, gauges, and tables. The result is a professional monitoring dashboard that looks similar to what large hosting companies use internally.

---

Architecture Overview

Minecraft Server -> Prometheus Exporter Plugin -> Prometheus (scrapes data) -> Grafana (displays data)

1. A Minecraft plugin exposes server metrics at an HTTP endpoint
2. Prometheus reads that endpoint every 15 seconds and stores the data
3. Grafana queries Prometheus and draws the graphs

You need a VPS or separate machine to run Prometheus and Grafana. They run as Docker containers alongside your server or on a separate box.

---

Step 1: Install the Prometheus Exporter Plugin

Download the UnifiedMetrics plugin (or the Prometheus Exporter plugin) for your server platform:

• Paper/Spigot: Search "UnifiedMetrics" on SpigotMC
• Fabric: Search "Prometheus Exporter" on Modrinth

Place the .jar in your plugins (or mods) folder and restart the server.

After restart, the plugin exposes metrics at:

http://your-server-ip:9225/metrics

Visit this URL in a browser. You should see raw text output with lines like:

minecraft_tps 20.0
minecraft_players_online 5
minecraft_jvm_memory_bytes_used 1073741824

---

Step 2: Install Prometheus with Docker

On your VPS (same machine or separate), create a docker-compose.yml:

version: '3'
services:
  prometheus:
    image: prom/prometheus:latest
    container_name: prometheus
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
      - prometheus-data:/prometheus
    ports:
      - "9090:9090"
    restart: unless-stopped

  grafana:
    image: grafana/grafana:latest
    container_name: grafana
    ports:
      - "3000:3000"
    volumes:
      - grafana-data:/var/lib/grafana
    restart: unless-stopped

volumes:
  prometheus-data:
  grafana-data:

Create the Prometheus config file prometheus.yml in the same directory:

global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'minecraft'
    static_configs:
      - targets: ['your-minecraft-server-ip:9225']

Replace your-minecraft-server-ip with the actual IP. If Prometheus runs on the same machine as the Minecraft server, use host.docker.internal (on Docker Desktop) or the host's LAN IP.

Start both containers:

docker compose up -d

Check that Prometheus is scraping by visiting http://your-vps-ip:9090/targets. The Minecraft target should show "UP" in green.

---

Step 3: Configure Grafana

Open Grafana at http://your-vps-ip:3000. Default login is admin/admin (change it immediately).

Add Prometheus as a data source:

1. Go to Configuration > Data Sources > Add Data Source
2. Select "Prometheus"
3. Set the URL to http://prometheus:9090 (Docker internal networking)
4. Click "Save & Test". It should show green

Create your first dashboard:

1. Click Dashboards > New Dashboard > Add Visualization
2. Select Prometheus as the data source
3. In the query field, type: minecraft_tps
4. You get a live TPS graph

---

Step 4: Build Useful Panels

Here are the queries for the most useful panels:

| Panel Title | Prometheus Query | Visualization | |---|---|---| | TPS (Ticks Per Second) | minecraft_tps | Time series graph | | Online Players | minecraft_players_online | Stat (big number) | | RAM Used (MB) | minecraft_jvm_memory_bytes_used / 1048576 | Gauge | | RAM Allocated (MB) | minecraft_jvm_memory_bytes_max / 1048576 | Gauge | | CPU Usage | process_cpu_seconds_total (rate) | Time series graph | | Loaded Chunks | minecraft_loaded_chunks | Time series graph | | Entities | minecraft_entities_total | Time series graph |

For CPU usage as a percentage, use this query:

rate(process_cpu_seconds_total[1m]) * 100

---

Step 5: Player Activity Tracking

UnifiedMetrics tracks per-player statistics. You can create panels showing:

• Player online time: minecraft_player_online_time_seconds
• Player join/leave events: Track with increase(minecraft_player_joins_total[1h])
• Peak player count: Use Grafana's "Max" aggregation on minecraft_players_online

Create a table panel with "Player" as a label column and "online time" as the value. Sort by descending to see your most active players.

---

Step 6: Alerts

Grafana supports alerting. Set up notifications for critical events:

• TPS drops below 18: Your server is lagging. Investigate immediately
• RAM usage exceeds 90%: Risk of out-of-memory crash
• Player count drops to 0 unexpectedly: Server might have crashed

Go to Alerting > Alert Rules > Create Alert. Set the condition (e.g., minecraft_tps < 18 for 2 minutes) and configure a notification channel (Discord webhook, email, or Slack).

---

Security

Do not expose the Prometheus exporter port (9225) to the public internet. If your Prometheus instance runs on a different machine, use a firewall rule to restrict access:

sudo ufw allow from your-prometheus-ip to any port 9225
sudo ufw deny 9225

Also restrict Grafana access to trusted IPs or put it behind a reverse proxy with authentication.

---

Space-Node's control panel includes built-in real-time CPU and RAM monitoring. For advanced dashboards with historical data and custom alerts, this Grafana setup gives you complete visibility into your server's performance. Get started here.