diff --git a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts index a0e9c1bacfd..df0dfca94ee 100644 --- a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts +++ b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts @@ -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', diff --git a/apps/docs/content/guides/database/connection-management.mdx b/apps/docs/content/guides/database/connection-management.mdx index 4a13b4aa4e5..bd763d7e7cf 100644 --- a/apps/docs/content/guides/database/connection-management.mdx +++ b/apps/docs/content/guides/database/connection-management.mdx @@ -23,6 +23,32 @@ These numbers are generalizations and depends on other Supabase products that yo ### Capturing historical usage +#### Dashboard monitoring charts + +Database client connections chart + +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 diff --git a/apps/docs/content/guides/telemetry/reports.mdx b/apps/docs/content/guides/telemetry/reports.mdx new file mode 100644 index 00000000000..34fbd117671 --- /dev/null +++ b/apps/docs/content/guides/telemetry/reports.mdx @@ -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. + + + +Reports are only available for projects hosted on the Supabase Cloud platform and are not available for self-hosted instances. + + + +## 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 + +Memory usage chart + +| 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 + +CPU usage chart + +| 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) + +Disk IOPS chart + +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 + +Disk IO Usage chart + +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 + +Disk Size chart + +| 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 + +Database connections chart + +| 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 | diff --git a/apps/docs/public/img/database/reports/cpu-usage-chart-dark.png b/apps/docs/public/img/database/reports/cpu-usage-chart-dark.png new file mode 100644 index 00000000000..191ae831653 Binary files /dev/null and b/apps/docs/public/img/database/reports/cpu-usage-chart-dark.png differ diff --git a/apps/docs/public/img/database/reports/cpu-usage-chart-light.png b/apps/docs/public/img/database/reports/cpu-usage-chart-light.png new file mode 100644 index 00000000000..0b688ec967d Binary files /dev/null and b/apps/docs/public/img/database/reports/cpu-usage-chart-light.png differ diff --git a/apps/docs/public/img/database/reports/db-connections-chart-dark.png b/apps/docs/public/img/database/reports/db-connections-chart-dark.png new file mode 100644 index 00000000000..44d7f75f02d Binary files /dev/null and b/apps/docs/public/img/database/reports/db-connections-chart-dark.png differ diff --git a/apps/docs/public/img/database/reports/db-connections-chart-light.png b/apps/docs/public/img/database/reports/db-connections-chart-light.png new file mode 100644 index 00000000000..27d5ff8d70c Binary files /dev/null and b/apps/docs/public/img/database/reports/db-connections-chart-light.png differ diff --git a/apps/docs/public/img/database/reports/disk-io-chart-dark.png b/apps/docs/public/img/database/reports/disk-io-chart-dark.png new file mode 100644 index 00000000000..5f9f8282e34 Binary files /dev/null and b/apps/docs/public/img/database/reports/disk-io-chart-dark.png differ diff --git a/apps/docs/public/img/database/reports/disk-io-chart-light.png b/apps/docs/public/img/database/reports/disk-io-chart-light.png new file mode 100644 index 00000000000..5eb835474c5 Binary files /dev/null and b/apps/docs/public/img/database/reports/disk-io-chart-light.png differ diff --git a/apps/docs/public/img/database/reports/disk-iops-chart-dark.png b/apps/docs/public/img/database/reports/disk-iops-chart-dark.png new file mode 100644 index 00000000000..74ffd527949 Binary files /dev/null and b/apps/docs/public/img/database/reports/disk-iops-chart-dark.png differ diff --git a/apps/docs/public/img/database/reports/disk-iops-chart-light.png b/apps/docs/public/img/database/reports/disk-iops-chart-light.png new file mode 100644 index 00000000000..ce7cf5d40e4 Binary files /dev/null and b/apps/docs/public/img/database/reports/disk-iops-chart-light.png differ diff --git a/apps/docs/public/img/database/reports/disk-size-chart-dark.png b/apps/docs/public/img/database/reports/disk-size-chart-dark.png new file mode 100644 index 00000000000..beb3df95327 Binary files /dev/null and b/apps/docs/public/img/database/reports/disk-size-chart-dark.png differ diff --git a/apps/docs/public/img/database/reports/disk-size-chart-light.png b/apps/docs/public/img/database/reports/disk-size-chart-light.png new file mode 100644 index 00000000000..8a1fa264a57 Binary files /dev/null and b/apps/docs/public/img/database/reports/disk-size-chart-light.png differ diff --git a/apps/docs/public/img/database/reports/memory-usage-chart-dark.png b/apps/docs/public/img/database/reports/memory-usage-chart-dark.png new file mode 100644 index 00000000000..93b6d401930 Binary files /dev/null and b/apps/docs/public/img/database/reports/memory-usage-chart-dark.png differ diff --git a/apps/docs/public/img/database/reports/memory-usage-chart-light.png b/apps/docs/public/img/database/reports/memory-usage-chart-light.png new file mode 100644 index 00000000000..006626c2027 Binary files /dev/null and b/apps/docs/public/img/database/reports/memory-usage-chart-light.png differ diff --git a/apps/studio/data/reports/database-charts.ts b/apps/studio/data/reports/database-charts.ts index 1a884dcc277..1c7fcb47d33 100644 --- a/apps/studio/data/reports/database-charts.ts +++ b/apps/studio/data/reports/database-charts.ts @@ -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',