Supabase Observability

Overview

Monitor Supabase projects end-to-end: Dashboard reports for API/database/auth metrics, supabase inspect db CLI for deep Postgres diagnostics, pgstatstatements for query analytics, log drains for external aggregation, Edge Functions for custom metrics, and alerting on quota thresholds.

Follow the three steps below from this file for the high-level workflow, then drill into the linked references/ files for the full commands, SQL, and function source.

Prerequisites

• Supabase CLI installed (npx supabase --version)
• Supabase project linked (supabase link --project-ref )
• Pro plan or higher for log drain support and extended log retention
• @supabase/supabase-js v2+ installed for application-level monitoring

Instructions

Step 1: Dashboard Reports and CLI Inspect Commands

Start with the built-in Dashboard > Reports (API Requests, Database, Auth Usage, Storage, Realtime) for high-level metrics. For deeper Postgres diagnostics, use the supabase inspect db subcommands — begin with cache hit ratio and sequential scans:

# Cache hit ratio — should be > 99% (below 95% means upgrade compute)
npx supabase inspect db cache-hit --linked

# Sequential scans — tables needing indexes
npx supabase inspect db seq-scans --linked

The full report table plus all nine inspect subcommands (table sizes, index usage, long-running queries, bloat, blocking, replication slots, and more) are in references/cli-inspect-commands.md.

Step 2: Query Analytics with pgstatstatements and Log Drains

Enable pgstatstatements for query-level metrics, then rank queries by execution time:

create extension if not exists pg_stat_statements;

-- Top slowest queries by average execution time
select substring(query, 1, 80) as query_preview, calls,
  round(mean_exec_time::numeric, 2) as avg_ms
from pg_stat_statements
where mean_exec_time > 50
order by mean_exec_time desc limit 20;

Forward logs to external aggregation with a log drain:

npx supabase log-drains add --name datadog-drain --type datadog \
  --datadog-api-key "$DATADOG_API_KEY" --datadog-region us1 --linked

The complete slow-query / high-frequency / connection-monitoring SQL set and every log-drain command (Datadog, webhook, list, remove) are in references/query-analytics-and-log-drains.md.

Step 3: Custom Metrics, Alerting, and Health Checks

Emit business-level metrics from a scheduled Edge Function, alert on quota thresholds, and expose a health endpoint for uptime monitors. The skeleton of the metrics collector:

// supabase/functions/collect-metrics/index.ts — see reference for full source
const DB_LIMIT_MB = 8000; // 8GB Pro plan limit
if (dbSize > DB_LIMIT_MB * 0.85) {
  console.warn(`[QUOTA_ALERT] Database at ${Math.round(dbSize / DB_LIMIT_MB * 100)}% capacity`);
}

Schedule it every 15 minutes via [functions.collect-metrics] in config.toml. The complete collector, the multi-service health-check endpoint, and Realtime connection monitoring are in references/custom-metrics-and-health-checks.md. For external alert rules, see the Prometheus AlertManager set in references/alert-configuration.md.

Output

• Dashboard reports configured for API, database, and auth monitoring
• CLI inspect commands available for Postgres diagnostics (table sizes, index usage, cache hits, sequential scans, long-running queries)
• pgstatstatements enabled with slow-query and high-frequency-query views
• Log drains forwarding to external tools (Datadog, Logflare, or webhook)
• Custom metrics Edge Function collecting quota-relevant data on a schedule
• Health check endpoint returning per-service status with latency
• Alerting on quota thresholds (database size, user count)

Error Handling

Examples

A one-shot diagnostic bash script that runs every inspect command in sequence, plus the app_metrics backing table schema with a 90-day retention policy, are in references/diagnostic-scripts.md. For application-level Prometheus instrumentation of the Supabase client, see references/metrics-collection.md.

Resources

• Supabase Logs & Analytics
• Database Inspect Commands
• Log Drains
• Edge Functions Scheduling
• pgstatstatements
• Supabase JS Client

Next Steps

For incident response procedures, see supabase-incident-runbook.

For performance optimization, see supabase-performance-tuning.