Skip to content

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

Add health advisor doc (#51144)

Steven Eubankb0597aa5fac3
diff --git a/apps/docs/components/DatabaseAdvisorsIndex.tsx b/apps/docs/components/DatabaseAdvisorsIndex.tsx
index 32c93df2aa6..ca383ca9951 100644
--- a/apps/docs/components/DatabaseAdvisorsIndex.tsx
+++ b/apps/docs/components/DatabaseAdvisorsIndex.tsx
@@ -1,5 +1,6 @@
import { readFile } from 'node:fs/promises'
import { join } from 'node:path'
+import { healthAdvisors } from '~/data/health-advisors.data'
import { MDXRemoteBase } from '~/features/docs/MdxBase'
import { TabPanel, Tabs } from '~/features/ui/Tabs'
import { GENERATED_DIRECTORY } from '~/lib/docs'
@@ -25,7 +26,7 @@ export async function DatabaseAdvisorsIndex() {
return (
<Tabs listClassNames="flex flex-wrap gap-2 [&>button]:m-0!" queryGroup="lint">
- {lints.map((lint) => (
+ {[...healthAdvisors, ...lints].map((lint) => (
<TabPanel key={lint.path} id={lint.path} label={capitalize(lint.path.replace(/_/g, ' '))}>
<section id={lint.path}>
<MDXRemoteBase source={lint.content} />
diff --git a/apps/docs/content/guides/observability/advisors.mdx b/apps/docs/content/guides/observability/advisors.mdx
index 16098634142..b0e1302bf45 100644
--- a/apps/docs/content/guides/observability/advisors.mdx
+++ b/apps/docs/content/guides/observability/advisors.mdx
@@ -1,21 +1,19 @@
---
id: 'advisors'
title: 'Advisors'
-description: 'Deterministic security and performance findings you or an agent can pull as part of ongoing observability.'
+description: 'Health, security, and performance checks you or an agent can run against a project.'
---
-Advisors are programmatic checks that ship with the platform. They inspect the live schema and return deterministic findings, such as missing indexes or incorrectly configured RLS policies.
+Advisors are deterministic checks that ship with the platform. They flag health, security, and performance issues in your project, such as elevated error rates, misconfigured RLS policies, or missing indexes.
-Confirm each finding against the intended schema and access model. Search [Troubleshooting](/docs/guides/troubleshooting) for its check name or affected object; logs can provide additional context but are not required to establish a schema finding.
+You or an agent can run them from:
-You or an agent can pull the same checks from:
-
-- Studio: [Security Advisor](/dashboard/project/_/advisors/security) and [Performance Advisor](/dashboard/project/_/advisors/performance)
+- Studio: [Health Advisor](/dashboard/project/_/advisors/health), [Security Advisor](/dashboard/project/_/advisors/security), and [Performance Advisor](/dashboard/project/_/advisors/performance)
- MCP: `get_advisors` with `type` set to `security` or `performance`
- 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)
+- Management API: [security](/docs/reference/api/v1-get-security-advisors), [performance](/docs/reference/api/v1-get-performance-advisors), and [health](/docs/reference/api/v2-run-project-advisors) advisors
-Prioritize warning and error findings. Each finding names a check, severity, affected object, and remediation guidance. Informational findings provide context and do not always require a change. The advisors run automatically in Studio. After an authorized fix, rerun the relevant advisor and confirm that the finding no longer appears.
+Some findings may be intentional, so check them against your intended schema and access model before you change anything. Health findings can take a while to clear after a fix, since the check measures error rates over a period of time.
## Available checks
diff --git a/apps/docs/data/health-advisors.data.ts b/apps/docs/data/health-advisors.data.ts
new file mode 100644
index 00000000000..7f5254eb35c
--- /dev/null
+++ b/apps/docs/data/health-advisors.data.ts
@@ -0,0 +1,55 @@
+/**
+ * Health advisors read service logs rather than the schema, so they aren't documented in
+ * splinter alongside the security and performance lints. `DatabaseAdvisorsIndex` prepends
+ * these, matching the order of the advisors in Studio.
+ */
+export const healthAdvisors = [
+ {
+ path: 'log_data_api_error_rate_high',
+ content: `**Summary:** Data API error rate is persistently high
+
+**Ramification:** Data API requests are returning 5xx errors, so reads and writes from your app may fail.
+
+***
+
+### How to Resolve
+
+Pull up to five recent 5xx responses on \`/rest/v1\` paths from \`edge_logs\` with their IDs, timestamps, and status. You can use [Logs](/dashboard/project/_/logs/edge-logs) in Studio, the MCP [\`query_logs\`](/docs/guides/observability/advanced-log-filtering#mcp) tool, or the [Management API](/docs/guides/observability/advanced-log-filtering#api). Then follow [API error troubleshooting](/docs/guides/troubleshooting/discovering-and-interpreting-api-errors-in-the-logs-7xREI9).`,
+ },
+ {
+ path: 'log_auth_error_rate_high',
+ content: `**Summary:** Auth error rate is persistently high
+
+**Ramification:** Users may be unable to sign in or refresh their session.
+
+***
+
+### How to Resolve
+
+Pull up to five recent errors from \`auth_logs\` with their IDs, timestamps, and status. You can use [Logs](/dashboard/project/_/logs/auth-logs) in Studio, the MCP [\`query_logs\`](/docs/guides/observability/advanced-log-filtering#mcp) tool, or the [Management API](/docs/guides/observability/advanced-log-filtering#api). Then use [Auth error codes](/docs/guides/auth/debugging/error-codes) to interpret them.`,
+ },
+ {
+ path: 'log_storage_error_rate_high',
+ content: `**Summary:** Storage error rate is persistently high
+
+**Ramification:** File uploads and downloads may fail.
+
+***
+
+### How to Resolve
+
+Pull up to five recent errors from \`storage_logs\` with their IDs, timestamps, and status. You can use [Logs](/dashboard/project/_/logs/storage-logs) in Studio, the MCP [\`query_logs\`](/docs/guides/observability/advanced-log-filtering#mcp) tool, or the [Management API](/docs/guides/observability/advanced-log-filtering#api). Then use [Storage error codes](/docs/guides/storage/debugging/error-codes) to interpret them.`,
+ },
+ {
+ path: 'log_edge_function_error_rate_high',
+ content: `**Summary:** Edge Function error rate is persistently high
+
+**Ramification:** Features that call your Edge Functions may fail.
+
+***
+
+### How to Resolve
+
+Pull up to five recent failed invocations from \`function_edge_logs\` with their IDs, timestamps, and status. You can use [Logs](/dashboard/project/_/logs/edge-functions-logs) in Studio, the MCP [\`query_logs\`](/docs/guides/observability/advanced-log-filtering#mcp) tool, or the [Management API](/docs/guides/observability/advanced-log-filtering#api). Then use [Edge Functions error codes](/docs/guides/functions/error-codes) to interpret them.`,
+ },
+]
diff --git a/apps/docs/internals/markdown-schema/DatabaseAdvisorsIndex.ts b/apps/docs/internals/markdown-schema/DatabaseAdvisorsIndex.ts
index 96e40c23a66..081f1a5ccfd 100644
--- a/apps/docs/internals/markdown-schema/DatabaseAdvisorsIndex.ts
+++ b/apps/docs/internals/markdown-schema/DatabaseAdvisorsIndex.ts
@@ -1,5 +1,6 @@
import { readFileSync } from 'node:fs'
import path from 'node:path'
+import { healthAdvisors } from '~/data/health-advisors.data'
const ADVISORS_PATH = path.join(process.cwd(), 'features/docs/generated/database-advisors.json')
@@ -11,7 +12,7 @@ interface Lint {
export const DatabaseAdvisorsIndex = (): string => {
const lints: Lint[] = JSON.parse(readFileSync(ADVISORS_PATH, 'utf-8'))
- return lints
+ return [...healthAdvisors, ...lints]
.map(
(lint) => `### ${lint.path}