Execute set up comprehensive observability for Supabase integrations with metrics, traces, and alerts.
Use when implementing monitoring for Supabase operations, setting up dashboards,
or configuring alerting for Supabase integration health.
Trigger with phrases like "supabase monitoring", "supabase metrics",
"supabase observability", "monitor supabase", "supabase alerts", "supabase tracing".
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 (API Requests, Database, Auth Usage, Storage, Realtime) for high-level metrics. For deeper Postgres diagnostics, use the subcommands — begin with cache hit ratio and sequential scans:
Dashboard > Reports
supabase inspect db
# 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:
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.
