docs(telemetry): add a Debugging guide and log-query best practices - #47762
Merged
Conversation
Documents the narrow-query discipline (filter by table, bound the timestamp, select only needed columns, widen along an anchor) and the Logs Explorer's BigQuery SQL restrictions (no subqueries, no *, no ILIKE, cross join unnest for nested fields). Complements the existing per-source Postgres and API log guides with the discipline that applies across every log source.
|
This pull request has been ignored for the connected project Preview Branches by Supabase. |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
6 Skipped Deployments
|
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository UI (base), Organization UI (inherited) Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
✅ Files skipped from review due to trivial changes (1)
📝 WalkthroughWalkthroughAdded a telemetry Debugging documentation page, linked it from navigation, expanded Logs Explorer guidance for targeted investigation and cross-source correlation, and allowed a documented Auth error token in the spelling rule. ChangesTelemetry debugging documentation
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
github-actions
Bot
added
the
documentation
The Logs Explorer now runs on ClickHouse (single logs table, source column, log_attributes map, logs.all.otel endpoint) rather than per-source BigQuery tables. Rewrite every query and the dialect section to match, per .claude/skills/clickhouse-logs-queries.
The telemetry/logs guide already documents querying the Logs Explorer and its best practices, so a separate troubleshooting page duplicated it. Drop the standalone page and add the three missing, engine-agnostic practices to the existing Best practices list: query one source at a time, follow a request across sources with an anchor, and reference only confirmed field names.
jordienr
changed the title
Add a front-door page for troubleshooting Supabase issues: the debugging loop, the parallel-services request stack, log-reading guidance, and a symptom-to-guide routing table that links into the existing troubleshooting collection. Register it in the Telemetry nav group right after Logging.
jordienr
changed the title
3 tasks
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
jordienr
marked this pull request as ready for review
July 10, 2026 10:20
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
apps/docs/content/guides/telemetry/debugging.mdx (1)
1-69: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winFix the Prettier check before merge.
The pipeline reports formatting issues in this file. Run the repository-configured Prettier formatter and commit the resulting changes.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@apps/docs/content/guides/telemetry/debugging.mdx` around lines 1 - 69, Run the repository-configured Prettier formatter on the debugging documentation file and commit the formatting-only changes, preserving the existing content and links.Source: Pipeline failures
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@apps/docs/content/guides/telemetry/debugging.mdx`:
- Line 39: In the API-to-database troubleshooting guidance, revise the “almost
always” claim to a qualified statement acknowledging other possible causes such
as filters, authentication, query shape, and schema-cache issues, while
preserving the existing layer-isolation workflow and recommendation to trace
toward the database.
In `@apps/docs/content/guides/telemetry/logs.mdx`:
- Around line 356-367: The logs guide still presents BigQuery-era guidance while
the current Logs Explorer uses ClickHouse. Update the surrounding
troubleshooting sections and all related examples, field references, and query
syntax to valid ClickHouse Logs Explorer conventions, or explicitly label the
material as legacy; ensure anchors and field semantics match the current engine
before publishing.
---
Outside diff comments:
In `@apps/docs/content/guides/telemetry/debugging.mdx`:
- Around line 1-69: Run the repository-configured Prettier formatter on the
debugging documentation file and commit the formatting-only changes, preserving
the existing content and links.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 509d58e0-0073-46bc-808a-a5dd47186b24
📒 Files selected for processing (3)
apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.tsapps/docs/content/guides/telemetry/debugging.mdxapps/docs/content/guides/telemetry/logs.mdx
jeremenichelli
left a comment
jeremenichelli
left a comment
Contributor
There was a problem hiding this comment.
This content is golden 👌 really really useful. good job!
Left some comments on phrasing and reading cadence.
Co-authored-by: Jeremias Menichelli <jmenichelli@gmail.com>
Co-authored-by: Jeremias Menichelli <jmenichelli@gmail.com>
Co-authored-by: Jeremias Menichelli <jmenichelli@gmail.com>
Co-authored-by: Jeremias Menichelli <jmenichelli@gmail.com>
Co-authored-by: Jeremias Menichelli <jmenichelli@gmail.com>
Co-authored-by: Jeremias Menichelli <jmenichelli@gmail.com>
Co-authored-by: Jeremias Menichelli <jmenichelli@gmail.com>
jeremenichelli
approved these changes
Jul 10, 2026
Contributor
Braintrust eval report
|
This was referenced Jul 15, 2026
6 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:
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
logstable,log_attributesmap), butguides/telemetry/logs.mdxand 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.mdxtroubleshooting/how-to-interpret-and-explore-the-postgres-logs-OuCIOj.mdxtroubleshooting/discovering-and-interpreting-api-errors-in-the-logs-7xREI9.mdxSummary by CodeRabbit
New Features
Documentation