supabase-observability

name	supabase-observability
description	Set up monitoring and observability for Supabase projects using Dashboard reports, CLI inspect commands, pg_stat_statements, log drains, and alerting. Use when implementing monitoring, diagnosing slow queries, forwarding logs, or configuring alerts for Supabase project health. Trigger with phrases like "supabase monitoring", "supabase metrics", "supabase observability", "supabase logs", "supabase alerts", "supabase inspect", "supabase log drain".
allowed-tools	Read, Write, Edit, Bash(npx supabase:*), Bash(supabase:*), Grep
version	1.53.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","supabase","monitoring","observability"]
compatibility	Designed for Claude Code

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)  avg_ms
 pg_stat_statements
 mean_exec_time  
  mean_exec_time  limit ;