## 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>
## Problem
Docs discarded every browser exception because its third-party
stack-frame filter never returned a value from its predicate. Errors
captured by the page error boundaries were discarded too.
## Fix
Use Studio's Sentry SDK tagging approach with a matching webpack
application key, retaining page-crashing exceptions even when their
frames are classified as third-party. Preserve consent and platform
checks, and pass the source-map upload token through Turbo.
## How to test
- Run `pnpm --filter docs run test:local:unwatch
lib/sentry-client.test.ts` with the documented local Supabase
prerequisites satisfied. Eleven filter regression checks passed locally
using an isolated Vitest configuration.
- On a production-mode preview with the docs DSN configured, accept
telemetry consent and trigger a temporary client render error. Verify
that the docs Sentry project receives it with `globalErrorBoundary:
true` and readable stack traces.
- Verify that third-party-only errors are filtered and declining consent
suppresses browser reports.
Prettier, focused filter/test TypeScript checks, and an in-memory
transport check using the real Sentry SDK passed. Full app typecheck and
lint are blocked locally by existing dependency/generated-file drift;
the standard docs suite requires unavailable Docker access. Live Sentry
ingestion and source-map uploads still need deployment verification.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **Bug Fixes**
- Improved error monitoring to distinguish documentation app boundary
crashes from other exceptions.
- Reduced noise in error reports by filtering third-party-only errors
and respecting platform and consent settings.
- Preserved reporting for first-party failures and critical application
crashes.
- **Chores**
- Improved Sentry build and deployment configuration for more consistent
error tracking.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
<!-- 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>
<!-- CURSOR_AGENT_PR_BODY_BEGIN -->
## 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`
<!-- 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>
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## 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.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
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>
In this PR:
- The `llms.ts` script is removed from the pipeline. It was just
iterating over the sections of the SDK JSON files to generate _dummy_
text files for LLMS to consume. But with a lot of inconsistencies and
mistakes.
- There's a new script that builds markdown files from the SDK
definition files.
- The Management API now has a definition file too, it was missing
before.
- On the www project now there are redirects for the reference text
files to the new markdown files in the docs project.
- NPM scripts have received better names so that prebuild ones are
smaller and all are easier to differentiate.
It's possible for individual PRs to pass typechecking, while the merge
result fails it. To prevent errors from getting into production, we can
fail the prod build if typecheck fails. Typecheck is still ignored on
preview builds for efficiency, since those are blocked on the GitHub
typecheck Action.
Scripts currently use CJS, which is causing a bit of a mess when trying
to use shared utilities from the app. Converting everything to ESM so
there are fewer conflicts when adding new scripts going forward.
* refactor(docs): turn auth error codes table into data file
Take the Markdown error codes table and turn it into a data file
instead. This makes it easy to parse and reuse in other places besides
Markdown documents.
* Update apps/docs/content/errorCodes/authErrorCodes.toml
Co-authored-by: Terry Sutton <saltcod@gmail.com>
---------
Co-authored-by: Terry Sutton <saltcod@gmail.com>
* Bump all versions of postcss to 8.5.3.
* Run next/codemod on the docs app.
* Move two experimental flags into stable. Add next-mdx-remote as a transpiled package.
* Add extra folders to the clean command in docs.
* Fix type errors in docs test.
* Run prettier on the new files.
* remove turbopack, fix fetch revalidation, fix metadata awaits
Couple of minor fixes:
- Turbopack doesn't work in dev because of known MDX loader limitations
(cannot load functions in MDX plugin config)
- Fetches not cached by default anymore in Next 15 so need to manually
cache the ones we need
- Missing a few awaits for metadata generation with page params
* Bump the graphiql version because headlessui/react is not building with Next 15.
---------
Co-authored-by: Charis Lam <26616127+charislam@users.noreply.github.com>
* Added hsts header via vercel.json
* Migrate headers to next.config.js
* only apply hsts headers when running on vercel
* remove is platform check from docs
* Moved hsts header to root path
* Removed debugging header
* revert environment check on www header
---------
Co-authored-by: Alaister Young <a@alaisteryoung.com>
The examples folder needs to be explicitly included in the Vercel Serverless bundle. Because it's at the root of the monorepo rather than being within the `app/docs` folder, we copy it over pre-build (and pre-dev).
Test the examples/prompts fix by re-enabling revalidations on graphql pages. Added a temp version of the fetch function so we can gradually reenable and monitor Vercel error rates over time.
* Add next to pnpm catalog and use that next version from all apps and packages.
* Remove vite direct dependency.
* Set the @types/node to version 20.
* Stabilize supports-color by adding it in the main package.json. This will make it appear in all packages that have it as optional.
* Use built-in matchers for vitest in @testing-library/jest-dom.
* Add libpg-query as a dependency to docs.
* Remove nextjs-node-loader for the built-in external packages feature on nextjs.
* Clean up extra comment.
Migrates client SDK References to App Router. (Management and CLI API references aren't migrated yet, nor are self-hosting config references.)
Some notes:
Big changes to the way crawler pages are built and individual section URLs (e.g., javascript/select) are served. All of these used to be SSG-generated pages, but the number of heavy pages was just too much to handle -- slow as molasses and my laptop sounded like it was taking off, and CI sometimes refuses to build it all at all.
Tried various tricks with caching and pre-generating data but no dice.
So I changed to only building one copy of each SDK+version page, then serving the sub-URLs through a response rewrite. That's for the actual user-visible pages.
For the bot pages, each sub-URL needs to be its own page, but prebuilding it doesn't work, and rendering on demand from React components is too slow (looking for super-fast response here for SEO). Instead I changed to using an API route that serves very minimal, hand-crafted HTML. It looks ugly, but it's purely for the search bots.
You can test what bots see by running curl --user-agent "Mozilla/5.0 (iPhone; CPU iPhone OS 6_0 like Mac OS X) AppleWebKit/536.26 (KHTML, like Gecko) Version/6.0 Mobile/10A5376e Safari/8536.25 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)" <URL_OF_PAGE>
Also added some smoke tests to run against prod for the crawler routes, since we don't keep an eye on those regularly, and Vercel config changes could surprise-break them. Tested the meta images on Open Graph and all seems to work fine.
With this approach, full production builds are really fast: ~5 minutes
Starts using the new type spec handling, which is better at finding params automatically, so I could remove some of the manually written ones from the spec files.
* move to shared types
* Rename the package to api-types.
* Fix a forgotten dependency.
* Add more forgotten deps.
---------
Co-authored-by: Ivan Vasilov <vasilov.ivan@gmail.com>
* feat: add new Icons package
* Create README.md
* add more icons
* add "Home" icon and "Postgres" icon
* reduce helpers
* remove old files
* make dev deps
* Delete package-lock.json
* Update README.md
* add to packages for other apps
* remove from db.design
* Update README.md
* Move the build-icons package in the packages folder.
---------
Co-authored-by: Ivan Vasilov <vasilov.ivan@gmail.com>
* Change all imports in the ui package which import via the @ui shortcut.
* Add a new ui-patterns package. Add it to all apps.
* Migrate PrivacySettings from ui to ui-patterns.
* Migrate ConsentToast from ui to ui-patterns.
* Remove providers folder from ui package.
* Move GlassPanel.
* Migrate IconPanel.
* Migrate TweetCard.
* Migrate ThemeImage.
* Remove LWXCountdownBanner.
* Migrate CountdownWidget.
* Migrate SchemaTableNode.
* Migrate ExpandableVideo.
* Migrate ThemeToggle.
* Fix bunch of imports in the docs app.
* Revert some unnecessary changes.
* Expand the README.md.
* Fix the tailwind configs, they were using old folder structure.
* Fix leftover merge conflicts.
* Remove a deleted page in master.
---------
Co-authored-by: Terry Sutton <saltcod@gmail.com>
* Add a new function to ai-commands package.
* Add a new API route to all three apps.
* Refactor the Command component to use the new URL.
* Resort the imports.
* update deps + image codemod (studio)
* update next links (studio)
* update deps
* update links (ui)
* remove next-transpile-modules
* move next-themes dependency
* chore: update ConfirmDialog
* chore: remove old ConfirmModal js file. migrated to TS
* dependency wrangling
* remove empty page
* update next links (www)
* First run bump react-data-grid-v7 beta 4
* fix package-lock.json
* more deps wrangling
* update recharts
* update sentry options
* fix some broken things in www
* studio fixes
* fix graphiql
* fix studio build
* fix menu hydration
* small build error
* update turbo
* fix www typescript errors
* docs image codemod
* links codemod docs
* fix docs typescript errors
* move useConsent to ui to prevent circular deps
* Fix links
* Fix homepage
* Fix links
* move studio/ to apps/
* Revert "move studio/ to apps/"
This reverts commit 1b0a985fcb.
* disable outputFileTracingRoot
* remove outputFileTracingRoot
* fix homepage product cards
* fix PrivacySettings links
* Fix links
* Fix the build for www.
* Minor fixes for JWTGenerator.
* Fix the docs and ui tests.
* Revert codehike back to 0.8.3
* remove ConfirmAlert()
* reenable babel because mobx hates me
* fix blog image and comparison page avatar
* Fix svg errors
* update image synthax
* Fix code hike
* Move the button in a div so that it doesn't inherit its parent height and make the button look weird.
* When components are defined in a component, they get recreated on each render. This makes them unstable in certain cases and causes infinite rerenders.
* Replace the next/head usage with next/script.
* Chore/upgrade next 13 fix table editor (#18431)
* fix table editor styling and fix row deletion logic
* Fix deleting selected rows from header, and fix checkboxes not clearing up
* Fix deleting all rows when filter applied, and fix deleting all rows
* Fix grid size styling issue
* Fix TS error
* Hydration errors
* studio org pages fixes
* fix more studio links
* audit logs fixes
* dropdown icon styling fixes
* fix some images in www
* upgrade to next 14
* try new sentry wrapper for api
* see if this is even invoked
* Revert "see if this is even invoked"
This reverts commit 86c3973ffa.
* Revert "try new sentry wrapper for api"
This reverts commit f67623ebad.
* Revert "upgrade to next 14"
This reverts commit a24dd6131e.
* chore: allow node version 19/20
* Try to fix the LogTable so that it renders with the newer "react-data-grid" version.
* Fix type errors in the log renderer code.
* Fix the replication screen.
* Add the CSS for the GraphiQL.
* Fix SQL editor results rendering
* Lint
* Fix SQL editor results height issue
* Fix auth RLS not invalidating RQ when toggling RLS
* Fix database tables new/edit column regressed
* Fix migrations page empty state if migrations schema not yet created
* Fix API side panel docs temp remove postgrest text for column description PK and FK
* Fix + improve timeout handling in SQL editor
---------
Co-authored-by: Jonathan Summers-Muir <MildTomato@users.noreply.github.com>
Co-authored-by: Joshen Lim <joshenlimek@gmail.com>
Co-authored-by: Francesco Sansalvadore <f.sansalvadore@gmail.com>
Co-authored-by: Terry Sutton <saltcod@gmail.com>
Co-authored-by: Ivan Vasilov <vasilov.ivan@gmail.com>
Co-authored-by: Kevin Grüneberg <k.grueneberg1994@gmail.com>
Danny White
