## 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?
Documentation update.
## What is the current behavior?
The observability overview and access page overlap; configuration
interrupts querying; related guides send log queries to the old editor.
## What is the new behavior?
The observability overview and navigation follow the same four sections:
Read project data, Detect and diagnose, Hire an agent, and Configure and
export. The overview absorbs the redundant access page, with permanent
redirects for both HTML and Markdown URLs.
“Query logs with SQL” owns ClickHouse querying through MCP, the
Management API, and Explorer with query source Logs. Logging
configuration moves to its own guide; sources, captured headers, and
limits live in the field reference. Inspection links to canonical
diagnostic SQL. Related Storage and database guides use the replacement
Explorer workflow and retain existing anchors where headings move.
## Additional context
Validation: Markdown generation, docs typecheck, targeted ESLint,
formatting, and content-listing tests. Browser overview/navigation
checked; old HTML and Markdown URLs return 308, and the new
configuration page returns 200 in both formats. Three ClickHouse
examples and the Postgres configuration query ran in a disposable
container sandbox. Changed pages have no MDX lint violations;
repository-wide existing failures remain.
Self-review: the Management API request was verified against its
published schema but not sent to a hosted project. Realtime ingestion
and hosted logging configuration still need a hosted smoke check. No
compatibility path for the deprecated logs engine is documented.
Stage 2 of 3; depends on stage 1.
Stack: #50073 → #50074 → #50075.
Production docs build also passes at the stack tip after standard
reference generation.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **Documentation**
- Reorganized observability guidance around reading data, detecting
issues, diagnosing problems, agent setup, and exporting data.
- Added a guide for configuring Postgres and Realtime logging.
- Updated log investigation instructions to use Explorer, SQL queries,
and clearer filters.
- Added log source, field, and captured-header references.
- Improved advisor guidance and database performance troubleshooting.
- Added redirects for moved observability content.
- **Accessibility**
- Improved screen-reader labels for copy and feature-selection controls.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
<!-- CURSOR_AGENT_PR_BODY_BEGIN -->
## 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.
<!-- CURSOR_AGENT_PR_BODY_END -->
<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>
