Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

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.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<Record<string, ContentListingGroup>> = 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.',
+ },
+ ],
+}