mirror of
https://github.com/supabase/supabase.git
synced 2026-10-05 17:35: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>