From 4c716df063d21a56ff2ae0d1525b8948288cf0ce Mon Sep 17 00:00:00 2001 From: Saxon Fletcher Date: Fri, 4 Sep 2026 13:38:37 +1000 Subject: [PATCH] docs: add Observe the data hub for logs, metrics, and advisors (#49502) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Stack Draft stack extracted from `docs/monitoring`. Merge bottom-up. Troubleshooting / debugging-guide rewrite is out of scope. 1. #49503 move inspect and advisors 2. #49501 split Studio logs from ClickHouse queries 3. #49500 treat reports as signal dashboards 4. **#49502** add Observe the data hub ← **this PR** 5. #49506 add agent setup components 6. #49504 add hire-an-agent templates 7. #49505 restructure observability nav and overview ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Docs update. Fourth layer in the observability stack. ## What is the current behavior? There is no single page that maps what you can observe (logs, metrics, database, advisors) to where you query it (MCP, API, CLI, Studio). ## What is the new behavior? Adds `/guides/monitoring-and-debugging/access-data` as that hub, with content listings and nav. Inspect and Query and filter logs now point here for MCP/CLI context. ## Additional context This page is the spine of the new observability IA. Later PRs add agent templates and restructure the sidebar around it.
Open in Web Open in Cursor 
--------- Co-authored-by: Cursor Agent Co-authored-by: Saxon Fletcher --- .../NavigationMenu.constants.ts | 4 + .../monitoring-and-debugging/access-data.mdx | 80 +++++++++++++++++++ .../advanced-log-filtering.mdx | 4 +- .../monitoring-and-debugging/inspect.mdx | 2 +- apps/docs/data/content-listings/index.ts | 9 ++- .../data/content-listings/telemetry.data.ts | 65 +++++++++++++++ 6 files changed, 160 insertions(+), 4 deletions(-) create mode 100644 apps/docs/content/guides/monitoring-and-debugging/access-data.mdx diff --git a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts index a32458105d8..87826a30826 100644 --- a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts +++ b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts @@ -3025,6 +3025,10 @@ export const telemetry: NavMenuConstant = { url: '/guides/monitoring-and-debugging', items: [ { name: 'Overview', url: '/guides/monitoring-and-debugging' }, + { + name: 'Observe the data', + url: '/guides/monitoring-and-debugging/access-data' as `/${string}`, + }, { name: 'Debugging', url: undefined, diff --git a/apps/docs/content/guides/monitoring-and-debugging/access-data.mdx b/apps/docs/content/guides/monitoring-and-debugging/access-data.mdx new file mode 100644 index 00000000000..60299f687fb --- /dev/null +++ b/apps/docs/content/guides/monitoring-and-debugging/access-data.mdx @@ -0,0 +1,80 @@ +--- +id: 'access-data' +title: 'Observe the data' +description: 'Query logs, metrics, and database diagnostics from MCP, the CLI, the API, or Studio.' +--- + +This guide explains how to observe a Supabase project. + +Use this page to: + +- See [what data you can observe](#what-data-you-can-observe) +- Choose [where you can observe it](#access-via) + +## What data you can observe [#what-data-you-can-observe] + +The sources are logs, metrics, live Postgres diagnostics, and advisor findings. Open Logs and Reports in Studio when you want a UI on those sources. See [where you can observe it](#access-via). + +### Logs + +Request, database, Auth, Storage, Realtime, and function events in ClickHouse. + +- [Query and filter logs](/docs/guides/monitoring-and-debugging/advanced-log-filtering) — run ClickHouse SQL from Studio, MCP, the API, or a script. Record extra Postgres, API, and Realtime events. +- [Logs field reference](/docs/guides/monitoring-and-debugging/log-field-reference) — sources and fields + +### Metrics [#metrics-api] + +Prometheus-compatible CPU, IO, WAL, connections, and query stats. Scrape the [Metrics API](/docs/guides/monitoring-and-debugging/metrics) for custom dashboards, alerting, or retention beyond Studio. + +### Database + +Live Postgres statistics such as bloat, cache hit rate, blocking sessions, index usage, and slow queries. See [Inspect the database](/docs/guides/monitoring-and-debugging/inspect) (`supabase inspect db`) for the command and SQL catalog. + +MCP `execute_sql` can run the same read-only queries. + +### Advisors + +Deterministic security and performance findings. Pull them from [Advisors](/docs/guides/monitoring-and-debugging/advisors). + +## Where you can observe it [#access-via] + +Use the interface that matches where you are working. + +### MCP [#mcp] + +Configure the [Supabase MCP server](/docs/guides/ai-tools/mcp) for one project with read-only mode. The debugging tools are: + +- `query_logs` for bounded log queries. Use the same ClickHouse SQL as [Query and filter logs](/docs/guides/monitoring-and-debugging/advanced-log-filtering). +- `execute_sql` for read-only database inspection +- `get_advisors` for security and performance findings + +Ask the agent to inspect a time window, error code, or advisor finding. Keep production connections project-scoped and read-only. + +### API [#api] + +Use the Management API when you want the same data from a script: + +- [Query project logs](/docs/reference/api/v1-get-project-logs). Pass ClickHouse SQL in the `sql` parameter. See [Query and filter logs](/docs/guides/monitoring-and-debugging/advanced-log-filtering). +- [Security advisors](/docs/reference/api/v1-get-security-advisors) and [performance advisors](/docs/reference/api/v1-get-performance-advisors) +- [API usage counts](/docs/reference/api/v1-get-project-usage-api-count) + +Scrape the [Metrics API](/docs/guides/monitoring-and-debugging/metrics) for Prometheus-compatible database series. That endpoint is a project URL, not a Management API route. + +### CLI [#cli] + +Use the [Supabase CLI](/docs/guides/local-development/cli/getting-started) against a linked project: + +- [`supabase inspect db`](/docs/guides/monitoring-and-debugging/inspect) for the database diagnostic catalog +- [`supabase db advisors`](/docs/reference/cli/usage#supabase-db-advisors) for security and performance findings + +Run `supabase inspect db help` on the installed CLI to see the reports available in your version. + +### Studio [#studio] + +Use Studio when you want to inspect the project in the browser: + +- [Logs](/docs/guides/monitoring-and-debugging/logs) for the unified Logs view +- [Reports](/docs/guides/monitoring-and-debugging/reports) for API, Auth, Storage, Realtime, and database dashboards +- [Advisors](/docs/guides/monitoring-and-debugging/advisors) for deterministic security and performance findings + +To send logs or traces to your own stack, see [Log drains](/docs/guides/monitoring-and-debugging/log-drains), [Client-side tracing](/docs/guides/monitoring-and-debugging/client-side-tracing), and [Sentry integration](/docs/guides/monitoring-and-debugging/sentry-monitoring). diff --git a/apps/docs/content/guides/monitoring-and-debugging/advanced-log-filtering.mdx b/apps/docs/content/guides/monitoring-and-debugging/advanced-log-filtering.mdx index eff1d16f71d..642c363f96a 100644 --- a/apps/docs/content/guides/monitoring-and-debugging/advanced-log-filtering.mdx +++ b/apps/docs/content/guides/monitoring-and-debugging/advanced-log-filtering.mdx @@ -30,7 +30,7 @@ Open [Logs](/dashboard/project/_/logs) to filter and inspect events. Open the [L ### MCP [#mcp] -On hosted projects, call [`query_logs`](/docs/guides/ai-tools/mcp) with the same SQL as this guide. Keep the connection project-scoped and read-only. +On hosted projects, call [`query_logs`](/docs/guides/ai-tools/mcp) with the same SQL as this guide. Keep the connection project-scoped and read-only. See [Observe the data](/docs/guides/monitoring-and-debugging/access-data#mcp). ### API [#api] @@ -38,7 +38,7 @@ Pass ClickHouse SQL in the `sql` parameter of the [Management API logs endpoint] ### CLI [#cli] -The Supabase CLI does not query ClickHouse logs. Call the [Management API](/docs/reference/api/v1-get-project-logs) from a script, or use [`supabase inspect db`](/docs/guides/monitoring-and-debugging/inspect) for database diagnostics. +The Supabase CLI does not query ClickHouse logs. Call the [Management API](/docs/reference/api/v1-get-project-logs) from a script, or use [`supabase inspect db`](/docs/guides/monitoring-and-debugging/inspect) for database diagnostics. See [Observe the data](/docs/guides/monitoring-and-debugging/access-data#cli). ## Sources [#logs-explorer] diff --git a/apps/docs/content/guides/monitoring-and-debugging/inspect.mdx b/apps/docs/content/guides/monitoring-and-debugging/inspect.mdx index b128c9b6b27..8169aeda1e9 100644 --- a/apps/docs/content/guides/monitoring-and-debugging/inspect.mdx +++ b/apps/docs/content/guides/monitoring-and-debugging/inspect.mdx @@ -13,7 +13,7 @@ Use this page to: - Run [CLI inspection commands](#using-the-cli) - Copy the matching [SQL](#using-sql) -If you are checking whether something is wrong, start with the [debugging guide](/docs/guides/monitoring-and-debugging/debugging). For project logs and metrics, see the [Monitoring and Debugging overview](/docs/guides/monitoring-and-debugging). +If you are checking whether something is wrong, start with the [debugging guide](/docs/guides/monitoring-and-debugging/debugging). For project logs, metrics, and advisors, see [Observe the data](/docs/guides/monitoring-and-debugging/access-data). ## Using the CLI diff --git a/apps/docs/data/content-listings/index.ts b/apps/docs/data/content-listings/index.ts index cd9935a9e6b..f7b357f9c6e 100644 --- a/apps/docs/data/content-listings/index.ts +++ b/apps/docs/data/content-listings/index.ts @@ -27,7 +27,12 @@ import { selfHostingSupport, } from './self-hosting.data' import { storageExamples, storageGetStarted, storageResources } from './storage.data' -import { telemetryDebugging, telemetryMonitoring } from './telemetry.data' +import { + telemetryAccessWhat, + telemetryAccessWhere, + telemetryDebugging, + telemetryMonitoring, +} from './telemetry.data' const ALL_GROUPS: readonly ContentListingGroup[] = [ aiToolsSupportedAgents, @@ -63,6 +68,8 @@ const ALL_GROUPS: readonly ContentListingGroup[] = [ storageResources, telemetryDebugging, telemetryMonitoring, + telemetryAccessWhat, + telemetryAccessWhere, ] export const CONTENT_LISTINGS: Readonly> = Object.fromEntries( diff --git a/apps/docs/data/content-listings/telemetry.data.ts b/apps/docs/data/content-listings/telemetry.data.ts index 1133f603123..0ada46af8a7 100644 --- a/apps/docs/data/content-listings/telemetry.data.ts +++ b/apps/docs/data/content-listings/telemetry.data.ts @@ -73,3 +73,68 @@ export const telemetryMonitoring: ContentListingGroup = { }, ], } + +export const telemetryAccessWhat: ContentListingGroup = { + id: 'telemetry-access-what', + heading: 'What data you can observe', + headingLevel: 'h3', + type: 'grid', + columns: 2, + items: [ + { + title: 'Logs', + href: '/guides/monitoring-and-debugging/advanced-log-filtering', + description: + 'Query project logs and look up sources and fields. Record extra Postgres, API, and Realtime events.', + }, + { + title: 'Metrics API', + href: '/guides/monitoring-and-debugging/metrics', + description: 'Scrape Prometheus-compatible database metrics for dashboards and alerting.', + }, + { + title: 'Database', + href: '/guides/monitoring-and-debugging/inspect', + description: + 'Inspect live Postgres stats such as bloat, cache hit rate, locks, and slow queries.', + }, + { + title: 'Advisors', + href: '/guides/monitoring-and-debugging/advisors', + description: + 'Pull deterministic security and performance findings as part of ongoing observability.', + }, + ], +} + +export const telemetryAccessWhere: ContentListingGroup = { + id: 'telemetry-access-where', + heading: 'Where you can observe it', + headingLevel: 'h3', + type: 'grid', + columns: 2, + items: [ + { + title: 'MCP', + href: '/guides/monitoring-and-debugging/access-data#mcp', + description: + 'Query logs, run read-only SQL, and fetch advisor findings from an agent harness.', + }, + { + title: 'API', + href: '/guides/monitoring-and-debugging/access-data#api', + description: 'Read logs, advisors, and usage counts, or scrape the Metrics API.', + }, + { + title: 'CLI', + href: '/guides/monitoring-and-debugging/access-data#cli', + description: + 'Inspect the database and run security or performance advisors from the terminal.', + }, + { + title: 'Studio', + href: '/guides/monitoring-and-debugging/access-data#studio', + description: 'Open Logs, Reports, and Advisors in the browser.', + }, + ], +}