pavel444-byte
1f254b29a2
All checks were successful
Deploy MineGeo to Dokploy / deploy (push) Successful in 5m57s
78 lines
4.6 KiB
Markdown
78 lines
4.6 KiB
Markdown
# 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.site/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/).
|