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:
npx supabase inspect db cache-hit --linked
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;
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:
const DB_LIMIT_MB = 8000;
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
Next Steps
For incident response procedures, see supabase-incident-runbook.
For performance optimization, see supabase-performance-tuning.
