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.

Use this guide only if you need full manual control (custom scrape topology, self-hosted Prometheus or non-standard auth).

Otherwise, use the Grafana Cloud integration available in the Supabase Dashboard.

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. Prometheus Alertmanager or your preferred system sends notifications when Prometheus rules fire (optional) .

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: username
      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.

<Image src="/docs/img/guides/platform/supabase-grafana-prometheus.png" alt="Supabase Grafana dashboard showcasing database metrics" width="3000" height="1509" />

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.