semi related to this PR: https://github.com/supabase/changelog/pull/234
Trying to ensure the information architecture links someone reading the
debugging docs to the correct info on SQL syntax required by CH. This is
a simple QOL change vs doing a larger IA fix
## 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
## What is the current behavior?
Does not direct users to CH sql syntax doc
## What is the new behavior?
Directs users to CH sql syntax doc
## Additional context
https://supabase.com/changelog/48235-migration-of-supabase-management-api-logs-all-analytics-endpoint-to-logs-endpoint
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Updated the MCP server description to link to Logs Explorer
documentation for the supported ClickHouse SQL syntax used when querying
logs.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## What
- Adds a **Debug with AI tools** section to the debugging guide,
covering the MCP debugging tools (`get_logs`, `query_logs`,
`get_advisors`, `execute_sql`), the Supabase agent skill, and the
combined plugin install, with a pointer to the MCP security best
practices.
- Adds a one-line pointer to it from the Monitoring and Debugging
overview.
- Adds the missing `query_logs` entry to the MCP server's Debugging tool
group.
Note: `pnpm lint:mdx` couldn't run locally (Node version), Prettier
passes.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Added guidance for debugging with AI tools, including MCP tools and
the Supabase agent skill for reading logs and advisors.
* Documented plugin installation and security considerations when
connecting AI agents through MCP.
* Added links from monitoring and debugging guidance to the new AI tools
documentation.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Miranda Limonczenko <miranda.limonczenko@supabase.io>
## Summary
- Renames the **Telemetry** nav section to **Monitoring and Debugging**
(nav label + sidebar title)
- Rewrites the section overview (`telemetry.mdx`) as a clean navigation
page using `ContentListings` — three panels (Debugging / Monitoring / AI
& automation) with no how-to prose
- Adds new `telemetry.data.ts` content-listings data file with three
groups registered in `index.ts`
- Adds a new **Debugging** guide (`debugging.mdx`) — request-stack
model, symptom-to-layer router with troubleshooting links for every
service, logging guidance
- Adds cross-links between `debugging.mdx`, `logs.mdx`, and
`advanced-log-filtering.mdx`
- Adds a new **AI agents and MCP** page (`ai-agents.mdx`) — MCP tools
table, `get_logs` usage, debugging skill workflow
- Restructures sidebar into three groups: **Debugging** / **Monitoring**
/ **AI & automation**
## Motivation
- No central entry point existed for debugging — content was scattered
across products with no index
- The overview page had almost no links for agents to follow
- The section name "Telemetry" caused confusion (also used for CLI usage
telemetry)
- Unblocks the `supabase` debugging skill, which routes agents to this
section as its source of truth
## Test plan
- [ ] `/docs/guides/telemetry` — three ContentListings panels render, no
prose how-to text
- [ ] `/docs/guides/telemetry.md` (markdown) — clean link list,
navigable by LLMs
- [ ] `/docs/guides/telemetry/debugging` — renders correctly, symptom
table links resolve
- [ ] `/docs/guides/telemetry/ai-agents` — new page renders correctly
- [ ] Sidebar shows 3 groups: Debugging / Monitoring / AI & automation
- [ ] All cross-links between debugging, logs, and
advanced-log-filtering resolve
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
## Summary
- **New Features**
- Added new documentation coverage for AI agent–assisted monitoring and
debugging, including an observability-driven troubleshooting workflow.
- **Documentation**
- Updated the “Telemetry” area to “Monitoring and Debugging” with a
refreshed landing page and reorganized sections (Debugging, Monitoring,
and AI).
- Revised the debugging and logs guides to improve step-by-step guidance
and highlight advanced log filtering.
- **Navigation**
- Renamed and restructured the top-level navigation entry to reflect the
new Monitoring and Debugging content layout.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: Jeremias Menichelli <jmenichelli@gmail.com>
Steven Eubank