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.

<$Partial path="metrics_access.mdx" />

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

1. Prometheus scrapes https://<project-ref>.supabase.co/customer/v1/privileged/metrics every minute using HTTP Basic Auth.
2. Grafana reads from Prometheus and renders dashboards/alerts.
3. (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:

scrape_configs:
  - job_name: 'supabase'
    scrape_interval: 60s
    metrics_path: /customer/v1/privileged/metrics
    scheme: https
    basic_auth:
      username: service_role
      password: '<secret API key (sb_secret_...)>'
    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 (Secret API 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:

1. In Grafana, go to Connections → Data sources → Add data source.
2. Choose Prometheus, set the URL to your Prometheus endpoint (for example http://prometheus:9090), and click Save & test.

3. Import Supabase dashboards

1. Go to Dashboards → New → Import.
2. Paste the contents of supabase-grafana/dashboard.json.
3. 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.md into 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 Secret API keys on a regular cadence and update the Prometheus config accordingly.