The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
docs: Overhaul reports page (#39195)
Chris Chinchillac734078800d3
diff --git a/apps/docs/content/guides/telemetry/reports.mdx b/apps/docs/content/guides/telemetry/reports.mdxindex 5160b761a75..68781163d70 100644--- a/apps/docs/content/guides/telemetry/reports.mdx+++ b/apps/docs/content/guides/telemetry/reports.mdx@@ -4,7 +4,17 @@ title: 'Reports'description: 'Built-in observability for your Supabase project'----Supabase Reports provide comprehensive observability for your project through dedicated monitoring dashboards that visualize key metrics across your database, auth, storage, realtime, and API systems. Each report offers self-debugging tools to gain actionable insights for optimizing performance and troubleshooting issues.+{/* last LW we added that same report to every report page (pre-filtered) so, API Gateway report filtered by Auth will show the same data as going to Auth Report in the API Gateway section */}++Supabase Reports provide comprehensive observability for your project through dedicated monitoring dashboards for servers:++- Database+- Auth+- Storage+- Realtime+- API systems++Each report offers self-debugging tools to gain actionable insights for optimizing performance and troubleshooting issues.<Admonition type="note">@@ -14,7 +24,7 @@ Reports are only available for projects hosted on the Supabase Cloud platform an## Using reports-Reports can be filtered by time range to focus your analysis on specific periods. Available time ranges are gated by your organization's plan, with higher-tier plans providing access to longer historical periods.+You can filter reports by time range to focus on a specific period. Higher-tier plans provide access to longer time ranges.| Time Range | Free | Pro | Team | Enterprise || --------------- | ---- | --- | ---- | ---------- |@@ -31,27 +41,63 @@ Reports can be filtered by time range to focus your analysis on specific periods<$Show if="billing:all">+## API gateway++The API Gateway report analyzes performance and traffic patterns managed by your project's API layer.++| Chart | Description | Key Insights |+| --------------- | ----------------------------------------- | ---------------------------------------------------------------------- |+| Total Requests | Overall API request volume | Traffic patterns and growth trends, including top routes |+| Response Errors | Error rates with 4XX and 5XX status codes | API reliability and user experience issues, including top routes |+| Response Speed | Average API response times | Performance bottlenecks and optimization targets, including top routes |+| Network Traffic | Request and response egress usage | Data transfer patterns and cost implications |++## Auth++The Auth reports focus on user authentication patterns and behaviors within your Supabase project.++| Chart | Description | Key Insights |+| ------------------------ | --------------------------------------------- | ----------------------------------------------- |+| Active Users | Count of unique users performing auth actions | User engagement and retention patterns |+| Sign In Attempts by Type | Breakdown of authentication methods used | Password vs OAuth vs magic link preferences |+| Sign Ups | Total new user registrations | Growth trends and onboarding funnel performance |+| API Gateway Auth Errors | Error rates grouped by status code | Authentication friction and security issues |+| Password Reset Requests | Volume of password recovery attempts | User experience pain points |++### Auth API Gateway++The Auth API Gateway reports focus on API requests related to authentication and user management.++| Chart | Description | Key Insights |+| --------------- | --------------------------------------------- | ---------------------------------------------------------------------------- |+| Total Requests | Count of unique users performing auth actions | User engagement and retention patterns, including top routes |+| Response Errors | Error rates with 4XX and 5XX status codes | API reliability and user experience issues, including top routes |+| Response speed | Average response time for auth requests | Performance bottlenecks and optimization opportunities, including top routes |+| Network Traffic | Ingress and egress usage | Data transfer costs and CDN effectiveness |+## Database-The Database report provides the most comprehensive view into your Postgres instance's health and performance characteristics. These charts help you identify performance bottlenecks, resource constraints, and optimization opportunities at a glance.+The Database report provides a comprehensive view into your Postgres instance's health and performance characteristics. These charts help you identify performance bottlenecks and resource constraints at a glance.The following charts are available for Free and Pro plans:-| Chart | Available Plans | Description | Key Insights |-| ---------------------------- | --------------- | -------------------------------------------- | --------------------------------------------- |-| Memory usage | Free, Pro | RAM usage percentage by the database | Memory pressure and resource utilization |-| CPU usage | Free, Pro | Average CPU usage percentage | CPU-intensive query identification |-| Disk IOPS | Free, Pro | Read/write operations per second with limits | IO bottleneck detection and workload analysis |-| Database connections | Free, Pro | Number of pooler connections to the database | Connection pool monitoring |-| Shared Pooler connections | All | Client connections to the shared pooler | Shared pooler usage patterns |-| Dedicated Pooler connections | All | Client connections to PgBouncer | Dedicated pooler connection monitoring |--</$Show>+| Chart | Available Plans | Description | Key Insights |+| ---------------------------- | --------------- | -------------------------------------------- | -------------------------------------------------------------- |+| Memory usage | Free, Pro | RAM usage percentage by the database | Memory pressure and resource utilization |+| CPU usage | Free, Pro | Average CPU usage percentage | CPU-intensive query identification |+| Disk IOPS | Free, Pro | Read/write operations per second with limits | IO bottleneck detection and workload analysis |+| Database connections | Free, Pro | Number of pooler connections to the database | Connection pool monitoring |+| Dedicated Pooler connections | All | Client connections to PgBouncer | Dedicated pooler connection monitoring |+| Shared Pooler connections | All | Client connections to the shared pooler | Shared pooler usage patterns |+| Shared Pooler connections | All | Client connections to the shared pooler | Shared pooler usage patterns |+| Disk usage | Free, Pro | Disk space consumption breakdown | Storage capacity planning |+| Database size | Free, Pro | Total database size and growth trends | Space consumption monitoring, including list of largest tables |{/* supa-mdx-lint-disable-next-line Rule001HeadingCase */}### Advanced Telemetry+{/* TODO: This is confusing and feels contradictory */}The following charts provide a more advanced and detailed view of your database performance and are available only for Team, Enterprise, and Platform plans.### Memory usage@@ -71,7 +117,7 @@ height={650}| Component | Description || ------------------- | ------------------------------------------------------ || **Used** | RAM actively used by Postgres and the operating system |-| **Cache + buffers** | Memory used for page cache and Postgres buffers |+| **Cache + buffers** | Memory used for page cache and OS buffers || **Free** | Available unallocated memory |How it helps debug issues:@@ -87,8 +133,8 @@ Actions you can take:| Action | Description || --------------------------------------------------------------------------- | ---------------------------------------------- || [Upgrade compute size](/docs/guides/platform/compute-and-disk#compute-size) | Increase available memory resources |-| Optimize queries | Reduce memory consumption of expensive queries |-| Tune Postgres configuration | Improve memory management settings |+| [Optimize queries](/docs/content/guides/database/query-optimization) | Reduce memory consumption of expensive queries |+| [Tune Postgres configuration](https://pgtune.leopard.in.ua) | Improve memory management settings || Implement application caching | Add query result caching to reduce memory load |### CPU usage@@ -123,12 +169,12 @@ How it helps debug issues:Actions you can take:-| Action | Description |-| -------------------------------------------------------------- | --------------------------------------------------------------------------- |-| Optimize CPU-intensive queries | Target queries causing high User CPU usage |-| Address IO bottlenecks | Resolve disk/network issues when IOWait is high |-| [Upgrade compute size](/docs/guides/platform/compute-and-disk) | Increase available CPU capacity |-| Implement proper indexing | Use [query optimization](/docs/guides/database/postgres/indexes) techniques |+| Action | Description |+| ---------------------------------------------------------------------------------- | ----------------------------------------------- |+| [Optimize CPU-intensive queries](/docs/content/guides/database/query-optimization) | Target queries causing high User CPU usage |+| Address IO bottlenecks | Resolve disk/network issues when IOWait is high |+| [Upgrade compute size](/docs/guides/platform/compute-and-disk) | Increase available CPU capacity |+| [Implement proper indexing](/docs/guides/database/postgres/indexes) | Use query optimization techniques |### Disk input/output operations per second (IOPS)@@ -158,8 +204,8 @@ Actions you can take:| Action | Description || -------------------------------------------------------------- | --------------------------------------------------------- |-| Optimize indexing | Reduce high read IOPS through better query indexing |-| Consider read replicas | Distribute read-heavy workloads across multiple instances |+| [Optimize indexing](/docs/guides/database/postgres/indexes) | Reduce high read IOPS through better query indexing |+| Consider [read replicas](/docs/guides/platform/read-replicas) | Distribute read-heavy workloads across multiple instances || Batch write operations | Reduce write IOPS by grouping database writes || [Upgrade compute size](/docs/guides/platform/compute-and-disk) | Increase IOPS limits with larger compute instances |@@ -181,22 +227,25 @@ Actions you can take:| Action | Description || -------------------------------------------------------------- | ------------------------------------------------------------- |-| Optimize query patterns | Reduce large sequential reads/writes |-| Tune caching and batching | Minimize repeated disk access and improve throughput headroom |+| [Optimize disk-intensive queries](/docs/content/guides/database/query-optimization) | Reduce queries that perform excessive reads/writes |+ | Tune caching and batching | Minimize repeated disk access and improve throughput headroom || [Upgrade compute size](/docs/guides/platform/compute-and-disk) | Increase throughput limits for sustained workloads |+| Review database design | Optimize schema and query patterns for efficiency |+| [Add strategic indexes](http://localhost:3001/docs/guides/database/postgres/indexes) | Reduce sequential scans with appropriate indexing |### Disk size<Imagealt="Disk Size chart"+ width={2148}+ height={654}src={{dark: '/docs/img/database/reports/disk-size-chart-dark.png',light: '/docs/img/database/reports/disk-size-chart-light.png',}}-width={2148}-height={654}+/>| Component | Description |@@ -222,6 +271,10 @@ Actions you can take:| Implement data archival | Archive historical data to reduce active storage needs || [Upgrade disk size](/docs/guides/platform/database-size) | Increase storage capacity when approaching limits |+### Query Performance++Links to the [Query Performance Advisory page](/docs/guides/platform/performance#examine-query-performance) in the dashboard, which provides a detailed analysis of slow database queries+### Database connections<Image@@ -261,29 +314,114 @@ Actions you can take:| Implement [connection pooling](/docs/guides/database/connecting-to-postgres#shared-pooler) | Optimize connection management for high direct connection usage || Review application code | Ensure proper connection handling and cleanup |-## Auth+{/* supa-mdx-lint-disable-next-line Rule001HeadingCase */}+### Dedicated Pooler (PgBouncer) Client Connections-The Auth report focuses on user authentication patterns and behaviors within your Supabase project.+Available on Team and Enterprise plans.-| Chart | Description | Key Insights |-| ------------------------ | --------------------------------------------- | ----------------------------------------------- |-| Active Users | Count of unique users performing auth actions | User engagement and retention patterns |-| Sign In Attempts by Type | Breakdown of authentication methods used | Password vs OAuth vs magic link preferences |-| Sign Ups | Total new user registrations | Growth trends and onboarding funnel performance |-| Auth Errors | Error rates grouped by status code | Authentication friction and security issues |-| Password Reset Requests | Volume of password recovery attempts | User experience pain points |+This chart displays the number of PgBouncer connections over time.-## Storage+How it helps debug issues:-The Storage report provides visibility into how your Supabase Storage is being utilized, including request patterns, performance characteristics, and caching effectiveness.+| Issue | Description |+| ------------------------------- | ----------------------------------------------------------- |+| Connection pool exhaustion | Identify when approaching maximum connection limits |+| Connection leak detection | Spot applications not properly closing connections |+| Service distribution monitoring | Monitor connection usage across different Supabase services |++Actions you can take:++| Action | Description |+| ------------------------------------------------------------------------------------------ | --------------------------------------------------------------- |+| [Upgrade compute size](/docs/guides/platform/compute-and-disk#compute-size) | Increase maximum connection limits |+| Implement [connection pooling](/docs/guides/database/connecting-to-postgres#shared-pooler) | Optimize connection management for high direct connection usage |+| Review application code | Ensure proper connection handling and cleanup |++{/* supa-mdx-lint-disable-next-line Rule001HeadingCase */}+### Shared Pooler (Supavisor) Client Connections++Available on Team and Enterprise plans.++This chart displays the number of Supavisor connections over time.++How it helps debug issues:++| Issue | Description |+| ------------------------------- | ----------------------------------------------------------- |+| Connection pool exhaustion | Identify when approaching maximum connection limits |+| Connection leak detection | Spot applications not properly closing connections |+| Service distribution monitoring | Monitor connection usage across different Supabase services |++Actions you can take:++| Action | Description |+| ------------------------------------------------------------------------------------------ | --------------------------------------------------------------- |+| [Upgrade compute size](/docs/guides/platform/compute-and-disk#compute-size) | Increase maximum connection limits |+| Implement [connection pooling](/docs/guides/database/connecting-to-postgres#shared-pooler) | Optimize connection management for high direct connection usage |+| Review application code | Ensure proper connection handling and cleanup |-| Chart | Description | Key Insights |-| --------------- | ------------------------------------------ | ------------------------------------------------------ |-| Total Requests | Overall request volume to Storage | Traffic patterns and usage trends |-| Response Speed | Average response time for storage requests | Performance bottlenecks and optimization opportunities |-| Network Traffic | Ingress and egress usage | Data transfer costs and CDN effectiveness |-| Request Caching | Cache hit rates and miss patterns | CDN performance and cost optimization |-| Top Routes | Most frequently accessed storage paths | Popular content and usage patterns |+### Disk Usage++### Database size++<Image+ alt="Disk Size chart"++ zoomable+ src={{+ dark: '/docs/img/database/reports/disk-size-chart-dark.png',+ light: '/docs/img/database/reports/disk-size-chart-light.png',+ }}++ width={2148}+ height={654}+/>++| Component | Description |+| ------------ | --------------------------------------------------------- |+| **Database** | Space used by your actual database data (tables, indexes) |+| **WAL** | Space used by Write-Ahead Logging |+| **System** | Reserved space for system operations |++How it helps debug issues:++| Issue | Description |+| ----------------------------- | ------------------------------------------- |+| Space consumption monitoring | Track disk usage trends over time |+| Growth pattern identification | Identify rapid growth requiring attention |+| Capacity planning | Plan upgrades before hitting storage limits |++Actions you can take:++| Action | Description |+| -------------------------------------------------------------------------------- | -------------------------------------------------------------------- |+| Run [VACUUM](https://www.postgresql.org/docs/current/sql-vacuum.html) operations | Reclaim dead tuple space and optimize storage |+| Analyze large tables | Use CLI commands like `table-sizes` to identify optimization targets |+| Implement data archival | Archive historical data to reduce active storage needs |+| [Upgrade disk size](/docs/guides/platform/database-size) | Increase storage capacity when approaching limits |++## Edge Functions++The Edge Functions report provides insights into serverless function performance, execution patterns, and regional distribution across Supabase's global edge network.++| Chart | Description | Key Insights |+| ------------------------------------ | ----------------------------------------- | ---------------------------------------------- |+| Total Edge Function Invocations | Function response codes and error rates | Function reliability and error patterns |+| Edge Function Execution Status Codes | Function response codes and error rates | Function reliability and error patterns |+| Edge Function Execution Time | Average function duration and performance | Performance optimization opportunities |+| Edge Function Invocations by Region | Geographic distribution of function calls | Global usage patterns and latency optimization |+++## PostgREST++The PostgREST report provides insights into RESTful API performance, request patterns, and response characteristics.++| Chart | Description | Key Insights |+| --------------- | -------------------------------------------- | ---------------------------------------------------------------------------- |+| Total Requests | HTTP requests to PostgREST endpoints | API usage alongside WebSocket activity |+| Response Errors | Error rates with 4XX and 5XX status codes | API reliability and user experience issues, including top routes |+| Response Speed | Average response time for PostgREST requests | Performance bottlenecks and optimization opportunities, including top routes |+| Network Traffic | Ingress and egress usage | Data transfer costs and CDN effectiveness |## Realtime@@ -291,7 +429,7 @@ The Realtime report tracks WebSocket connections, channel activity, and real-tim| Chart | Description | Key Insights || ---------------------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------- |-| Realtime Connections | Active WebSocket connections over time | Concurrent user activity and connection stability |+| Connected Clients | Active WebSocket connections over time | Concurrent user activity and connection stability || Broadcast Events | Broadcast events over time | Real-time feature usage patterns || Presence Events | Presence events over time | Real-time feature usage patterns || Postgres Changes Events | Postgres Changes events over time | Real-time feature usage patterns |@@ -302,24 +440,25 @@ The Realtime report tracks WebSocket connections, channel activity, and real-tim| Total Requests | HTTP requests to Realtime endpoints | API usage alongside WebSocket activity || Response Speed | Performance of Realtime API endpoints | Infrastructure optimization opportunities |-## Edge Functions+### Realtime API Gateway-The Edge Functions report provides insights into serverless function performance, execution patterns, and regional distribution across Supabase's global edge network.+The Realtime API Gateway reports focus on API requests related to Realtime functionality.-| Chart | Description | Key Insights |-| ---------------------- | ----------------------------------------- | ---------------------------------------------- |-| Execution Status Codes | Function response codes and error rates | Function reliability and error patterns |-| Execution Time | Average function duration and performance | Performance optimization opportunities |-| Invocations by Region | Geographic distribution of function calls | Global usage patterns and latency optimization |+| Chart | Description | Key Insights |+| --------------- | ------------------------------------- | --------------------------------------------------------------- |+| Total Requests | HTTP requests to Realtime endpoints | API usage alongside WebSocket activity, including top routes |+| Response Errors | HTTP requests to Realtime endpoints | API usage alongside WebSocket activity, including top routes |+| Response Speed | Performance of Realtime API endpoints | Infrastructure optimization opportunities, including top routes |-## API gateway+## Storage-The API Gateway report analyzes traffic patterns and performance characteristics of requests flowing through your Supabase project's API layer.+The Storage report provides visibility into how your Supabase Storage is being utilized, including request patterns, performance characteristics, and caching effectiveness.++| Chart | Description | Key Insights |+| --------------- | ------------------------------------------ | ---------------------------------------------------------------------------- |+| Total Requests | Overall request volume to Storage | Traffic patterns and usage trends, including top routes |+| Response Speed | Average response time for storage requests | Performance bottlenecks and optimization opportunities, including top routes |+| Network Traffic | Ingress and egress usage | Data transfer costs and CDN effectiveness |+| Request Caching | Cache hit rates and miss patterns | CDN performance and cost optimization, including top routes |-| Chart | Description | Key Insights |-| --------------- | ----------------------------------------- | ------------------------------------------------ |-| Total Requests | Overall API request volume | Traffic patterns and growth trends |-| Response Errors | Error rates with 4XX and 5XX status codes | API reliability and user experience issues |-| Response Speed | Average API response times | Performance bottlenecks and optimization targets |-| Network Traffic | Request and response egress usage | Data transfer patterns and cost implications |-| Top Routes | Most frequently accessed API endpoints | Usage patterns and optimization priorities |+</$Show>diff --git a/supa-mdx-lint/Rule001HeadingCase.toml b/supa-mdx-lint/Rule001HeadingCase.tomlindex dee51c8459d..d38ddd5fcce 100644--- a/supa-mdx-lint/Rule001HeadingCase.toml+++ b/supa-mdx-lint/Rule001HeadingCase.toml@@ -16,6 +16,7 @@ may_uppercase = ["Assistant","Audit Logs?","Auth",+ "Auth API Gateway","Auth0","Auth0 Actions?","AWS Marketplace",@@ -51,6 +52,7 @@ may_uppercase = ["Dashboard","Database Functions?","Deadpool",+ "Dedicated Pooler","Deno","DigitalOcean","Discord",@@ -172,7 +174,7 @@ may_uppercase = ["Prometheus","PyIceberg","Python",- "Qodo Gen",+ "Qodo Gen","Queues?","Quotas","Query Performance",@@ -181,6 +183,7 @@ may_uppercase = ["React Email","React Native","Read Replicas?",+ "Realtime API Gateway","Realtime","Reciprocal Ranked Fusion","Redis",@@ -196,6 +199,7 @@ may_uppercase = ["Sentry","Server-Side Auth","Server-Side Rendering",+ "Shared Pooler","Single Sign-On","Slack","Slack Developers?",