MineGeo/docs/prometheus.md

Prometheus and Grafana

Open MineGeo's Moderation page while signed in as an Admin, then find Prometheus & Grafana. Regular Moderators cannot view or change this setup. No new Vercel environment variables or Supabase keys are needed.

Connect Prometheus

1. Click Generate metrics token. Copy the generated configuration immediately. Only a token hash is stored; the raw token cannot be recovered after leaving the page or hiding it.
2. Paste the configuration into your Prometheus server's prometheus.yml. If that file already has scrape_configs:, add only the - job_name: minegeo entry under that existing section. Do not create two scrape_configs keys.
3. Validate the configuration with promtool check config prometheus.yml, then reload or restart your Prometheus service using its normal deployment process.
4. In Prometheus, open Status → Targets and check that minegeo is UP. A successful scrape also appears in MineGeo's Last successful scrape field; use Refresh status to update it.

Prometheus must be able to reach MineGeo's public HTTPS address. The endpoint is https://minegeo.vercel.app/api/metrics, protected by an Authorization bearer header. Browser login cookies, plugin credentials, and URL query tokens do not grant access. The generated job scrapes once a minute with a 20-second timeout and does not forward credentials through redirects. Keep the configuration private; do not paste it into public Git repositories or forum posts.

Rotate metrics token revokes the previous token immediately. Copy the new configuration and update Prometheus afterward. Disable metrics access revokes the current token. Deleting the issuing Admin account or removing its Admin role also invalidates that token. Issuing another token requires a current Admin.

Import the Grafana dashboard

1. In MineGeo, click Download Grafana dashboard.
2. In Grafana, add a Prometheus data source pointing to your Prometheus server (for example, its internal service address). Grafana queries Prometheus; it does not use the MineGeo metrics URL as its data source.
3. Open Dashboards → New → Import, upload the downloaded JSON, and choose the Prometheus data source when prompted.
4. Select the MineGeo instance. Allow one or two scrapes for the first values.

The dashboard has 15 panels covering scrape health, registered accounts, maps, panoramas, solo games, multiplayer rooms, uploads, bug reports, content reports, Discord delivery, exporter read time, and snapshot age. It requires only the built-in Prometheus source and Grafana stat/time-series panels.

History begins when your Prometheus instance starts scraping; existing retained records appear in the first snapshot. Prometheus retention controls how long history remains. Set up Prometheus/Grafana on your own server or supported hosted monitoring service; Vercel runs the exporter, not the monitoring servers.

Meaning and privacy of metrics

• All minegeo_* values are gauges, not monotonic counters. Deleted records, including closed bug reports removed after three days, can lower counts. Do not use rate() or increase() on these retained inventory gauges.
• Games/rooms created in the last 24 hours are rolling-window gauges.
• Solo games are complete once current_round = 5. Incomplete includes abandoned games. Room lifecycle states describe stored rooms, not currently online users.
• Aggregates are collected in one database transaction and cached there for 30 seconds to share work across Vercel instances. Failed scrapes return 503, never a fabricated all-zero dataset. Prometheus's up series records failures.
• Names, IDs, emails, messages, screenshots, credentials, and map content are excluded. Metric labels use fixed state/difficulty values only.
• Page views, IP addresses, browser sessions, Vercel CPU/memory, and request latency are not collected by this integration. Vercel Web Analytics remains separate.

For another installation, apply supabase/migrations/20261012085217_prometheus_metrics.sql before deployment. The new table has RLS and service-role-only permissions; the three RPC functions use security invoker and explicitly revoke public/anonymous/authenticated access. Verify SQL authorization locally with node scripts/test-prometheus-sql.mjs using the same optional PGlite runtime as the existing SQL verification scripts.

References: Prometheus scrape configuration, Grafana dashboard imports.