<!-- 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>
## Context
Allow self-host / local dashboard to access the "Observability" pages
Currently only Query Performance will be accessible - eventually once
Database Connections is publicly ready, it'll also be accessible here
too
<img width="518" height="312" alt="image"
src="https://github.com/user-attachments/assets/18e5f6c7-ca77-4e90-81ec-c303bd31dc33"
/>
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Navigation, sidebar, and mobile menus now consistently display
**Observability** and **Logs** based on enabled features, including the
unified logs preview.
* **Observability** destinations now adapt to platform and settings so
users land on the correct Query Performance view.
* **Bug Fixes**
* Improved Query Performance loading layout for a smoother loading
experience.
* Database selection is now shown only on supported platform
environments.
* **Tests**
* Updated navigation/menu tests to match the new routing behavior.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Follow-up to #48344: collapses the two resolution paths for the
Admonition module into one.
`src/admonition.tsx` was a back-compat shim re-exporting
`src/Admonition/`. Two ways to resolve one module is exactly what
produced the macOS self-import bug fixed in #48344, and the local
typecheck errors that #48374 worked around. This removes the shim and
standardizes on the PascalCase subpath, matching every other export in
the package.
**Changed:**
- Codemodded all 246 `ui-patterns/admonition` imports to
`ui-patterns/Admonition` (240 `.tsx`, 5 `.mdx`, 1 `.ts` across studio,
docs, www, design-system, and lite-studio)
- Pointed the 5 internal `'../admonition'` imports back at the
`'../Admonition'` directory
**Removed:**
- `packages/ui-patterns/src/admonition.tsx`, and its `./admonition`
entry in the exports map (regenerated with `pnpm gen:exports`)
## To test
- `grep -r "ui-patterns/admonition" --include='*.ts*'` → no hits
- `pnpm test:case-hazards` → passes
- `pnpm typecheck` → all 15 tasks green
- `pnpm --filter studio run lint:ratchet` → passes
- `pnpm --filter ui-patterns vitest run src/Admonition` → 11 tests pass
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Bug Fixes**
* Standardized Admonition component imports across the application and
documentation.
* Improved compatibility with case-sensitive environments by using the
canonical component path.
* Removed the legacy Admonition import entry point.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Alaister Young <10985857+alaister@users.noreply.github.com>
## 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?
Changes to the structure of the <Switch> and <Dialog> elements, which
previously resulted in two nested buttons in the DOM.
Adding the asChild attribute broke the styling of the <Switch>.
Added aria-label and tooltips to the <Switch> component and the
icon-only buttons.
<img width="1909" height="1254" alt="fix_observabilty"
src="https://github.com/user-attachments/assets/4dc99845-c083-455b-beed-1ac58b66dd6f"
/>
## What is the current behavior?
Icon-only buttond do not have explicit accessible names for screen
readers.
Two nested buttons are invalid in HTML and interfere with the operation
of screen readers.
## What is the new behavior?
Iicon-only buttons now have explicit accessible names using visually
hidden text (sr-only), ensuring proper screen reader support.
The DOM structure is now correct.
## Additional context
No visual changes were introduced.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
## Summary by CodeRabbit
* **Bug Fixes**
* Improved accessibility in the query performance filter bar by adding
clear `aria-label` values to the Refresh and Reset report buttons.
* Improved accessibility and usability for cron job table actions by
adding a job-specific “actions” tooltip/label for the dropdown trigger.
* Updated the cron job enable/disable toggle with job-specific
`aria-label`s and refined the confirmation dialog flow to prevent
unintended row interactions.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Problem
We now export components under a subpath in ui-patterns to avoid barrel
files as they slow down every tools (from IDE to linters, etc.) and may
also affect bundles our users have to download.
## Solution
- Remove the UI patterns index file
- Fix invalid impors
## Problem
Our `<Button>` component breaks the default `button` contract by
redefining the `type` prop to set its variant (`primary`, `default`,
etc) instead of the button type (`submit`, `button`, etc).
This is confusing and forces to write more code when using it with
shadcn components that expect/inject the standard button props.
## Solution
- rename the `type` prop to `variant`
- rename the `htmlType` prop to `type`
- propagate the changes where necessary
- format code
## How to test
As this is just prop renaming, if it builds it's ok
---------
Co-authored-by: Ivan Vasilov <vasilov.ivan@gmail.com>
## Context
Just some clean up as I was going through stuff
- `useExecuteSqlQuery` is deprecated and not used at all
- As such `execute-sql-query` is technically irrelevant, the more
relevant file is `execute-sql-mutation`
- Hence opting to consolidate `execute-sql-query` into
`execute-sql-mutation`
- Also removing `ExecuteSqlError` since its just re-exporting the
`ResponseError` type
There's a lot of file changes but its essentially just updating the
importing statements across the files
## Summary
Part 4 of the SafeSql migration stack
([#45897](https://github.com/supabase/supabase/pull/45897),
[#45903](https://github.com/supabase/supabase/pull/45903),
[#45990](https://github.com/supabase/supabase/pull/45990), this PR, …).
Converts the remaining reports, query performance, observability, index
advisor, and privileges call sites of `executeSql` to produce
`SafeSqlFragment` values. The `ReportQuery.sql` field flips from
`string` to `SafeSqlFragment`, which cascades into every consumer —
landed here atomically so each branch typechecks cleanly.
Touched areas:
- `interfaces/Reports/*` — `ReportQuery.sql: SafeSqlFragment`, plus all
report definitions/utilities updated
- `interfaces/QueryPerformance/useQueryPerformanceQuery.ts`
- `interfaces/Database/IndexAdvisor/*` and
`data/database/{table-index-advisor,retrieve-index-advisor-result}-query.ts`
-
`data/privileges/{table-api-access,update-exposed-entities}-mutation.ts`
- `interfaces/Storage/StoragePolicies/StoragePolicies.tsx`
- `hooks/analytics/useDbQuery.tsx`
- `Observability/useSlowQueriesCount.ts` +
`useQueryInsightsIssues.utils.test.ts`
## Test plan
- [x] `pnpm typecheck` passes
- [x] `useQueryInsightsIssues.utils.test.ts` passes
- [x] Dev-server smoke test: reports pages, query performance, index
advisor, storage policies
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Refactor**
* Reworked SQL construction and typings across reporting, query
performance, index advisor, and privilege features to use safer SQL
fragments, improving reliability and preventing query composition
issues.
* **Types**
* Reporting query types were split to distinguish database vs. logs
queries, enabling correct handling and validation.
* **Docs/Utils**
* Added a helper to consistently generate logs SQL for report hooks.
* **Tests**
* Updated tests to exercise the new SQL-building API.
<!-- review_stack_entry_start -->
[](https://app.coderabbit.ai/change-stack/supabase/supabase/pull/45998)
<!-- review_stack_entry_end -->
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Mark provenance of SQL via the branded types SafeSqlFragment and
UntrustedSqlFragment. Only SafeSqlFragment should be executed;
UntrustedSqlFragments require some kind of implicit user approval (show
on screen + user has to click something) before they are promoted to
SafeSqlFragment.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Editor and RLS tester show loading states for inferred/generated SQL
and include a dedicated user SQL editor for safer edits.
* **Refactor**
* Platform-wide SQL handling tightened: snippets and AI-generated SQL
are treated as untrusted/display-only until promoted, improving safety
and consistency.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
This PR migrates the whole monorepo to use Tailwind v4:
- Removed `@tailwindcss/container-queries` plugin since it's included by
default in v4,
- Bump all instances of Tailwind to v4. Made minimal changes to the
shared config to remove non-supported features (`alpha` mentions),
- Migrate all apps to be compatible with v4 configs,
- Fix the `typography.css` import in 3 apps,
- Add missing rules which were included by default in v3,
- Run `pnpm dlx @tailwindcss/upgrade` on all apps, which renames a lot
of classes
- Rename all misnamed classes according to
https://tailwindcss.com/docs/upgrade-guide#renamed-utilities in all
apps.
---------
Co-authored-by: Jordi Enric <jordi.err@gmail.com>
## Problem
On self-hosted Supabase instances where the `pg_stat_statements`
extension is not installed, the Observability Overview page
automatically queries the extension on every page load. This produces
"relation pg_stat_statements does not exist" errors in Postgres logs for
all projects without the extension. Additionally, if a user navigated to
the Query Performance page, they received a generic error with no
actionable guidance. A secondary issue allowed malformed sort URL params
(e.g. `?sort=created_at:asc&order=asc`) to be interpolated directly into
SQL ORDER BY clauses.
## Fix
- Wrapped the `useSlowQueriesCount` SQL in a `CASE WHEN EXISTS (SELECT 1
FROM pg_extension WHERE extname = 'pg_stat_statements')` guard. The
query now returns 0 silently instead of erroring when the extension is
absent.
- Added a `VALID_SORT_COLUMNS` whitelist in
`generateQueryPerformanceSql`. Invalid column names from URL params are
rejected and the query falls back to the preset default ORDER BY.
- When the Query Performance page fails because `pg_stat_statements`
does not exist, a `warning` admonition now appears with "Enable it in
Database -> Extensions" guidance instead of a generic destructive error.
The Sentry capture is skipped for this expected configuration state.
- Extracted `buildSlowQueriesCountSql` as a testable function and added
unit tests for both fixes.
## How to test
**Extension not installed (self-hosted):**
1. Run a self-hosted Supabase instance without the `pg_stat_statements`
extension enabled.
2. Navigate to the Observability Overview page.
3. Check Postgres logs -- no "relation pg_stat_statements does not
exist" errors should appear.
4. Navigate to the Query Performance page.
5. Expected: a yellow warning admonition appears saying the extension is
not enabled, with a link to Database -> Extensions. No red error.
**Extension installed (normal flow):**
1. With `pg_stat_statements` installed, navigate to Observability
Overview.
2. Expected: slow queries count loads as normal.
3. Navigate to Query Performance -- data loads as normal.
**Invalid sort URL param:**
1. Navigate to
`/project/<ref>/observability/query-performance?sort=created_at:asc&order=asc`.
2. Expected: the page loads and falls back to the default sort order
(total time descending). No SQL error in logs.
**Unit tests:**
```
node apps/studio/node_modules/vitest/dist/cli.js run --no-coverage \
apps/studio/components/interfaces/Observability/useSlowQueriesCount.test.ts \
apps/studio/components/interfaces/QueryPerformance/useQueryPerformanceQuery.test.ts
```
All 28 tests should pass.
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
## Problem
The Query Performance page loaded all results in a single query with a
fixed limit of 20 rows, giving users no way to browse beyond the first
page. There was also no way to control how many rows were shown at once.
## Fix
adds pagination
## How to test
- Navigate to `/observability/query-performance` in Studio
- scroll to bottom
- should automatically load more results
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
## Context
Adds a source filter for the query performance advisor so you can filter
out queries from the dashboard, or not from the dashboard
<img width="309" height="217" alt="image"
src="https://github.com/user-attachments/assets/c1fab9af-e57e-482f-afdb-d77a6600edb3"
/>
For transparency how this works:
- Queries fired via the dashboard through the /query endpoint get
enriched with metadata from the API to include a comment like `--
source: dashboard`
- That's mainly how this filter works atm, to check if this comment
exists if the source "Dashboard" is selected, and the inverse if the
source "Non dashboard" is selected
Add a Query Performance page implementation powered by
[supamonitor](https://github.com/supabase/supamonitor).
[Context](https://linear.app/supabase/project/build-extension-for-supabase-query-insights-df4fb145352c/overview)
This looks largely the same as the pg_stat_monitor implementation:
<img width="2556" height="960" alt="Screenshot 2026-02-12 at 7 35 47 PM"
src="https://github.com/user-attachments/assets/bf37466e-f7af-41f2-b4f2-cf8eb6a8c76f"
/>
Only available on projects on custom AMI - existing users are unaffected
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Supamonitor-based query performance view: charts, aggregated metrics,
date-range controls, and export/download.
* Added "Application" column for per-application tracking.
* Interactive Supamonitor grid: sorting, filtering, keyboard navigation,
selection, retry/error handling.
* Automatic per-project Supamonitor detection with toggleable UI
integration.
* **Bug Fixes**
* Chart latency calculation prefers histogram data for more accurate
p95.
* **Documentation**
* Minor blog formatting fix.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: kemal <hello@kemal.earth>
Co-authored-by: Ali Waseem <waseema393@gmail.com>
* feat: more generic observability banner on db report
* feat: try popup in corner
* feat: tidy up and fix up event as well
* feat: add event for dismiss as well
* feat: add supplementary link at bottom of reports
* fix: sizing of fonts
* feat: banner stack approach
* fix: isIndexAdvisorAvailable dep
* chore: remove unused import for old banner
* feat: remove unused isDismissed
* chore: remove unused cn
* chore: change prio on query perf page
* chore: remove unused sendEvent
* chore: better useEffect cleanup
* chore: remove unused index advisor notice
* fix: priority of banner stack
* fix: first time loader flickering
* chore: lowercase the word Free
* feat: add IS_PLATFORM to make sure metrics api banner is scoped to platform
* chore: another copy update for observability link
* fix: telemetry keys to match styleguide
* fix: use the correct way to apply events
* feat: add events for index advisor banner too
* chore: delete unused old banner
* fix: dismiss buttons not working
* feat: add extra event to enable index advisor
* feat: change the check to show index advisor tab at all times
* fix: hide add to log drains on export menu in query perf
* fix: small fallback for pathname check
* fix: query perf header block responsiveness
* feat: admonition for index advisor
* fix: add aria-describedby to query perf sheet
* feat: proper way to do sheet description
* chore: better title spacing in panel
* fix: indexes in use empty state
* fix: key in observability menu
* feat: better highlighting of index advisor issues
* feat: add docs button to empty indexes tab
* feat: remove unused code
* feat: use button tooltips for reset and refresh to gain space
* feat: add dismiss to index advisor banner
* feat: add warnings filter to query perf
* feat: filter all queries for warnings
* fix: selected state for warning rows
* fix: fallback for isLogs check
* fix: other instance of download button
---------
Co-authored-by: Ali Waseem <waseema393@gmail.com>
* feat: setup chart area and tabs
This sets up the area where we can expect the insights chart as well as the tabs mechanism.
* feat: parse pg_stat_monitor logs as json
* feat: create query perf chart utils and move transfrom function
Created a utils file for our QueryPerformanceChart component. This moves the logs to JSON transform function there.
* feat: add timerange to chart
* feat: add date selector to query perf overview
This adds the selector to the top right of the page allowing the user to switch between last hour, 3 hours and 24 hours
* feat: modify chart component to accomodate hiding bits
* feat: add metrics to each tab
* chore: update to 60 min by default and some css
* feat: centralise data parsing for logs
* feat: clean up filters bar
This rewires the export to give you the aggregate pg_stat_monitor data. Also removes unused buttons and filters.
* feat: percentiles for query latency chart
* feat: filter out non evenets from pg_stat_monitor logs
* feat: utils for cache misses and hits
* feat: add selected query to chart on click
* feat: add click through to query panel
* chore: tidy up files
* chore: distinction between selected and open panel
* feat: move query performance fully into reports area
* fix: preserve query params on reports link
* fix: remove right icon syntax in report menu
* chore: remove cache misses from cache chart
* refactor: backwards compatibility for statements if right db version isnt available
* chore: delete randomly generated empty file
* chore: tidy up unused imports and vars
* chore: remove console logs
* chore: remove isMounted from query perf
* fix: cmd k query perf path
* feat: simplify query latency only p50 and p95
This seems to give us a more accurate reading as we can calculate these two
* fix: cache hit rate not showing inside query details
* chore: chart bg colour adjust
So it contrasts a little better on light mode.
* feat: show selected query on other verticals
* feat: bring back symlink in advisors
