From 6f2effd9e22369ccc71e89f4775fcf58f5571494 Mon Sep 17 00:00:00 2001 From: Saxon Fletcher Date: Fri, 4 Sep 2026 13:38:38 +1000 Subject: [PATCH] docs: add hire-an-agent templates for observability routines (#49504) 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 5. #49506 add agent setup components 6. **#49504** add hire-an-agent templates ← **this PR** 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. Sixth layer in the observability stack. ## What is the current behavior? Humans and agents have no packaged, copy-paste observability routines to run in their own harness. ## What is the new behavior? - Hire an agent hub plus Doctor, Security officer, Personal trainer, and Accountant - Each page is a prompt + schedule + harness setup (Claude, Codex, Cursor) - MCP security guidance covers unattended read-only monitoring on production ## Additional context These pages are the agent-facing templates from the prototype. #49505 puts them in the Observability overview and sidebar.
Open in Web Open in Cursor 
--------- Co-authored-by: Cursor Agent Co-authored-by: Saxon Fletcher Co-authored-by: Steven Eubank --- .../NavigationMenu.constants.ts | 26 ++++ .../_partials/monitoring_agent_output.mdx | 5 + apps/docs/content/guides/ai-tools/mcp.mdx | 12 +- .../automate-with-agents.mdx | 38 ++++++ .../automate-with-agents/all.mdx | 40 ++++++ .../automate-with-agents/health.mdx | 37 ++++++ .../automate-with-agents/performance.mdx | 37 ++++++ .../automate-with-agents/security.mdx | 37 ++++++ .../automate-with-agents/usage.mdx | 37 ++++++ apps/docs/data/ai-prompts.data.ts | 125 ++++++++++++++++++ apps/docs/data/content-listings/index.ts | 2 + .../data/content-listings/telemetry.data.ts | 41 ++++++ apps/docs/data/monitoring-agents.data.ts | 12 ++ apps/docs/lib/content-listings.test.ts | 4 +- 14 files changed, 446 insertions(+), 7 deletions(-) create mode 100644 apps/docs/content/_partials/monitoring_agent_output.mdx create mode 100644 apps/docs/content/guides/monitoring-and-debugging/automate-with-agents.mdx create mode 100644 apps/docs/content/guides/monitoring-and-debugging/automate-with-agents/all.mdx create mode 100644 apps/docs/content/guides/monitoring-and-debugging/automate-with-agents/health.mdx create mode 100644 apps/docs/content/guides/monitoring-and-debugging/automate-with-agents/performance.mdx create mode 100644 apps/docs/content/guides/monitoring-and-debugging/automate-with-agents/security.mdx create mode 100644 apps/docs/content/guides/monitoring-and-debugging/automate-with-agents/usage.mdx diff --git a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts index 87826a30826..17ccf6d605b 100644 --- a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts +++ b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts @@ -3111,6 +3111,32 @@ export const telemetry: NavMenuConstant = { }, ], }, + { + name: 'Hire an agent', + url: '/guides/monitoring-and-debugging/automate-with-agents' as `/${string}`, + items: [ + { + name: 'Generalist', + url: '/guides/monitoring-and-debugging/automate-with-agents/all' as `/${string}`, + }, + { + name: 'Health monitor', + url: '/guides/monitoring-and-debugging/automate-with-agents/health' as `/${string}`, + }, + { + name: 'Security monitor', + url: '/guides/monitoring-and-debugging/automate-with-agents/security' as `/${string}`, + }, + { + name: 'Performance monitor', + url: '/guides/monitoring-and-debugging/automate-with-agents/performance' as `/${string}`, + }, + { + name: 'Capacity monitor', + url: '/guides/monitoring-and-debugging/automate-with-agents/usage' as `/${string}`, + }, + ], + }, ], } diff --git a/apps/docs/content/_partials/monitoring_agent_output.mdx b/apps/docs/content/_partials/monitoring_agent_output.mdx new file mode 100644 index 00000000000..28e72db7400 --- /dev/null +++ b/apps/docs/content/_partials/monitoring_agent_output.mdx @@ -0,0 +1,5 @@ +When the agent finds an issue, it reports in the harness. Send that report wherever you already triage work. Use the connections your harness already has. For example, Codex can open a Linear issue. + +Keep the Supabase project read-only. Filing a ticket is work in the harness, not a change to the project. + +If you want that routing on every scheduled run, add it to the prompt. diff --git a/apps/docs/content/guides/ai-tools/mcp.mdx b/apps/docs/content/guides/ai-tools/mcp.mdx index 87f18999fb1..15c7dd7c030 100644 --- a/apps/docs/content/guides/ai-tools/mcp.mdx +++ b/apps/docs/content/guides/ai-tools/mcp.mdx @@ -135,7 +135,7 @@ There are some situations where you might want to manually authenticate the MCP To authenticate the MCP server in a CI environment, you can create a personal access token (PAT) with the necessary scopes and pass it as a header to the MCP server. -1. Remember to never connect the MCP server to production data. Supabase MCP is only designed for development and testing purposes. See [Security risks](#security-risks). +1. Production projects can contain sensitive data. Before connecting one, scope the server to that project, enable [read-only mode](#configuration-options), restrict the available feature groups, and review the [security risks](#security-risks). 1. Navigate to your Supabase [access tokens](/dashboard/account/tokens) and generate a new token. Name the token based on its purpose, e.g. "Example App MCP CI token". @@ -151,7 +151,7 @@ To authenticate the MCP server in a CI environment, you can create a personal ac If your MCP client requires an OAuth client ID and secret (e.g. Azure API Center), you can manually create an OAuth app in your Supabase account and pass the credentials to the MCP client. -1. Remember to never connect the MCP server to production data. Supabase MCP is only designed for development and testing purposes. See [Security risks](#security-risks). +1. Production projects can contain sensitive data. Before connecting one, scope the server to that project, enable [read-only mode](#configuration-options), restrict the available feature groups, and review the [security risks](#security-risks). 1. Navigate to your Supabase organization's [OAuth apps](/dashboard/org/_/apps) and add a new application. Name the app based on its purpose, e.g. "Example App MCP". @@ -176,7 +176,9 @@ The primary attack vector unique to LLMs is prompt injection, which might trick -Most MCP clients like Cursor ask you to manually accept each tool call before they run. We recommend you always keep this setting enabled and always review the details of the tool calls before executing them. +Most MCP clients ask you to accept each tool call before it runs. Keep manual approval enabled for interactive work, and review each tool call before you run it. + +An unattended monitoring routine cannot request approval during each run. Approve in advance only the project-scoped, read-only tools that the routine needs. The routine must stop and report a recommendation instead of running a write operation. To lower this risk further, Supabase MCP wraps SQL results with additional instructions to discourage LLMs from following instructions or commands that might be present in the data. This is not foolproof though, so you should always review the output before proceeding with further actions. @@ -186,9 +188,9 @@ To lower this risk further, Supabase MCP wraps SQL results with additional instr We recommend the following best practices to mitigate security risks when using the Supabase MCP server: -- **Don't connect to production**: Use the MCP server with a development project, not production. LLMs are great at helping design and test applications, so leverage them in a safe environment without exposing real data. Be sure that your development environment contains non-production data (or obfuscated data). +- **Protect production data**: Connect to a production project only when the task requires production evidence. Use project scoping, read-only mode, restricted feature groups, and the narrowest data query that can answer the question. Do not include secrets or unrelated personal data in prompts or reports. - **Don't give to your customers**: The MCP server operates under the context of your developer permissions, so you should not give it to your customers or end users. Instead, use it internally as a developer tool to help you build and test your applications. -- **Read-only mode**: If you must connect to real data, set the server to [read-only](#configuration-options) mode, which executes all queries as a read-only Postgres user. +- **Read-only mode**: Set unattended monitoring and diagnostic routines to [read-only](#configuration-options) mode, which executes SQL queries as a read-only Postgres user. - **Project scoping**: Scope your MCP server to a [specific project](#configuration-options), limiting access to only that project's resources. This prevents LLMs from accessing data from other projects in your Supabase account. - **Branching**: Use Supabase's [branching feature](/docs/guides/deployment/branching) to create a development branch for your database. This allows you to test changes in a safe environment before merging them to production. - **Feature groups**: Restrict which [tool groups](#available-tools) are available using the `features` [configuration option](#configuration-options). This helps reduce the attack surface and limits the actions that LLMs can perform to only those that you need. diff --git a/apps/docs/content/guides/monitoring-and-debugging/automate-with-agents.mdx b/apps/docs/content/guides/monitoring-and-debugging/automate-with-agents.mdx new file mode 100644 index 00000000000..b12b1941afd --- /dev/null +++ b/apps/docs/content/guides/monitoring-and-debugging/automate-with-agents.mdx @@ -0,0 +1,38 @@ +--- +id: 'automate-with-agents' +title: 'Hire an agent' +subtitle: 'Run a read-only monitoring routine in your own agent harness.' +description: 'Choose and set up a Health, Security, Performance, or Capacity monitor in Claude, Codex, or Cursor.' +--- + +This guide explains how to run a Supabase monitoring agent in your own harness. Each agent is a prompt plus a schedule. It reads project data and reports findings. It does not change the project. + +## Choose a routine + +Start with one monitor. Add another only when the project needs a different source or cadence. + +| Monitor | What it watches | Default cadence | Use it when | +| --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | --------------- | -------------------------------------------------------------- | +| [Health monitor](/docs/guides/monitoring-and-debugging/automate-with-agents/health) | API and Auth server errors, error-rate spikes, connection pressure | Hourly | You need incident detection and regular feedback loops | +| [Security monitor](/docs/guides/monitoring-and-debugging/automate-with-agents/security) | Security Advisor findings, authentication and authorization failures | Daily | You need a regular access-control and configuration review | +| [Performance monitor](/docs/guides/monitoring-and-debugging/automate-with-agents/performance) | Slow queries, lock waits, long-running sessions, Performance Advisor findings | Hourly | You need query and database performance checks | +| [Capacity monitor](/docs/guides/monitoring-and-debugging/automate-with-agents/usage) | Request, error, storage, table, and connection growth | Daily | You need to identify growth before it reaches a resource limit | + +For a small project, run the most relevant routine daily or weekly and include the other categories in its prompt. Split it into specialized monitors only when you need different owners, schedules, or alert thresholds. + +## Run the routine + +1. Connect the [Supabase MCP server](/docs/guides/ai-tools/mcp) with `project_ref` and `read_only=true`. +2. Open the monitor that matches the job from the table above. +3. Set it up in Claude, Codex, Cursor, or copy the prompt into another harness. +4. Run it on demand first. Then put the same prompt on a schedule. + +Each agent page describes what it will output. Send those findings through the connections your harness already has, such as Linear in Codex. + +Scheduled tasks start a fresh context on every run, so the prompt is self-contained. Review the first runs before you rely on the schedule. + + + +Logs and query results can contain secrets or personal information. Keep the agent read-only, aggregate evidence, and redact sensitive values. + + diff --git a/apps/docs/content/guides/monitoring-and-debugging/automate-with-agents/all.mdx b/apps/docs/content/guides/monitoring-and-debugging/automate-with-agents/all.mdx new file mode 100644 index 00000000000..cca409477ee --- /dev/null +++ b/apps/docs/content/guides/monitoring-and-debugging/automate-with-agents/all.mdx @@ -0,0 +1,40 @@ +--- +id: 'automate-with-agents-all' +title: 'Generalist' +subtitle: 'Generalist is a read-only daily agent. It runs all four checks — health, security, performance, and usage — and reports only findings that need attention.' +description: 'A once-daily agent that checks all signal sources and reports across health, security, performance, and usage.' +--- + +```mermaid +flowchart TD + Schedule([Once per day]) --> Health[query_logs: health] + Schedule --> Security[get_advisors: security] + Schedule --> Performance[get_advisors + pg_stat_activity] + Schedule --> Usage[execute_sql: sizes and growth] + Health & Security & Performance & Usage --> Filter{Anything to report?} + Filter -->|Yes| Report[Daily summary] + Filter -->|No| Silent[Stay silent] +``` + +## What it watches + +- **Health** — API 5xx, Auth failures, error-rate spikes in the last 24 hours +- **Security** — Security Advisor findings, authorization failure spikes +- **Performance** — slow queries, lock waits, Performance Advisor findings +- **Usage** — database size, connection counts, API request growth, approaching limits + +It uses `query_logs`, `get_advisors`, and read-only `execute_sql` on project-scoped [Supabase MCP](/docs/guides/ai-tools/mcp). It does not change the project. + +## When it watches + + + +## What it will output + +Generalist reports only checks that turn up a finding. If health is clear, that section is omitted. If all checks are clear, the agent stays silent. When it does report, each section follows the same format as the specialist agent: a grouped finding, a likely cause, and a next step for a person to act on. + +<$Partial path="monitoring_agent_output.mdx" /> + +## Set up the agent + + diff --git a/apps/docs/content/guides/monitoring-and-debugging/automate-with-agents/health.mdx b/apps/docs/content/guides/monitoring-and-debugging/automate-with-agents/health.mdx new file mode 100644 index 00000000000..caf743d941c --- /dev/null +++ b/apps/docs/content/guides/monitoring-and-debugging/automate-with-agents/health.mdx @@ -0,0 +1,37 @@ +--- +id: 'automate-with-agents-health' +title: 'Health monitor' +subtitle: 'Health monitor is a read-only agent. It polls logs on a short interval, clusters errors, and reports only when a threshold is crossed.' +description: 'An on-call triage agent that watches logs for 5xx spikes, Auth failures, and availability issues.' +--- + +```mermaid +flowchart TD + Schedule([Every hour]) --> Inspect[query_logs] + Inspect --> Signals["5xx, Auth failures, error-rate spikes"] + Signals --> Threshold{Threshold crossed?} + Threshold -->|Yes| Report[Incident report] + Threshold -->|No| Silent[Stay silent] +``` + +## What it watches + +- API and Auth responses with status `>= 500` +- Error-rate spikes against a recent baseline +- Connection pressure when database inspection is available + +It uses `query_logs` on project-scoped, read-only [Supabase MCP](/docs/guides/ai-tools/mcp). It can use `get_advisors` for extra context. It does not change the project. + +## When it watches + + + +## What it will output + +When a threshold is crossed, Health monitor reports an incident: grouped errors, a few request IDs, a likely cause, and a troubleshooting link. If nothing crosses the threshold, it stays silent. + +<$Partial path="monitoring_agent_output.mdx" /> + +## Set up the agent + + diff --git a/apps/docs/content/guides/monitoring-and-debugging/automate-with-agents/performance.mdx b/apps/docs/content/guides/monitoring-and-debugging/automate-with-agents/performance.mdx new file mode 100644 index 00000000000..333f77abb07 --- /dev/null +++ b/apps/docs/content/guides/monitoring-and-debugging/automate-with-agents/performance.mdx @@ -0,0 +1,37 @@ +--- +id: 'automate-with-agents-performance' +title: 'Performance monitor' +subtitle: 'Performance monitor is a read-only agent. It inspects query statistics, blocking sessions, and Performance Advisor findings, then proposes the next change for a person to apply.' +description: 'A query health agent that looks for slow queries, lock waits, and performance advisor findings.' +--- + +```mermaid +flowchart TD + Schedule([Once per hour]) --> Inspect[get_advisors and execute_sql] + Inspect --> Signals["Slow queries, lock waits, advisor findings"] + Signals --> Review{Needs a change?} + Review -->|Yes| Report[Finding and verification plan] + Review -->|No| Silent[Stay silent] +``` + +## What it watches + +- Slow or regressing queries +- Lock waits and long-running sessions +- Unindexed foreign keys and other Performance Advisor findings + +It uses `get_advisors` and read-only `execute_sql` on project-scoped [Supabase MCP](/docs/guides/ai-tools/mcp). It does not create indexes, rewrite queries, or cancel sessions. + +## When it watches + + + +## What it will output + +Performance monitor reports slow or regressing queries, lock waits, and Performance Advisor findings, with a verification plan. It can recommend that a person cancel a session. It does not cancel the session or create indexes. + +<$Partial path="monitoring_agent_output.mdx" /> + +## Set up the agent + + diff --git a/apps/docs/content/guides/monitoring-and-debugging/automate-with-agents/security.mdx b/apps/docs/content/guides/monitoring-and-debugging/automate-with-agents/security.mdx new file mode 100644 index 00000000000..8ff0ae96aa6 --- /dev/null +++ b/apps/docs/content/guides/monitoring-and-debugging/automate-with-agents/security.mdx @@ -0,0 +1,37 @@ +--- +id: 'automate-with-agents-security' +title: 'Security monitor' +subtitle: 'Security monitor is a read-only agent. It reviews Security Advisor findings and bounded authentication or authorization failure counts, then proposes changes for a person to apply.' +description: 'A security review agent that reports advisor findings and authentication or authorization spikes.' +--- + +```mermaid +flowchart TD + Schedule([Once per day]) --> Inspect[get_advisors and query_logs] + Inspect --> Signals[Advisor warnings and auth failures] + Signals --> Review{Needs review?} + Review -->|Yes| Report[Findings and proposed fix] + Review -->|No| Silent[Stay silent] +``` + +## What it watches + +- Security Advisor findings at warning and error level +- Authentication and authorization failure spikes +- RLS or privilege issues that advisors already name + +It uses `get_advisors` and `query_logs` on project-scoped, read-only [Supabase MCP](/docs/guides/ai-tools/mcp). It does not change policies, grants, API keys, or Auth settings. + +## When it watches + + + +## What it will output + +Security monitor reports warning and error advisor findings, grouped authentication or authorization failures, and the least invasive fix for a person to apply. If nothing needs review, it stays silent. + +<$Partial path="monitoring_agent_output.mdx" /> + +## Set up the agent + + diff --git a/apps/docs/content/guides/monitoring-and-debugging/automate-with-agents/usage.mdx b/apps/docs/content/guides/monitoring-and-debugging/automate-with-agents/usage.mdx new file mode 100644 index 00000000000..5889a000b65 --- /dev/null +++ b/apps/docs/content/guides/monitoring-and-debugging/automate-with-agents/usage.mdx @@ -0,0 +1,37 @@ +--- +id: 'automate-with-agents-usage' +title: 'Capacity monitor' +subtitle: 'Capacity monitor is a read-only agent. It trends API request volume and error rates, then warns before traffic or errors look like a capacity problem.' +description: 'A capacity agent that tracks API request growth, error rates, and approaching resource ceilings.' +--- + +```mermaid +flowchart TD + Schedule([Once each morning]) --> Inspect[query_logs and usage APIs] + Inspect --> Signals["Request growth, error rates, resource trends"] + Signals --> Limit{Likely to hit a limit?} + Limit -->|Yes| Report["Trend, projected date, scaling guide"] + Limit -->|No| Silent[Stay silent] +``` + +## What it watches + +- API request growth against a recent baseline +- Server-error rate increases +- Disk, connection, or table growth when database inspection is available + +It uses `query_logs` on project-scoped, read-only [Supabase MCP](/docs/guides/ai-tools/mcp) and the [Management API usage endpoints](/docs/reference/api/v1-get-project-usage-api-count) when those are already authorized. It does not change billing, compute, or plan settings. MCP does not expose organization billing totals. + +## When it watches + + + +## What it will output + +Capacity monitor reports request growth, error-rate changes, and resource trends. If a metric looks likely to hit a limit within 14 days, it flags the date and the relevant scaling guide. + +<$Partial path="monitoring_agent_output.mdx" /> + +## Set up the agent + + diff --git a/apps/docs/data/ai-prompts.data.ts b/apps/docs/data/ai-prompts.data.ts index accbe0ddf44..d6707390673 100644 --- a/apps/docs/data/ai-prompts.data.ts +++ b/apps/docs/data/ai-prompts.data.ts @@ -328,6 +328,131 @@ Do not change billing, compute, or plan settings. REFERENCE https://supabase.com/docs/guides/monitoring-and-debugging/automate-with-agents/usage.md`, + 'monitoring-agent-all': `You are "Generalist", a daily read-only agent for a Supabase project. + +TOOLS AVAILABLE +- query_logs: query ClickHouse logs (edge_logs, auth_logs, postgres_logs, + function_edge_logs, function_logs, storage_logs, realtime_logs, supavisor_logs) +- get_advisors: pull Splinter lint findings (security and performance categories) +- execute_sql: run read-only SQL against the live Postgres database +If you are running inside Claude Code with the Supabase plugin or skills installed, +those provide the same tools plus richer context from the local project. + +Reach the project only through Supabase MCP with read_only=true. +Run once per day. Work through all four checks in order. + +HEALTH +1. Call query_logs with this SQL to count errors across all log sources in 1-hour + buckets over the last 24 hours: + + SELECT toStartOfHour(timestamp) AS hour, + source, + count() AS events + FROM logs + WHERE timestamp >= now() - interval 24 hour + AND ( + (source = 'edge_logs' + AND toInt32OrZero(log_attributes['response.status_code']) >= 500) + OR (source = 'postgres_logs' + AND log_attributes['parsed.error_severity'] IN ('ERROR', 'FATAL')) + OR (source = 'auth_logs' + AND event_message ILIKE '%failed%') + ) + GROUP BY hour, source + ORDER BY hour DESC, events DESC + + Declare an incident for any source/hour bucket with more than 20 events. + For each incident, collect up to 5 example event_messages to identify the cause. + +SECURITY +2. Call get_advisors with type=security. Collect ALL findings (error, warn, info). + For each finding, include the documentation link from the MCP response if one + is provided. +3. Call query_logs for authorization and authentication failures in the last + 24 hours. Group by status code or error code, not by user, email, or IP. + Report a spike only when the count is at least twice the recent baseline + and at least 20 events. Do not change policies, grants, or keys. + +PERFORMANCE +4. Call get_advisors with type=performance. Collect ALL findings (error, warn, info). + For each finding, include the documentation link from the MCP response if one + is provided. +5. Call execute_sql to find long-running or blocking sessions: + SELECT pid, usename, state, now()-query_start AS duration, wait_event_type, + left(query,120) AS query FROM pg_stat_activity + WHERE state IN ('active','idle in transaction') + AND now()-query_start > interval '30 seconds' + AND pid <> pg_backend_pid() ORDER BY duration DESC LIMIT 10; +6. Call execute_sql for cache hit rate. Flag any table below 0.99: + SELECT relname, heap_blks_hit::float/(heap_blks_hit+heap_blks_read+1) AS hit_rate + FROM pg_statio_user_tables ORDER BY hit_rate ASC LIMIT 10; + +USAGE +7. Call execute_sql for database size, top 10 table sizes, and connection counts + by role. Compare to the 7-day trend if earlier results are in context. +8. Call query_logs to count edge_logs requests by path for the last 24 hours. + Compare to the prior 24-hour window if available. + Flag if growth looks likely to hit a limit within 14 days. + +OUTPUT FORMAT +Produce a markdown report. Group advisor findings by severity (error, warn, info). +Omit a section entirely if its checks found nothing to act on. +If all checks are clear, output only: "All clear." + +--- + +## Daily report + +### Health +**[source] — [hour]** · [N] errors +Cause: [one sentence from example event_messages] +Fix: +\`\`\`sql +-- investigation or remediation query +\`\`\` + +### Security +**[finding title]** · [severity] +Docs: [link from MCP response, if provided] +Fix: +\`\`\`sql +-- remediation SQL +\`\`\` + +**[status/error code] spike** · [N] events (baseline: [N]) +Fix: [one sentence — e.g. check this RLS policy, rotate this key] + +### Performance +**[advisor finding title]** · [severity] +Docs: [link from MCP response, if provided] +Fix: +\`\`\`sql +-- remediation SQL +\`\`\` + +**Session [pid]** · [duration] · [state] · role: [usename] +Query: \`[excerpt]\` +Fix — confirm it is safe to cancel, then run in SQL editor: +\`\`\`sql +SELECT pg_cancel_backend([pid]); +\`\`\` + +**Cache hit rate: [table]** · [hit_rate] +Fix: [one sentence — e.g. investigate sequential scans on this table] + +### Usage +**[metric]**: [current] · 7-day trend: [direction] +[If limit risk:] Projected to reach limit by [date]. +See: https://supabase.com/docs/guides/platform/compute-and-disk + +--- + +Do not suggest new features, schema changes unrelated to a detected issue, +or improvements beyond fixing what you found. Only report detected problems +and the specific SQL, CLI command, or Studio step to fix each one. + +REFERENCE +https://supabase.com/docs/guides/monitoring-and-debugging/automate-with-agents/all.md`, } as const export type AiPromptId = keyof typeof aiPrompts diff --git a/apps/docs/data/content-listings/index.ts b/apps/docs/data/content-listings/index.ts index f7b357f9c6e..e16bc5717a3 100644 --- a/apps/docs/data/content-listings/index.ts +++ b/apps/docs/data/content-listings/index.ts @@ -31,6 +31,7 @@ import { telemetryAccessWhat, telemetryAccessWhere, telemetryDebugging, + telemetryHireAgent, telemetryMonitoring, } from './telemetry.data' @@ -70,6 +71,7 @@ const ALL_GROUPS: readonly ContentListingGroup[] = [ telemetryMonitoring, telemetryAccessWhat, telemetryAccessWhere, + telemetryHireAgent, ] 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 0ada46af8a7..54b6cc1ccf1 100644 --- a/apps/docs/data/content-listings/telemetry.data.ts +++ b/apps/docs/data/content-listings/telemetry.data.ts @@ -1,3 +1,5 @@ +import { monitoringAgents } from '~/data/monitoring-agents.data' +import { getScheduleLabel } from '~/data/monitoring-agents.utils' import type { ContentListingGroup } from '~/lib/content-listings.schema' export const telemetryDebugging: ContentListingGroup = { @@ -138,3 +140,42 @@ export const telemetryAccessWhere: ContentListingGroup = { }, ], } + +export const telemetryHireAgent: ContentListingGroup = { + id: 'telemetry-hire-agent', + type: 'grid', + columns: 2, + items: [ + { + title: 'Generalist', + href: '/guides/monitoring-and-debugging/automate-with-agents/all', + subtitle: getScheduleLabel(monitoringAgents.all), + description: + 'Run all four checks — health, security, performance, and usage — in one daily pass.', + }, + { + title: monitoringAgents.health.name, + href: '/guides/monitoring-and-debugging/automate-with-agents/health', + subtitle: getScheduleLabel(monitoringAgents.health), + description: 'Watch logs for 5xx spikes and Auth failures.', + }, + { + title: monitoringAgents.security.name, + href: '/guides/monitoring-and-debugging/automate-with-agents/security', + subtitle: getScheduleLabel(monitoringAgents.security), + description: 'Review advisor findings and authorization failures.', + }, + { + title: monitoringAgents.performance.name, + href: '/guides/monitoring-and-debugging/automate-with-agents/performance', + subtitle: getScheduleLabel(monitoringAgents.performance), + description: 'Find slow queries, lock waits, and missing indexes.', + }, + { + title: monitoringAgents.usage.name, + href: '/guides/monitoring-and-debugging/automate-with-agents/usage', + subtitle: getScheduleLabel(monitoringAgents.usage), + description: 'Track request growth, error rates, and approaching limits.', + }, + ], +} diff --git a/apps/docs/data/monitoring-agents.data.ts b/apps/docs/data/monitoring-agents.data.ts index 3f1f4d4a4cf..ca7a6d2b84c 100644 --- a/apps/docs/data/monitoring-agents.data.ts +++ b/apps/docs/data/monitoring-agents.data.ts @@ -46,6 +46,18 @@ export const monitoringAgents = { onDemand: 'Run it on demand after an unexpected traffic change.', }, }, + all: { + id: 'all', + name: 'Generalist', + promptId: 'monitoring-agent-all' as AiPromptId, + schedule: { + cadence: 'once per day', + intervalMinutes: 1440, + scheduled: 'Run it once per day at the start of your day or shift.', + onDemand: + 'Run it on demand after a deployment or whenever you want a full project health check.', + }, + }, } as const export type MonitoringAgentId = keyof typeof monitoringAgents diff --git a/apps/docs/lib/content-listings.test.ts b/apps/docs/lib/content-listings.test.ts index dd2788a5989..8de6892441a 100644 --- a/apps/docs/lib/content-listings.test.ts +++ b/apps/docs/lib/content-listings.test.ts @@ -68,7 +68,7 @@ describe('serializeContentListingGroupToMarkdown', () => { id: 'hire-agent', items: [ { - title: 'Doctor', + title: 'Health monitor', href: '/guides/monitoring-and-debugging/automate-with-agents/health', subtitle: 'Every 15 minutes', description: 'Watch logs for 5xx spikes and Auth failures.', @@ -79,7 +79,7 @@ describe('serializeContentListingGroupToMarkdown', () => { ) expect(markdown).toContain( - '**[Doctor](https://supabase.com/docs/guides/monitoring-and-debugging/automate-with-agents/health):** Every 15 minutes. Watch logs for 5xx spikes and Auth failures.' + '**[Health monitor](https://supabase.com/docs/guides/monitoring-and-debugging/automate-with-agents/health):** Every 15 minutes. Watch logs for 5xx spikes and Auth failures.' ) })