docs: add reusable monitoring agent setup components by SaxonF · Pull Request #49506 · supabase/supabase

SaxonF · 2026-08-24T23:54:48Z

Stack

Draft stack extracted from docs/monitoring. Merge bottom-up. Troubleshooting / debugging-guide rewrite is out of scope.

docs: move inspect and advisors into observability #49503 move inspect and advisors
docs: split Studio logs from ClickHouse log queries #49501 split Studio logs from ClickHouse queries
docs: treat reports as signal dashboards, not fix lists #49500 treat reports as signal dashboards
docs: add Observe the data hub for logs, metrics, and advisors #49502 add Observe the data hub
docs: add reusable monitoring agent setup components #49506 add agent setup components ← this PR
docs: add hire-an-agent templates for observability routines #49504 add hire-an-agent templates
docs: restructure observability navigation and overview #49505 restructure observability nav and overview

I have read the CONTRIBUTING.md file.

YES

What kind of change does this PR introduce?

Docs app feature (MDX components + markdown export). Fifth layer in the observability stack.

What is the current behavior?

There is no shared way to render a monitoring agent prompt, schedule, and Claude/Codex/Cursor setup instructions in both HTML and generated markdown.

What is the new behavior?

AgentSetup and AgentWatchSchedule MDX components, registered for HTML and markdown export
Shared monitoring-agents data (cadence, prompt ids, harness steps)
Opt-in AiPrompt markdown export (includeInMarkdown) so quickstarts stay HTML-only
Optional content-listing subtitle for schedule labels on cards

No agent guide pages yet — those land in #49504 so this PR stays a reviewable code change.

Additional context

Markdown schema handlers share the same data module as the React components.

vercel · 2026-08-24T23:54:56Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
design-system	Ready	Preview	Sep 4, 2026 2:27am UTC
docs	Ready	Preview, v0	Sep 4, 2026 2:27am UTC
kb	Ready	Preview	Sep 4, 2026 2:27am UTC
studio-self-hosted	Ready	Preview	Sep 4, 2026 2:27am UTC
studio-staging	Ready	Preview	Sep 4, 2026 2:27am UTC
ui-library	Ready	Preview	Sep 4, 2026 2:27am UTC
zone-www-dot-com	Ready	Preview, v0	Sep 4, 2026 2:27am UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
studio	Ignored		Sep 4, 2026 2:27am UTC

coderabbitai · 2026-08-24T23:54:56Z

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Team

Run ID: b5973c2e-d220-44ea-9cc8-d4dd85c1a297

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

supabase · 2026-08-24T23:56:38Z

This pull request has been ignored for the connected project xguihxuzqibwxjnimxev because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

nrichers

Content changes LGTM but I think a docs engineer should take a look at the infra changes: @czenko @jeremenichelli. Note the nit about the markdown handler.

Verdict: Approve with nits

Check	Result
Build / lint	`pnpm build:guides-markdown` unchanged as expected; `npx vitest run` → 41/41 tests pass
CI	All checks pass; local `tsc --noEmit` shows only pre-existing unrelated errors

Verified:

AgentSetup, AgentWatchSchedule, AiPrompt handlers share the same data source as their React components, registered in SCHEMA, and each has dedicated test coverage
No existing MDX broken by the new opt-in markdown behavior

Notes (nits):

AgentSetup markdown handler drops a harness "docs" link the React component renders
Persona-name casing inconsistency (sentence case vs. title case) between data and prompt text — cosmetic
New prompts link forward to pages that don't exist yet in this PR — resolved by #49504 next in stack (expected, not a defect)

smeubank

the general tooling made available here, i support. I am curious about the actual agent personas for the other PR more

nrichers

LGTM.

Introduce AgentSetup, AgentWatchSchedule, and opt-in AiPrompt markdown export so later agent guides can share prompts, schedules, and harness instructions. Co-authored-by: Saxon Fletcher <SaxonF@users.noreply.github.com>

