CtrlK
BlogDocsLog inGet started
Tessl Logo

g14wxz/supabase-observability-metrics

Configures Prometheus scraping, log drains, and observability for Supabase infrastructure monitoring.

97

Quality

97%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Risky

Do not use without reviewing

Overview
Quality
Evals
Security
Files

SKILL.mdskills/supabase-observability-metrics/

name:
supabase-observability-metrics
description:
Sets up Prometheus scrape jobs targeting the Supabase metrics endpoint and configures log drain pipelines. Establishes monitoring dashboards and alerting baselines. Use when configuring Supabase monitoring, setting up Prometheus metrics, implementing log drains, or establishing observability for production Supabase deployments.

Pre-Conditions

  • supabase-mcp-verification MUST have completed successfully.
  • The Supabase project MUST be on a Pro plan or higher (metrics endpoint is not available on Free tier). HALT if plan is insufficient.
  • The operator MUST provide the Prometheus server endpoint or log drain destination URL.
  • A valid Supabase service role key MUST be available for authenticated metrics scraping.

Execution Phases

Phase 1 — Configure Prometheus Scrape Job

  1. Obtain the project metrics endpoint: https://<project-ref>.supabase.co/customer/v1/privileged/metrics.
  2. Append the following scrape job block to the operator's prometheus.yml targets section, substituting <project-ref> and <service-role-key>:
scrape_configs:
  - job_name: supabase-<project-ref>
    scheme: https
    metrics_path: /customer/v1/privileged/metrics
    scrape_interval: 30s
    authorization:
      type: Bearer
      credentials: <service-role-key>
    static_configs:
      - targets:
          - <project-ref>.supabase.co
  1. Validate YAML syntax before saving.

Phase 2 — Configure Log Drains

  1. Enable log drains using the Supabase CLI:
# Create log drains for all sources (replace <destination-url> and <project-ref>)
for SOURCE in api postgres auth; do
  supabase --project-ref <project-ref> log-drains create \
    --source "$SOURCE" \
    --destination-url <destination-url> \
    --format json
done

# Verify drain status
supabase --project-ref <project-ref> log-drains list
  1. Log sources to configure: api, postgres, auth.
  2. Confirm drain status is ACTIVE for each source via the list command output.

Phase 3 — Define Monitoring Targets

  1. Confirm the following metric families are being scraped:
    • API response times (http_request_duration_seconds)
    • Database connection pool usage (pgbouncer_pools_*)
    • Auth token issuance rates (gotrue_* metrics)
    • Storage operation latency (storage_* metrics)
  2. HALT if any metric family returns zero series after two consecutive scrape intervals.

Phase 4 — Establish Alert Baselines

Write the content below to a standalone file named supabase_alerts.yml and reference it from prometheus.yml under rule_files. The file defines five alert rules across three signal areas:

supabase_alerts.yml (save separately and add to Prometheus rule_files):

groups:
  - name: supabase
    rules:
      - alert: SupabaseAPILatencyWarning
        expr: histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m])) > 2
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Supabase API p95 latency above 2s"

      - alert: SupabaseAPILatencyCritical
        expr: histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m])) > 5
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "Supabase API p95 latency above 5s"

      - alert: SupabaseConnectionPoolWarning
        expr: (pgbouncer_pools_server_active_connections / pgbouncer_pools_server_login_connections) > 0.80
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Supabase connection pool saturation above 80%"

      - alert: SupabaseConnectionPoolCritical
        expr: (pgbouncer_pools_server_active_connections / pgbouncer_pools_server_login_connections) > 0.95
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: "Supabase connection pool saturation above 95%"

      - alert: SupabaseAuthErrorRateWarning
        expr: rate(gotrue_errors_total[5m]) / rate(gotrue_requests_total[5m]) > 0.05
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Supabase auth error rate above 5%"

Add supabase_alerts.yml to prometheus.yml under rule_files:

rule_files:
  - supabase_alerts.yml

Verification Report

The agent MUST produce a report containing:

  • Scrape Job: Confirmed job name and target URL.
  • Log Drains: Status (ACTIVE/INACTIVE) per log source.
  • Metric Coverage: Confirmation of each required metric family.
  • Alert Rules: List of defined thresholds and severity levels.
  • Status: OPERATIONAL or DEGRADED with specific failures listed.

HALT if status is DEGRADED and surface the failing components immediately.

skills

supabase-observability-metrics

SKILL.md

tile.json