mirror of
https://github.com/supabase/supabase.git
synced 2026-10-06 01:45:10 +03:00
ac7e66f215
Two related docs changes for debugging Supabase, consolidated into one PR. ## 1. New "Debugging" guide (`guides/telemetry/debugging`) A methodology and entry page for debugging any Supabase issue, added next to Logging in the Telemetry nav. It covers: - **The debugging loop** — read the exact error, isolate the failing layer, gather evidence, fix, verify. - **The Supabase request stack** — the gateway fans out to PostgREST, GoTrue, Storage, and Realtime as parallel services (not a chain), with Postgres underneath. Explains why an API-layer permission or empty-result error is usually a Postgres RLS/privilege issue. - **Reading logs** — the narrow-query discipline (one source, bounded window, widen along an anchor), linking the Logs Explorer guide rather than duplicating query syntax. - **Symptom to guide routing table** — maps each symptom to its layer and the specific troubleshooting guide, acting as a front door to the troubleshooting collection. All 47 links verified live. This puts the debugging methodology in docs (owned and updatable) instead of only in the agent skill. ## 2. Log-query best practices (`guides/telemetry/logs`) Adds the three practices the existing Best practices list was missing, all engine-agnostic: query one source at a time, follow a request across sources with an anchor, and reference only confirmed field names. ## Follow-up (not in this PR) The Logs Explorer now defaults to **ClickHouse** (single `logs` table, `log_attributes` map), but `guides/telemetry/logs.mdx` and the two logs troubleshooting guides still document the legacy **BigQuery** dialect (`cross join unnest(metadata)`). They need a coordinated BigQuery to ClickHouse migration pass: - `guides/telemetry/logs.mdx` - `troubleshooting/how-to-interpret-and-explore-the-postgres-logs-OuCIOj.mdx` - `troubleshooting/discovering-and-interpreting-api-errors-in-the-logs-7xREI9.mdx` <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Added a new “Debugging” guide with a step-by-step workflow for identifying where issues originate versus where they appear. * Added a symptom-to-layer troubleshooting mapping and linked it from Telemetry navigation. * **Documentation** * Updated Logs Explorer guidance to note its ClickHouse default and that examples use legacy BigQuery syntax. * Expanded Logs Explorer best practices, including querying one source at a time, correlating with anchors, and using only confirmed field names. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Jeremias Menichelli <jmenichelli@gmail.com>
Reference Docs
Supabase Reference Docs
Maintainers
If you are a maintainer of any tools in the Supabase ecosystem, you can use this site to provide documentation for the tools & libraries that you maintain.
DocSpec
We use documentation specifications which can be used to generate human-readable docs.
- OpenAPI: for documenting API endpoints.
- SDKSpec (custom to Supabase): for SDKs and client libraries.
- ConfigSpec (custom to Supabase): for configuration options.
- CLISpec (custom to Supabase): for CLI commands and usage.
The benefit of using custom specifications is that we can generate many other types from a strict schema (eg, HTML and manpages). It also means that we can switch to any documentation system we want. On this site we use Next.js, but on Supabase's official website, we use a custom React site and expose only a subset of the available API for each tool.
Contributing
To contribute to docs, see the developers' guide and contributing guide.