## Stack Draft stack extracted from `docs/monitoring`. Merge bottom-up. Troubleshooting / debugging-guide rewrite is out of scope. 1. **#49503** move inspect and advisors ← **this PR** 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 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. First layer in the observability stack. ## What is the current behavior? Inspect and advisors live under Database (`/guides/database/inspect`, `/guides/database/database-advisors`). Observability readers have to leave the monitoring section to find them. ## What is the new behavior? - Moves inspect into `/guides/monitoring-and-debugging/inspect` - Adds `/guides/monitoring-and-debugging/advisors` (replaces the Database Advisors page) - Adds redirects and updates Studio/docs links so old URLs keep working - Adds both pages to the existing Monitoring nav so they are discoverable before the later IA PR ## Additional context Inspect and advisors pages render as standard MDX. Redirects cover `/docs/guides/database/inspect`, `/docs/guides/database/database-advisors`, and `/docs/guides/database/database-linter`. Debugging-guide content is unchanged except the inspect URL. ## Self-review - No leftover `/guides/database/inspect` or `/guides/database/database-advisors` links in docs guides or Studio linter/AI surfaces (historical blog posts left as-is) - Smoke test path updated to `/docs/guides/monitoring-and-debugging/advisors`  <div><a href="https://cursor.com/agents/bc-a3cb5ece-925b-4046-b58a-5d69e9a9d794?cursor_ref=pr_footer&cursor_cta=open_in_web"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-web-light.png"><img alt="Open in Web" width="114" height="28" src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a> <a href="https://cursor.com/background-agent?bcId=bc-a3cb5ece-925b-4046-b58a-5d69e9a9d794&cursor_ref=pr_footer&cursor_cta=open_in_cursor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img alt="Open in Cursor" width="131" height="28" src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a> </div>  ## Summary by CodeRabbit - **New Features** - Added a centralized Advisors guide for security and performance checks. - Updated database inspection guidance with live Postgres statistics, cache hit-rate context, and query-analysis resources. - **Documentation** - Reorganized Advisors and database inspection content under Monitoring and Debugging. - Updated navigation, cross-references, in-product help links, and CLI documentation links. - Added permanent redirects from previous documentation URLs to preserve access.  --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: Saxon Fletcher <SaxonF@users.noreply.github.com> Co-authored-by: Nik Richers <nik@validmind.ai>

## 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 ← **this PR** 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 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. Second layer in the observability stack. ## What is the current behavior? `/guides/monitoring-and-debugging/logs` mixes the Studio Logs UI with ClickHouse query syntax, sources, and recording extra events. ## What is the new behavior? - Logs is the Studio interface guide (filters, log types, inspecting a row) - Query and filter logs (`advanced-log-filtering`) owns ClickHouse SQL, sources, MCP/API/CLI access, and recording extra Postgres/API/Realtime events - Log field reference explains `log_attributes` query paths - Nav labels and cross-links follow the new titles ## Additional context Forward links to the later Observe the data hub are added in #49502. ## Self-review - Existing `#querying-with-the-logs-explorer` and `#configuring-pgauditlog` anchors now live on Query and filter logs - Debugging-guide links that pointed at the old Logs Explorer heading were retargeted so they still resolve  <div><a href="https://cursor.com/agents/bc-a3cb5ece-925b-4046-b58a-5d69e9a9d794?cursor_ref=pr_footer&cursor_cta=open_in_web"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-web-light.png"><img alt="Open in Web" width="114" height="28" src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a> <a href="https://cursor.com/background-agent?bcId=bc-a3cb5ece-925b-4046-b58a-5d69e9a9d794&cursor_ref=pr_footer&cursor_cta=open_in_cursor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img alt="Open in Cursor" width="131" height="28" src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a> </div> --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: Saxon Fletcher <SaxonF@users.noreply.github.com> Co-authored-by: Nik Richers <nik@validmind.ai>

## 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.  <div><a href="https://cursor.com/agents/bc-a3cb5ece-925b-4046-b58a-5d69e9a9d794?cursor_ref=pr_footer&cursor_cta=open_in_web"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-web-light.png"><img alt="Open in Web" width="114" height="28" src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a> <a href="https://cursor.com/background-agent?bcId=bc-a3cb5ece-925b-4046-b58a-5d69e9a9d794&cursor_ref=pr_footer&cursor_cta=open_in_cursor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img alt="Open in Cursor" width="131" height="28" src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a> </div> --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: Saxon Fletcher <SaxonF@users.noreply.github.com>

## 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.  <div><a href="https://cursor.com/agents/bc-a3cb5ece-925b-4046-b58a-5d69e9a9d794?cursor_ref=pr_footer&cursor_cta=open_in_web"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-web-light.png"><img alt="Open in Web" width="114" height="28" src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a> <a href="https://cursor.com/background-agent?bcId=bc-a3cb5ece-925b-4046-b58a-5d69e9a9d794&cursor_ref=pr_footer&cursor_cta=open_in_cursor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img alt="Open in Cursor" width="131" height="28" src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a> </div> --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: Saxon Fletcher <SaxonF@users.noreply.github.com> Co-authored-by: Steven Eubank <eubank.steven88@gmail.com>

