Metrics API with Prometheus & Grafana (self-hosted)
Self-hosting Prometheus and Grafana gives you full control over retention, alert routing, and dashboards. The Supabase Metrics API slots into any standard Prometheus scrape job, so you can run everything locally, on a VM, or inside Kubernetes.
Grafana also documents a Supabase integration reference. While it targets Grafana Cloud, the scrape and agent settings apply equally to self-hosted clusters and offer a community-maintained companion to this guide.
Architecture
- Prometheus scrapes
https://<project-ref>.supabase.co/customer/v1/privileged/metricsevery minute using HTTP Basic Auth. - Grafana reads from Prometheus and renders dashboards/alerts.
- (Optional) Alertmanager or your preferred system sends notifications when Prometheus rules fire.
1. Deploy Prometheus
Install Prometheus using your preferred method (Docker, Helm, binaries). Then add a Supabase-specific job to prometheus.yml:
12345678910111213scrape_configs: - job_name: 'supabase' scrape_interval: 60s metrics_path: /customer/v1/privileged/metrics scheme: https basic_auth: username: service_role password: '<service-role key or JWT>' static_configs: - targets: - '<project-ref>.supabase.co:443' labels: project: '<project-ref>'- Keep the scrape interval at 60 seconds to match Supabase’s refresh cadence.
- If you run Prometheus behind a proxy, make sure it can establish outbound HTTPS connections to
*.supabase.co. - Store secrets (service role key) with your secret manager or inject them via environment variables.
2. Deploy Grafana
Install Grafana (Docker image, Helm chart, or packages) and connect it to Prometheus:
- In Grafana, go to Connections → Data sources → Add data source.
- Choose Prometheus, set the URL to your Prometheus endpoint (for example
http://prometheus:9090), and click Save & test.
3. Import Supabase dashboards
- Go to Dashboards → New → Import.
- Paste the contents of
supabase-grafana/dashboard.json. - Select your Prometheus datasource when prompted.
You now have over 200 production-ready panels covering CPU, IO, WAL, replication, index bloat, and query throughput.
4. Configure alerting
- Import the sample rules from
docs/example-alerts.mdinto Prometheus or Grafana Alerting. - Tailor thresholds (for example, disk utilization, long-running transactions, connection saturation) to your project’s size.
- Route notifications via Alertmanager, Grafana OnCall, PagerDuty, or any other supported destination.
5. Operating tips
- Multiple projects: add one scrape job per project ref so you can separate metrics and labels cleanly.
- Right-sizing guidance: pair the dashboards with Supabase’s Query Performance report and Advisors to decide when to optimize vs upgrade.
- Security: rotate the service role key on a regular cadence and update the Prometheus config accordingly.