chore: add docs for new db reports charts (#36703)

* chore: add docs for new db reports charts * chore: fix linting issues * move db reports docs to telemetry section * add more info to reports docs * fix lint suggestions * update reports * update latest links and chart screenshots * advanced telemetry * update db section
2026-10-05 09:25:06 +03:00 · 2025-07-17 12:40:12 +00:00
1 parent a797ae2674
commit fb6f625707
@@ -2357,6 +2357,10 @@ export const telemetry: NavMenuConstant = {
          name: 'Log drains',
          url: '/guides/telemetry/log-drains',
        },
+        {
+          name: 'Reports',
+          url: '/guides/telemetry/reports',
+        },
        {
          name: 'Metrics',
          url: '/guides/telemetry/metrics',
@@ -23,6 +23,32 @@ These numbers are generalizations and depends on other Supabase products that yo

 ### Capturing historical usage

+#### Dashboard monitoring charts
+
+<Image
+  alt="Database client connections chart"
+  zoomable
+  src={{
+    dark: '/docs/img/database/reports/db-connections-chart-dark.png',
+    light: '/docs/img/database/reports/db-connections-chart-light.png',
+  }}
+/>
+
+For Teams and Enterprise plans, Supabase provides Advanced Telemetry charts directly within the Dashboard. The `Database client connections` chart displays historical connection data broken down by connection type:
+
+- **Postgres**: Direct connections from your application
+- **PostgREST**: Connections from the PostgREST API layer
+- **Reserved**: Administrative connections for Supabase services
+- **Auth**: Connections from Supabase Auth service
+- **Storage**: Connections from Supabase Storage service
+- **Other roles**: Miscellaneous database connections
+
+This chart helps you monitor connection pool usage, identify connection leaks, and plan capacity. It also shows a reference line for your compute size's maximum connection limit.
+
+For more details on using these monitoring charts, see the [Reports guide](/docs/guides/telemetry/reports#advanced-telemetry).
+
+#### Grafana Dashboard
+
 Supabase offers a Grafana Dashboard that records and visualizes over 200 project metrics, including connections. For setup instructions, check the [metrics docs](/docs/guides/platform/metrics).

 Its "Client Connections" graph displays connections for both Supavisor and Postgres
@@ -0,0 +1,309 @@
+---
+id: 'reports'
+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.
+
+<Admonition type="note">
+
+Reports are only available for projects hosted on the Supabase Cloud platform and are not available for self-hosted instances.
+
+</Admonition>
+
+## 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.
+
+| Time Range      | Free | Pro | Team | Enterprise |
+| --------------- | ---- | --- | ---- | ---------- |
+| Last 10 minutes | ✅   | ✅  | ✅   | ✅         |
+| Last 30 minutes | ✅   | ✅  | ✅   | ✅         |
+| Last 60 minutes | ✅   | ✅  | ✅   | ✅         |
+| Last 3 hours    | ✅   | ✅  | ✅   | ✅         |
+| Last 24 hours   | ✅   | ✅  | ✅   | ✅         |
+| Last 7 days     | ❌   | ✅  | ✅   | ✅         |
+| Last 14 days    | ❌   | ❌  | ✅   | ✅         |
+| Last 28 days    | ❌   | ❌  | ✅   | ✅         |
+
+---
+
+## 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 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        |
+
+{/* supa-mdx-lint-disable-next-line Rule001HeadingCase */}
+
+### Advanced Telemetry
+
+The following charts provide a more advanced and detailed view of your database performance and are available only for Teams and Enterprise plans.
+
+### Memory usage
+
+<Image
+  alt="Memory usage chart"
+  zoomable
+  src={{
+    dark: '/docs/img/database/reports/memory-usage-chart-dark.png',
+    light: '/docs/img/database/reports/memory-usage-chart-light.png',
+  }}
+/>
+
+| Component           | Description                                            |
+| ------------------- | ------------------------------------------------------ |
+| **Used**            | RAM actively used by Postgres and the operating system |
+| **Cache + buffers** | Memory used for page cache and Postgres buffers        |
+| **Free**            | Available unallocated memory                           |
+
+How it helps debug issues:
+
+| Issue                          | Description                                      |
+| ------------------------------ | ------------------------------------------------ |
+| Memory pressure detection      | Identify when free memory is consistently low    |
+| Cache effectiveness monitoring | Monitor cache performance for query optimization |
+| Memory leak detection          | Detect inefficient memory usage patterns         |
+
+Actions you can take:
+
+| Action                                                                                          | Description                                    |
+| ----------------------------------------------------------------------------------------------- | ---------------------------------------------- |
+| [Upgrade compute size](https://supabase.com/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             |
+| Implement application caching                                                                   | Add query result caching to reduce memory load |
+
+### CPU usage
+
+<Image
+  alt="CPU usage chart"
+  zoomable
+  src={{
+    dark: '/docs/img/database/reports/cpu-usage-chart-dark.png',
+    light: '/docs/img/database/reports/cpu-usage-chart-light.png',
+  }}
+/>
+
+| Category   | Description                                      |
+| ---------- | ------------------------------------------------ |
+| **System** | CPU time for kernel operations                   |
+| **User**   | CPU time for database queries and user processes |
+| **IOWait** | CPU time waiting for disk/network IO             |
+| **IRQs**   | CPU time handling interrupts                     |
+| **Other**  | CPU time for miscellaneous tasks                 |
+
+How it helps debug issues:
+
+| Issue                              | Description                                        |
+| ---------------------------------- | -------------------------------------------------- |
+| CPU-intensive query identification | Identify expensive queries when User CPU is high   |
+| IO bottleneck detection            | Detect disk/network issues when IOWait is elevated |
+| System overhead monitoring         | Monitor resource contention and kernel overhead    |
+
+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 |
+
+### Disk input/output operations per second (IOPS)
+
+<Image
+  alt="Disk IOPS chart"
+  zoomable
+  src={{
+    dark: '/docs/img/database/reports/disk-iops-chart-dark.png',
+    light: '/docs/img/database/reports/disk-iops-chart-light.png',
+  }}
+/>
+
+This chart displays read and write IOPS with a reference line showing your compute size's maximum IOPS capacity.
+
+How it helps debug issues:
+
+| Issue                             | Description                                                      |
+| --------------------------------- | ---------------------------------------------------------------- |
+| Disk IO bottleneck identification | Identify when disk IO becomes a performance constraint           |
+| Workload pattern analysis         | Distinguish between read-heavy vs write-heavy operations         |
+| Performance correlation           | Spot disk activity spikes that correlate with performance issues |
+
+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 |
+| Batch write operations                                                             | Reduce write IOPS by grouping database writes             |
+| [Upgrade compute size](https://supabase.com/docs/guides/platform/compute-and-disk) | Increase IOPS limits with larger compute instances        |
+
+### Disk IO Usage
+
+<Image
+  alt="Disk IO Usage chart"
+  zoomable
+  src={{
+    dark: '/docs/img/database/reports/disk-io-chart-dark.png',
+    light: '/docs/img/database/reports/disk-io-chart-light.png',
+  }}
+/>
+
+This chart displays the percentage of your allocated IOPS (Input/Output Operations Per Second) currently being used.
+
+How it helps debug issues:
+
+| Issue                       | Description                                                 |
+| --------------------------- | ----------------------------------------------------------- |
+| IOPS limit monitoring       | Identify when approaching your allocated IOPS capacity      |
+| Performance correlation     | Correlate high IO usage with application performance issues |
+| Operation impact assessment | Monitor how database operations affect disk performance     |
+
+Actions you can take:
+
+| Action                                                                             | Description                                        |
+| ---------------------------------------------------------------------------------- | -------------------------------------------------- |
+| Optimize disk-intensive queries                                                    | Reduce queries that perform excessive reads/writes |
+| Add strategic indexes                                                              | Reduce sequential scans with appropriate indexing  |
+| [Upgrade compute size](https://supabase.com/docs/guides/platform/compute-and-disk) | Increase IOPS limits with larger compute instances |
+| Review database design                                                             | Optimize schema and query patterns for efficiency  |
+
+### Disk 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',
+  }}
+/>
+
+| 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](https://supabase.com/docs/guides/platform/database-size)     | Increase storage capacity when approaching limits                    |
+
+### Database connections
+
+<Image
+  alt="Database connections chart"
+  zoomable
+  src={{
+    dark: '/docs/img/database/reports/db-connections-chart-dark.png',
+    light: '/docs/img/database/reports/db-connections-chart-light.png',
+  }}
+/>
+
+| Connection Type | Description                                      |
+| --------------- | ------------------------------------------------ |
+| **Postgres**    | Direct connections from your application         |
+| **PostgREST**   | Connections from the PostgREST API layer         |
+| **Reserved**    | Administrative connections for Supabase services |
+| **Auth**        | Connections from Supabase Auth service           |
+| **Storage**     | Connections from Supabase Storage service        |
+| **Other roles** | Miscellaneous database connections               |
+
+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](https://supabase.com/docs/guides/platform/compute-and-disk#compute-size)                | Increase maximum connection limits                              |
+| Implement [connection pooling](https://supabase.com/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
+
+The Auth report focuses 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 |
+| 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                     |
+
+## Storage
+
+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                      |
+| Response Speed  | Average response time for storage requests | Performance bottlenecks and optimization opportunities |
+| Network Traffic | Ingress and egress bandwidth 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                     |
+
+## Realtime
+
+The Realtime report tracks WebSocket connections, channel activity, and real-time event patterns in your Supabase project.
+
+| Chart                 | Description                                                   | Key Insights                                      |
+| --------------------- | ------------------------------------------------------------- | ------------------------------------------------- |
+| Realtime Connections  | Active WebSocket connections over time                        | Concurrent user activity and connection stability |
+| Channel Events        | Breakdown of broadcast, Postgres changes, and presence events | Real-time feature usage patterns                  |
+| Rate of Channel Joins | Frequency of new channel subscriptions                        | User engagement with real-time features           |
+| Total Requests        | HTTP requests to Realtime endpoints                           | API usage alongside WebSocket activity            |
+| Response Speed        | Performance of Realtime API endpoints                         | Infrastructure optimization opportunities         |
+
+## 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                                   |
+| ---------------------- | ----------------------------------------- | ---------------------------------------------- |
+| 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 |
+
+## API gateway
+
+The API Gateway report analyzes traffic patterns and performance characteristics of requests flowing through your Supabase project's API layer.
+
+| 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 bandwidth usage      | Data transfer patterns and cost implications     |
+| Top Routes      | Most frequently accessed API endpoints    | Usage patterns and optimization priorities       |
@@ -199,6 +199,7 @@ export const getReportAttributesV2: (org: Organization, project: Project) => Rep
    {
      id: 'ram-usage',
      label: 'Memory usage',
+      docsUrl: 'https://supabase.com/docs/guides/telemetry/reports#memory-usage',
      availableIn: ['team', 'enterprise'],
      hide: false,
      showTooltip: true,
@@ -240,6 +241,7 @@ export const getReportAttributesV2: (org: Organization, project: Project) => Rep
    {
      id: 'cpu-usage',
      label: 'CPU usage',
+      docsUrl: 'https://supabase.com/docs/guides/telemetry/reports#cpu-usage',
      syncId: 'database-reports',
      format: '%',
      valuePrecision: 2,
@@ -308,6 +310,8 @@ export const getReportAttributesV2: (org: Organization, project: Project) => Rep
    {
      id: 'disk-iops',
      label: 'Disk Input/Output operations per second (IOPS)',
+      docsUrl:
+        'https://supabase.com/docs/guides/telemetry/reports#disk-inputoutput-operations-per-second-iops',
      syncId: 'database-reports',
      availableIn: ['team', 'enterprise'],
      hide: false,
@@ -322,7 +326,6 @@ export const getReportAttributesV2: (org: Organization, project: Project) => Rep
        tickFormatter: (value: any) => numberFormatter(value, 2),
      },
      defaultChartStyle: 'line',
-      docsUrl: 'https://supabase.com/docs/guides/platform/compute-and-disk#compute-size',
      attributes: [
        {
          attribute: 'disk_iops_write',
@@ -352,6 +355,7 @@ export const getReportAttributesV2: (org: Organization, project: Project) => Rep
    {
      id: 'disk-io-usage',
      label: 'Disk IO Usage',
+      docsUrl: 'https://supabase.com/docs/guides/telemetry/reports#disk-io-usage',
      syncId: 'database-reports',
      availableIn: ['team', 'enterprise'],
      hide: false,
@@ -391,6 +395,7 @@ export const getReportAttributesV2: (org: Organization, project: Project) => Rep
      showGrid: true,
      YAxisProps: { width: 30 },
      defaultChartStyle: 'line',
+      docsUrl: 'https://supabase.com/docs/guides/telemetry/reports#database-connections',
      attributes: [
        {
          attribute: 'client_connections_postgres',
@@ -512,7 +517,7 @@ export const getReportAttributesV2: (org: Organization, project: Project) => Rep
      },
      hideChartType: false,
      defaultChartStyle: 'line',
-      docsUrl: 'https://supabase.com/docs/guides/platform/database-size',
+      docsUrl: 'https://supabase.com/docs/guides/telemetry/reports#disk-size',
      attributes: [
        {
          attribute: 'disk_fs_used_system',