## Stack Draft stack extracted from `docs/monitoring`. Merge bottom-up. The troubleshooting *catalog* rewrite (`content/troubleshooting` and the Diagnosing UI) stays 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 7. **#49505** restructure observability nav, overview, Detecting, and flatten Observe the data ← **this PR** ## 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. Top layer in the observability stack. ## What is the current behavior? The section is still titled Monitoring and Debugging, with a Debugging / Monitoring split that does not match the new pages. The debugging guide is still the master layer-isolation + symptom table. Observe the data is split into “what data” vs “where to observe it,” which duplicates the source pages. ## What is the new behavior? - Section title is Observability - Overview groups Observe the data, Detect and resolve, Hire an agent, and Export - **Observe the data is flattened by source.** Logs, Metrics API, Database, Advisors, and Reports each list where to read that source. There is no separate MCP/API/CLI/Studio nav group. - **Observe vs Detecting:** Observe is the catalog (what exists, how to access it). Detecting is how to *use* those sources to pick up a Health / Security / Performance / Usage signal. Named errors skip to Diagnosing. - Studio Logs sits under Logs. Reports sits beside the other sources. - Troubleshooting stays in the global menu and also appears as Diagnosing under Detect and resolve ## Additional context This is the last PR in the stack. Together the seven PRs reconstruct the `docs/monitoring` observability IA and guide content, without shipping the troubleshooting catalog overhaul.  <div><a href="https://cursor.com/agents/bc-a3cb5ece-925b-4046-b58a-5d69e9a9d794?cursor_ref=pr_footer&cursor_cta=open_in_web"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-web-light.png"><img alt="Open in Web" width="114" height="28" src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a> <a href="https://cursor.com/background-agent?bcId=bc-a3cb5ece-925b-4046-b58a-5d69e9a9d794&cursor_ref=pr_footer&cursor_cta=open_in_cursor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img alt="Open in Cursor" width="131" height="28" src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a> </div> --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: Saxon Fletcher <SaxonF@users.noreply.github.com> Co-authored-by: Nik Richers <nik@validmind.ai>

github-actions Bot added the documentation Improvements or additions to documentation label Aug 24, 2026

cursor Bot force-pushed the docs/observability-agent-infra branch from bbe610b to bcb187e Compare August 24, 2026 23:57

SaxonF mentioned this pull request Aug 25, 2026

Do not merge: link observability docs GitHub stack #49509

Closed

nrichers reviewed Aug 28, 2026

View reviewed changes

nrichers marked this pull request as ready for review August 28, 2026 01:37

nrichers requested a review from a team as a code owner August 28, 2026 01:37

smeubank approved these changes Aug 31, 2026

View reviewed changes

SaxonF requested a review from a team as a code owner September 1, 2026 02:29

SaxonF force-pushed the docs/observability-agent-infra branch from bcb187e to 5a5c0c7 Compare September 1, 2026 02:29

vercel Bot temporarily deployed to Preview – kb September 1, 2026 02:29 Inactive

SaxonF force-pushed the docs/observability-agent-infra branch from 5a5c0c7 to 4c6a75d Compare September 1, 2026 04:38

vercel Bot temporarily deployed to Preview – kb September 1, 2026 04:38 Inactive

SaxonF force-pushed the docs/observability-agent-infra branch from 4c6a75d to 010a1d6 Compare September 1, 2026 05:19

vercel Bot temporarily deployed to Preview – kb September 1, 2026 05:19 Inactive

vercel Bot temporarily deployed to Preview – kb September 1, 2026 05:33 Inactive

nrichers approved these changes Sep 3, 2026

View reviewed changes

docs: add reusable monitoring agent setup components

97520ed

Introduce AgentSetup, AgentWatchSchedule, and opt-in AiPrompt markdown export so later agent guides can share prompts, schedules, and harness instructions. Co-authored-by: Saxon Fletcher <SaxonF@users.noreply.github.com>

SaxonF added 2 commits September 4, 2026 12:10

docs: clarify monitoring agent roles

c81e93d

docs: run health monitor hourly

8b52824

SaxonF force-pushed the docs/observability-agent-infra branch from 488fb9f to 8b52824 Compare September 4, 2026 02:16

vercel Bot deployed to Preview – kb September 4, 2026 02:17 View deployment

SaxonF merged commit 36d2982 into master Sep 4, 2026
43 of 63 checks passed

SaxonF deleted the docs/observability-agent-infra branch September 4, 2026 03:38

Navigation Menu

Uh oh!

Uh oh!

docs: add reusable monitoring agent setup components - #49506

docs: add reusable monitoring agent setup components#49506
SaxonF merged 3 commits into
docs/observability-access-datafrom
docs/observability-agent-infra

SaxonF commented Aug 24, 2026 •

edited by cursor Bot

Loading

Uh oh!

vercel Bot commented Aug 24, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Aug 24, 2026 •

edited

Loading

Review skipped

Uh oh!

supabase Bot commented Aug 24, 2026

Uh oh!

nrichers left a comment

Uh oh!

smeubank left a comment

Uh oh!

nrichers left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Uh oh!

Conversation

SaxonF commented Aug 24, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Stack

I have read the CONTRIBUTING.md file.

What kind of change does this PR introduce?

What is the current behavior?

What is the new behavior?

Additional context

Uh oh!

vercel Bot commented Aug 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Aug 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

supabase Bot commented Aug 24, 2026

Uh oh!

nrichers left a comment

Choose a reason for hiding this comment

Uh oh!

smeubank left a comment

Choose a reason for hiding this comment

Uh oh!

nrichers left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

SaxonF commented Aug 24, 2026 •

edited by cursor Bot

Loading

vercel Bot commented Aug 24, 2026 •

edited

Loading

coderabbitai Bot commented Aug 24, 2026 •

edited

Loading