# 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](https://prometheus.io/docs/prometheus/latest/configuration/configuration/),
[Grafana dashboard imports](https://grafana.com/docs/grafana/latest/dashboards/build-dashboards/import-dashboards/).