Supabase observability

Supabase Observability

Overview

Monitor Supabase projects end-to-end: Dashboard reports for API/database/auth metrics, supabase inspect db CLI for deep Postgres diagnostics, pg_stat_statements 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 <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 pg_stat_statements and Log Drains

Enable pg_stat_statements 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)
• pg_stat_statements 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

Issue	Cause	Solution
pg_stat_statements returns no rows	Extension not enabled	Enable via Dashboard > Database > Extensions
supabase inspect db fails	CLI not linked to project	Run supabase link --project-ref <ref>
Log drain not receiving events	API key invalid or region mismatch	Verify credentials; check supabase log-drains list
Cache hit ratio below 95%	Working set exceeds RAM	Upgrade compute add-on or optimize queries
Health check returns 503	One or more services degraded	Check detail field in response; verify service role key
Edge Function cron not firing	Missing schedule in config.toml	Add [functions.<name>] with schedule field and redeploy
Long-running queries growing	Missing indexes or lock contention	Run inspect db seq-scans and inspect db blocking

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
• pg_stat_statements
• Supabase JS Client

Next Steps

For incident response procedures, see supabase-incident-runbook. For performance optimization, see supabase-performance-tuning.