The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
docs: add Observe the data hub for logs, metrics, and advisors (#49502)
Saxon Fletcher4c716df063d2
diff --git a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.tsindex 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.mdxnew file mode 100644index 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.mdxindex 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.mdxindex 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 CLIdiff --git a/apps/docs/data/content-listings/index.ts b/apps/docs/data/content-listings/index.tsindex 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<Record<string, ContentListingGroup>> = Object.fromEntries(diff --git a/apps/docs/data/content-listings/telemetry.data.ts b/apps/docs/data/content-listings/telemetry.data.tsindex 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.',+ },+ ],+}