From 116f90bf59e25766ed116eac6ff080cd28b3755e Mon Sep 17 00:00:00 2001 From: Saxon Fletcher Date: Tue, 1 Sep 2026 14:21:59 +1000 Subject: [PATCH] docs: address observability source review --- .../content/guides/monitoring-and-debugging/advisors.mdx | 2 +- .../content/guides/monitoring-and-debugging/inspect.mdx | 6 ++++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/apps/docs/content/guides/monitoring-and-debugging/advisors.mdx b/apps/docs/content/guides/monitoring-and-debugging/advisors.mdx index ad6742b122e..8f3e1aa818c 100644 --- a/apps/docs/content/guides/monitoring-and-debugging/advisors.mdx +++ b/apps/docs/content/guides/monitoring-and-debugging/advisors.mdx @@ -12,7 +12,7 @@ You or an agent can pull the same checks from: - Studio: [Security Advisor](/dashboard/project/_/advisors/security) and [Performance Advisor](/dashboard/project/_/advisors/performance) - MCP: `get_advisors` -- CLI: [`supabase db advisors`](/docs/reference/cli/usage#supabase-db-advisors) +- CLI: [`supabase db advisors`](/docs/reference/cli/supabase-db-advisors) - Management API: [security advisors](/docs/reference/api/v1-get-security-advisors) and [performance advisors](/docs/reference/api/v1-get-performance-advisors) The advisors run automatically in Studio. Rerun them after you resolve an issue. diff --git a/apps/docs/content/guides/monitoring-and-debugging/inspect.mdx b/apps/docs/content/guides/monitoring-and-debugging/inspect.mdx index 8e2e3c7ef65..b128c9b6b27 100644 --- a/apps/docs/content/guides/monitoring-and-debugging/inspect.mdx +++ b/apps/docs/content/guides/monitoring-and-debugging/inspect.mdx @@ -4,7 +4,9 @@ title: 'Inspect the database' description: 'Read live Postgres statistics such as bloat, cache hit rate, locks, and slow queries from the CLI, SQL Editor, or MCP.' --- -This guide explains how to inspect live Postgres statistics. The same checks run as `supabase inspect db` commands, as SQL in the [SQL Editor](/dashboard/project/_/sql), or as MCP `execute_sql`. +Database performance is a large topic and many factors can contribute. Common causes of poor performance include inefficient schemas or queries, missing or unused indexes, insufficient memory, lock contention, and table bloat. + +Use the live Postgres statistics in this guide to check for those conditions. The same checks run as `supabase inspect db` commands, as SQL in the [SQL Editor](/dashboard/project/_/sql), or as MCP `execute_sql`. Use this page to: @@ -236,6 +238,6 @@ from pg_statio_user_tables; This shows the ratio of data blocks fetched from the Postgres [shared_buffers](https://www.postgresql.org/docs/15/runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-MEMORY) cache against the data blocks that were read from disk or the OS cache. -A ratio below 99% means Postgres is reading from disk more than from cache. Treat that as a performance signal in the [debugging guide](/docs/guides/monitoring-and-debugging/debugging), then search [troubleshooting](/docs/guides/troubleshooting). +A ratio below 99% means more than 1% of observed block accesses missed `shared_buffers`. Postgres cannot distinguish whether those reads were served by the operating system cache or physical disk. Treat that as a performance signal in the [debugging guide](/docs/guides/monitoring-and-debugging/debugging), then search [troubleshooting](/docs/guides/troubleshooting). When a check names a slow statement, get a query plan with [`explain`](/docs/guides/database/query-optimization#analyze-the-query-plan) in SQL, or [`explain()`](/docs/guides/database/debugging-performance) on the Data API. Pair `pg_stat_statements` with the [Metrics API](/docs/guides/monitoring-and-debugging/metrics) to read the same window from Postgres stats and host metrics.