docs(telemetry): rename section and restructure as Monitoring and Debugging (#48243)

## Summary

- Renames the **Telemetry** nav section to **Monitoring and Debugging**
(nav label + sidebar title)
- Rewrites the section overview (`telemetry.mdx`) as a clean navigation
page using `ContentListings` — three panels (Debugging / Monitoring / AI
& automation) with no how-to prose
- Adds new `telemetry.data.ts` content-listings data file with three
groups registered in `index.ts`
- Adds a new **Debugging** guide (`debugging.mdx`) — request-stack
model, symptom-to-layer router with troubleshooting links for every
service, logging guidance
- Adds cross-links between `debugging.mdx`, `logs.mdx`, and
`advanced-log-filtering.mdx`
- Adds a new **AI agents and MCP** page (`ai-agents.mdx`) — MCP tools
table, `get_logs` usage, debugging skill workflow
- Restructures sidebar into three groups: **Debugging** / **Monitoring**
/ **AI & automation**

## Motivation

- No central entry point existed for debugging — content was scattered
across products with no index
- The overview page had almost no links for agents to follow
- The section name "Telemetry" caused confusion (also used for CLI usage
telemetry)
- Unblocks the `supabase` debugging skill, which routes agents to this
section as its source of truth

## Test plan

- [ ] `/docs/guides/telemetry` — three ContentListings panels render, no
prose how-to text
- [ ] `/docs/guides/telemetry.md` (markdown) — clean link list,
navigable by LLMs
- [ ] `/docs/guides/telemetry/debugging` — renders correctly, symptom
table links resolve
- [ ] `/docs/guides/telemetry/ai-agents` — new page renders correctly
- [ ] Sidebar shows 3 groups: Debugging / Monitoring / AI & automation
- [ ] All cross-links between debugging, logs, and
advanced-log-filtering resolve


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

## Summary

- **New Features**
- Added new documentation coverage for AI agent–assisted monitoring and
debugging, including an observability-driven troubleshooting workflow.

- **Documentation**
- Updated the “Telemetry” area to “Monitoring and Debugging” with a
refreshed landing page and reorganized sections (Debugging, Monitoring,
and AI).
- Revised the debugging and logs guides to improve step-by-step guidance
and highlight advanced log filtering.

- **Navigation**
- Renamed and restructured the top-level navigation entry to reflect the
new Monitoring and Debugging content layout.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: Jeremias Menichelli <jmenichelli@gmail.com>

apps/docs/app/guides/monitoring-and-debugging/[[...slug]]/page.tsx

@@ -11,15 +11,17 @@ type Params = { slug?: string[] }
 
 const MonitoringTroubleshootingGuidePage = async (props: { params: Promise<Params> }) => {
   const params = await props.params
-  const slug = ['telemetry', ...(params.slug ?? [])]
+  const slug = ['monitoring-and-debugging', ...(params.slug ?? [])]
   const data = await getGuidesMarkdown(slug)
 
   return <GuideTemplate {...data!} />
 }
 
-const generateStaticParams = !IS_DEV ? genGuidesStaticParams('telemetry') : getEmptyArray
+const generateStaticParams = !IS_DEV
+  ? genGuidesStaticParams('monitoring-and-debugging')
+  : getEmptyArray
 const generateMetadata = genGuideMeta((params: { slug?: string[] }) =>
-  getGuidesMarkdown(['telemetry', ...(params.slug ?? [])])
+  getGuidesMarkdown(['monitoring-and-debugging', ...(params.slug ?? [])])
 )
 
 export default MonitoringTroubleshootingGuidePage

apps/docs/app/guides/monitoring-and-debugging/layout.tsx

@@ -0,0 +1,5 @@
+import Layout from '~/layouts/guides'
+
+export default async function MonitoringAndDebugging({ children }: { children: React.ReactNode }) {
+  return <Layout>{children}</Layout>
+}

apps/docs/app/guides/telemetry/layout.tsx

@@ -1,5 +0,0 @@
-import Layout from '~/layouts/guides'
-
-export default async function Telemetry({ children }: { children: React.ReactNode }) {
-  return <Layout>{children}</Layout>
-}

apps/docs/components/MetricsStackCards.data.ts

@@ -13,7 +13,7 @@ export const metricsStackOptions: MetricsStackOption[] = [
     title: 'Grafana Cloud (SaaS)',
     description:
       'Use Grafana Cloud’s managed Prometheus (works on Free + Pro tiers) and import the Supabase dashboard without running any infrastructure.',
-    href: '/guides/telemetry/metrics/grafana-cloud',
+    href: '/guides/monitoring-and-debugging/metrics/grafana-cloud',
     iconKind: 'grafana',
     iconColor: '#F05A28',
     iconBg: 'rgba(240,90,40,0.1)',
@@ -23,7 +23,7 @@ export const metricsStackOptions: MetricsStackOption[] = [
     title: 'Grafana + self-hosted Prometheus',
     description:
       'Run Prometheus yourself following the official installation guidance and pair it with Grafana plus our dashboard JSON and alert pack.',
-    href: '/guides/telemetry/metrics/grafana-self-hosted',
+    href: '/guides/monitoring-and-debugging/metrics/grafana-self-hosted',
     iconKind: 'grafana',
     iconColor: '#F05A28',
     iconBg: 'rgba(240,90,40,0.1)',
@@ -43,7 +43,7 @@ export const metricsStackOptions: MetricsStackOption[] = [
     title: 'Vendor-agnostic / BYO Prometheus',
     description:
       'Connect AWS AMP, Grafana Mimir, VictoriaMetrics, or any Prometheus-compatible SaaS with the same scrape job pattern.',
-    href: '/guides/telemetry/metrics/vendor-agnostic',
+    href: '/guides/monitoring-and-debugging/metrics/vendor-agnostic',
     iconKind: 'flame',
     iconColor: '#0BA678',
     iconBg: 'rgba(11,166,120,0.1)',

apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts

@@ -212,9 +212,9 @@ export const GLOBAL_MENU_ITEMS: GlobalMenuItems = [
             level: 'security',
           },
           {
-            label: 'Telemetry',
+            label: 'Monitoring and Debugging',
             icon: 'telemetry',
-            href: '/guides/telemetry' as `/${string}`,
+            href: '/guides/monitoring-and-debugging' as `/${string}`,
             level: 'telemetry',
           },
           {
@@ -2983,57 +2983,59 @@ export const platform: NavMenuConstant = {
 
 export const telemetry: NavMenuConstant = {
   icon: 'telemetry',
-  title: 'Telemetry',
-  url: '/guides/telemetry',
+  title: 'Monitoring and Debugging',
+  url: '/guides/monitoring-and-debugging',
   items: [
-    { name: 'Overview', url: '/guides/telemetry' },
+    { name: 'Overview', url: '/guides/monitoring-and-debugging' },
     {
-      name: 'Logging & observability',
+      name: 'Debugging',
       url: undefined,
       items: [
         {
-          name: 'Logging',
-          url: '/guides/telemetry/logs' as `/${string}`,
+          name: 'Debugging guide',
+          url: '/guides/monitoring-and-debugging/debugging' as `/${string}`,
         },
         {
-          name: 'Debugging',
-          url: '/guides/telemetry/debugging' as `/${string}`,
+          name: 'Logging',
+          url: '/guides/monitoring-and-debugging/logs' as `/${string}`,
         },
         {
           name: 'Advanced log filtering',
-          url: '/guides/telemetry/advanced-log-filtering' as `/${string}`,
+          url: '/guides/monitoring-and-debugging/advanced-log-filtering' as `/${string}`,
         },
         {
           name: 'Logs field reference',
-          url: '/guides/telemetry/log-field-reference' as `/${string}`,
+          url: '/guides/monitoring-and-debugging/log-field-reference' as `/${string}`,
         },
+      ],
+    },
+    {
+      name: 'Monitoring',
+      url: undefined,
+      items: [
         {
           name: 'Log drains',
-          url: '/guides/telemetry/log-drains' as `/${string}`,
-        },
-        {
-          name: 'Tracing with the JS SDK',
-          url: '/guides/telemetry/client-side-tracing' as `/${string}`,
+          url: '/guides/monitoring-and-debugging/log-drains' as `/${string}`,
         },
         {
           name: 'Reports',
-          url: '/guides/telemetry/reports' as `/${string}`,
+          url: '/guides/monitoring-and-debugging/reports' as `/${string}`,
         },
         {
           name: 'Metrics',
-          url: '/guides/telemetry/metrics' as `/${string}`,
+          url: '/guides/monitoring-and-debugging/metrics' as `/${string}`,
           items: [
             {
               name: 'Overview',
-              url: '/guides/telemetry/metrics' as `/${string}`,
+              url: '/guides/monitoring-and-debugging/metrics' as `/${string}`,
             },
             {
               name: 'Grafana Cloud',
-              url: '/guides/telemetry/metrics/grafana-cloud' as `/${string}`,
+              url: '/guides/monitoring-and-debugging/metrics/grafana-cloud' as `/${string}`,
             },
             {
               name: 'Grafana self-hosted',
-              url: '/guides/telemetry/metrics/grafana-self-hosted' as `/${string}`,
+              url: '/guides/monitoring-and-debugging/metrics/grafana-self-hosted' as `/${string}`,
             },
             {
               name: 'Datadog',
@@ -3041,13 +3043,17 @@ export const telemetry: NavMenuConstant = {
             },
             {
               name: 'Vendor-agnostic setup',
-              url: '/guides/telemetry/metrics/vendor-agnostic' as `/${string}`,
+              url: '/guides/monitoring-and-debugging/metrics/vendor-agnostic' as `/${string}`,
             },
           ],
         },
         {
           name: 'Sentry integration',
-          url: '/guides/telemetry/sentry-monitoring' as `/${string}`,
+          url: '/guides/monitoring-and-debugging/sentry-monitoring' as `/${string}`,
+        },
+        {
+          name: 'Tracing with the JS SDK',
+          url: '/guides/monitoring-and-debugging/client-side-tracing' as `/${string}`,
         },
       ],
     },

apps/docs/components/Navigation/NavigationMenu/NavigationMenu.utils.ts

@@ -1,10 +1,11 @@
 'use client'
 
-import { usePathname } from 'next/navigation'
-import { useEffect, useState } from 'react'
 import { MenuId } from '~/components/Navigation/NavigationMenu/NavigationMenu'
 import type { ICommonItem } from '~/components/reference/Reference.types'
 import type { Json } from '~/features/helpers.types'
+import { usePathname } from 'next/navigation'
+import { useEffect, useState } from 'react'
+
 import { menuState } from '../../../hooks/useMenuState'
 
 export function getPathWithoutHash(relativePath: string) {
@@ -134,7 +135,7 @@ export const getMenuId = (pathname: string | null) => {
       return MenuId.LocalDevelopment
     case pathname.startsWith('ai-tools'):
       return MenuId.AiTools
-    case pathname.startsWith('telemetry'):
+    case pathname.startsWith('monitoring-and-debugging'):
       return MenuId.Telemetry
     case pathname.startsWith('platform'):
       return MenuId.Platform

apps/docs/content/guides/database/connection-management.mdx

@@ -47,11 +47,11 @@ For Teams and Enterprise plans, Supabase provides Advanced Telemetry charts dire
 
 This chart helps you monitor connection pool usage, identify connection leaks, and plan capacity. It also shows a reference line for your compute size's maximum connection limit.
 
-For more details on using these monitoring charts, see the [Reports guide](/docs/guides/telemetry/reports#advanced-telemetry).
+For more details on using these monitoring charts, see the [Reports guide](/docs/guides/monitoring-and-debugging/reports#advanced-telemetry).
 
 #### Grafana Dashboard
 
-Supabase offers a Grafana Dashboard that records and visualizes over 200 project metrics, including connections. For setup instructions, check the [metrics docs](/docs/guides/telemetry/metrics).
+Supabase offers a Grafana Dashboard that records and visualizes over 200 project metrics, including connections. For setup instructions, check the [metrics docs](/docs/guides/monitoring-and-debugging/metrics).
 
 Its "Client Connections" graph displays connections for both Supavisor and Postgres
 ![client connection graph](/docs/img/database/grafana-connections.png)

apps/docs/content/guides/database/extensions/pgaudit.mdx

@@ -391,5 +391,5 @@ PGAudit's [official documentation](https://www.pgaudit.org) focuses on system an
 
 - [Official `PGAudit` documentation](https://www.pgaudit.org)
 - [Database Function Logging](/docs/guides/database/functions#general-logging)
-- [Supabase Logging](/docs/guides/telemetry/logs)
+- [Supabase Logging](/docs/guides/monitoring-and-debugging/logs)
 - [Self-Hosting Logs](/docs/reference/self-hosting-analytics/introduction)

apps/docs/content/guides/database/replication/manual-replication-monitoring.mdx

@@ -8,12 +8,12 @@ sidebar_label: 'Monitoring'
 
 Monitoring replication lag is important and there are 3 ways to do this:
 
-1. Dashboard - In [Reports](/docs/guides/telemetry/reports), you can view the replication lag of your project
+1. Dashboard - In [Reports](/docs/guides/monitoring-and-debugging/reports), you can view the replication lag of your project
 2. Database -
    - pg_stat_subscription (subscriber) - if PID is null, then the subscription is not active
    - pg_stat_subscription_stats - look here for error_count to see if there were issues applying or syncing (if yes, check the logs for why)
    - pg_replication_slots - use this to check if the slot is active and you can also calculate the lag from here
-3. [Metrics](/docs/guides/telemetry/metrics) - Using the prometheus endpoint for your project
+3. [Metrics](/docs/guides/monitoring-and-debugging/metrics) - Using the prometheus endpoint for your project
    - replication_slots_max_lag_bytes - this is the more important one
    - pg_stat_replication_replay_lag - lag to replay WAL files from the source DB on the target DB (throttled by disk or high activity)
    - pg_stat_replication_send_lag - lag in sending WAL files from the source DB (a high lag means that the publisher is not being asked to send new WAL files OR network issues)

apps/docs/content/guides/monitoring-and-debugging.mdx

@@ -0,0 +1,9 @@
+---
+title: Monitoring and Debugging
+---
+
+Monitor your project, debug errors, and understand what's happening across the Supabase stack.
+
+<ContentListings id="telemetry-debugging" />
+
+<ContentListings id="telemetry-monitoring" />

apps/docs/content/guides/monitoring-and-debugging/client-side-tracing.mdx

@@ -73,7 +73,7 @@ Once trace context is flowing through, the `trace_id` appears in:
 - **API Gateway logs** — every request to PostgREST, Auth, Storage, and Realtime
 - **Edge Function logs** — invocations and any structured logs emitted from within the function
 
-If you forward Supabase logs to a third-party backend via [Log Drains](/docs/guides/telemetry/log-drains), you can join Supabase logs to your own client and server traces using the shared `trace_id`. This is especially useful for self-hosted setups where you already operate your own OpenTelemetry collector — Supabase logs become first-class citizens in your existing tracing UI.
+If you forward Supabase logs to a third-party backend via [Log Drains](/docs/guides/monitoring-and-debugging/log-drains), you can join Supabase logs to your own client and server traces using the shared `trace_id`. This is especially useful for self-hosted setups where you already operate your own OpenTelemetry collector — Supabase logs become first-class citizens in your existing tracing UI.
 
 ## Using a vendor tracing SDK
 

apps/docs/content/guides/monitoring-and-debugging/debugging.mdx

@@ -1,22 +1,22 @@
 ---
 id: 'debugging'
-title: 'Debugging'
+title: 'Debugging guide'
 description: 'Isolate and fix Supabase issues by reading the error, isolating the failing layer, and gathering evidence from logs.'
 ---
 
 Debug by evidence, not by guessing. A Supabase error almost always surfaces at one layer but originates at another, so the fastest path to a fix is finding _where_ the problem is, not pattern-matching the symptom. Retrying a failed request rarely helps; isolating the layer does.
 
-## The debugging loop
+## Follow these debugging steps
 
 Work through these steps in order, skipping straight to a fix before you have evidence for the cause is the most common way to waste time on a bug.
 
 1. **Reproduce the issue and read the error precisely.** Capture the exact status code, the error code, and the full message, not a paraphrase. A `401` is not a `403`; `PGRST002` is not `PGRST106`; a Postgres `SQLSTATE` such as `42501`, `42P01`, or `23505` points at the exact failure. The precise error is your strongest clue. If you're using `supabase-js`, remember that errors are **returned, not thrown**, check the `error` field in the `{ data, error }` response object. Make sure your code inspects `error` — a swallowed error is why many bugs look like "nothing happened".
 2. **Locate the failing layer.** Use the request stack below. The status code and error code usually name the layer for you.
-3. **Gather evidence for that layer.** Query its logs, run the security and performance advisors, and inspect the schema. Logs are the primary tool, and the layer you identified in the previous step tells you which log source to query. See [Reading logs](#reading-logs) below.
+3. **Gather evidence for that layer.** Query its logs, run the security and performance advisors, and inspect the schema. Logs are the primary tool, and the layer you identified in the previous step tells you which log source to query. See [Read the logs](#read-the-logs) below.
 4. **Isolate the cause** using the troubleshooting guide for that layer (see [Find the guide for your symptom](#find-the-guide-for-your-symptom) below). Confirm your hypothesis against the evidence before you act. Most Supabase issues trace back to a small, known set of causes, and the guide explains how to tell them apart.
 5. **Apply the fix, then verify.** Re-run the exact operation that failed and confirm it now succeeds, and that the corresponding log line is clean. A fix you haven't re-run is still a guess. If a couple of attempts don't resolve it, stop and gather more evidence rather than repeating the same change.
 
-## The Supabase request stack
+## Check the request stack
 
 A request from a client passes through several layers before it reaches your data. Errors propagate upward, so the layer that _reports_ an error is often not the layer that _caused_ it.
 
@@ -44,7 +44,7 @@ A permission error or an unexpectedly empty result at the API layer is often a P
 
 </Admonition>
 
-## Reading logs
+## Read the logs
 
 Once you know the layer, query that layer's log source directly rather than scanning everything. Pick one `source`, bound the time window, and select only the fields you need.
 
@@ -52,7 +52,7 @@ When a query comes up empty, widen along an anchor, such as a timestamp, request
 
 A wide, unfiltered query across every source buries the one line you need and, on paid projects, costs more in scanned data.
 
-The [Logging guide](/docs/guides/telemetry/logs) covers the Logs Explorer, the available log sources, and how to write queries against them.
+The [Logging guide](/docs/guides/monitoring-and-debugging/logs) covers the Logs Explorer, the available log sources, and how to write queries against them.
 
 ## Find the guide for your symptom
 
@@ -71,8 +71,17 @@ Supabase updates these troubleshooting guides continuously, so treat this table
 | Realtime `TIMED_OUT`; `TooManyChannels`; silent disconnect; missed database changes; broadcast-from-DB warning; heartbeats                                                                                       | Realtime → `realtime_logs`                               | [TIMED_OUT](/docs/guides/troubleshooting/realtime-connections-timed_out-status) · [TooManyChannels](/docs/guides/troubleshooting/realtime-too-many-channels-error) · [Silent disconnects](/docs/guides/troubleshooting/realtime-handling-silent-disconnections-in-backgrounded-applications-592794) · [Broadcast warning](/docs/guides/troubleshooting/realtime-warn-sending-broadcast-message) · [Heartbeats](/docs/guides/troubleshooting/realtime-heartbeat-messages) · [Logger](/docs/guides/troubleshooting/realtime-debugging-with-logger)                                                                                                                                                                                                                                              |
 | Upload or list fails; public bucket inaccessible; `relation "objects" does not exist`; file size limit; folder or RLS issue                                                                                      | Storage → `storage_logs`, `postgres_logs`                | [Public bucket upload/list](/docs/guides/troubleshooting/why-cant-i-uploadlistetc-my-public-bucket-Z6CmGt) · [403 RLS on upload](/docs/guides/troubleshooting/storage-error-403-forbidden-new-row-violates-row-level-security-policy-on-upload-a94384) · [relation objects does not exist](/docs/guides/troubleshooting/relation-objects-does-not-exist-error-during-storage-uploads-8f21f0) · [File size limits](/docs/guides/troubleshooting/upload-file-size-restrictions-Y4wQLT) · [Folder ops / hierarchical RLS](/docs/guides/troubleshooting/supabase-storage-inefficient-folder-operations-and-hierarchical-rls-challenges-b05a4d)                                                                                                                                                    |
 | Webhook not firing; `pg_cron` job not running; `pg_net` queue stuck; `42501 ... http_request_queue`                                                                                                              | Database jobs → `postgres_logs`                          | [Webhook debugging](/docs/guides/troubleshooting/webhook-debugging-guide-M8sk47) · [pg_cron debugging](/docs/guides/troubleshooting/pgcron-debugging-guide-n1KTaz) · [42501 http_request_queue](/docs/guides/troubleshooting/42501--permission-denied-for-table-httprequestqueue-KnozmQ)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| Reading or querying logs; interpreting Postgres logs; finding API errors in logs; reading metrics                                                                                                                | Diagnostics → any log source                             | [Logging guide](/docs/guides/telemetry/logs) · [Interpret Postgres logs](/docs/guides/troubleshooting/how-to-interpret-and-explore-the-postgres-logs-OuCIOj) · [API errors in logs](/docs/guides/troubleshooting/discovering-and-interpreting-api-errors-in-the-logs-7xREI9) · [Logging levels](/docs/guides/troubleshooting/understanding-postgresql-logging-levels-and-how-they-impact-your-project-KXiJRm) · [View database metrics](/docs/guides/troubleshooting/how-to-view-database-metrics-uqf2z_)                                                                                                                                                                                                                                                                                     |
+| Reading or querying logs; interpreting Postgres logs; finding API errors in logs; reading metrics                                                                                                                | Diagnostics → any log source                             | [Logging guide](/docs/guides/monitoring-and-debugging/logs) · [Interpret Postgres logs](/docs/guides/troubleshooting/how-to-interpret-and-explore-the-postgres-logs-OuCIOj) · [API errors in logs](/docs/guides/troubleshooting/discovering-and-interpreting-api-errors-in-the-logs-7xREI9) · [Logging levels](/docs/guides/troubleshooting/understanding-postgresql-logging-levels-and-how-they-impact-your-project-KXiJRm) · [View database metrics](/docs/guides/troubleshooting/how-to-view-database-metrics-uqf2z_)                                                                                                                                                                                                                                                                      |
 
 For query performance and schema-design questions such as indexing, `EXPLAIN`, N+1 queries, or partitioning, see the [Postgres guides](/docs/guides/database/overview).
 
 Debugging is complete only once you've re-run the failing operation, confirmed it succeeds, and checked that the layer's logs show a clean result.
+
+## Per-product debugging
+
+Each Supabase product has its own debugging resources. Use these as a starting point when the error originates in a specific service.
+
+- [Database — Debugging and monitoring](/docs/guides/database/inspect)
+- [Auth — Error codes](/docs/guides/auth/debugging/error-codes)
+- [Storage — Debugging](/docs/guides/storage/debugging/logs)
+- [Edge Functions — Local debugging](/docs/guides/functions/debugging-tools)

apps/docs/content/guides/monitoring-and-debugging/log-drains.mdx

@@ -9,7 +9,7 @@ Log drains send all logs of the Supabase stack to one or more desired destinatio
 ## What you can do with log drains
 
 - Route Supabase logs (Postgres, Auth, Storage, Edge Functions, and more) to any observability platform.
-- Combine Supabase logs with application-level traces — see [Tracing with the JS SDK](/docs/guides/telemetry/client-side-tracing) to extend your traces into Supabase.
+- Combine Supabase logs with application-level traces — see [Tracing with the JS SDK](/docs/guides/monitoring-and-debugging/client-side-tracing) to extend your traces into Supabase.
 - Archive logs to S3 for long-term retention and compliance.
 - Build alerts and dashboards on top of Supabase log data in your preferred vendor.
 
@@ -335,5 +335,5 @@ Logs are forwarded to a remote Syslog receiver using TCP or TLS, adhering to [RF
 ## Additional resources
 
 - [Log Drains pricing breakdown](/docs/guides/platform/manage-your-usage/log-drains) — cost per drain, per million events, and egress charges.
-- [Metrics API](/docs/guides/telemetry/metrics) — export Postgres performance metrics alongside your logs.
-- [Tracing with the JS SDK](/docs/guides/telemetry/client-side-tracing) — instrument your application and combine traces with Supabase logs.
+- [Metrics API](/docs/guides/monitoring-and-debugging/metrics) — export Postgres performance metrics alongside your logs.
+- [Tracing with the JS SDK](/docs/guides/monitoring-and-debugging/client-side-tracing) — instrument your application and combine traces with Supabase logs.

apps/docs/content/guides/monitoring-and-debugging/log-field-reference.mdx

@@ -4,7 +4,7 @@ title: 'Logs field reference'
 description: 'Supabase Logs field reference'
 ---
 
-Refer to the full field reference for each available source below. To access each nested key, you need to perform the [necessary unnesting joins](/docs/guides/telemetry/advanced-log-filtering#unnesting-arrays)
+Refer to the full field reference for each available source below. To access each nested key, you need to perform the [necessary unnesting joins](/docs/guides/monitoring-and-debugging/advanced-log-filtering#unnesting-arrays)
 
 <SharedData data="logConstants">
   {(logConstants) => (

apps/docs/content/guides/monitoring-and-debugging/logs.mdx

@@ -6,10 +6,22 @@ description: 'Getting started with Supabase Log Browser'
 
 The Supabase Platform includes a Logs Explorer that allows log tracing and debugging. Log retention is based on your [project's pricing plan](/pricing). For details on how Logs usage is billed, see [Manage Logs usage](/docs/guides/platform/manage-your-usage/logs).
 
+<Admonition type="note">
+
+If you are debugging a specific error or unexpected behavior, start with the [Debugging guide](/docs/guides/monitoring-and-debugging/debugging) — it routes you to the right log source based on your error code or symptom before you open the Logs Explorer.
+
+</Admonition>
+
 ## Product logs
 
 Supabase provides a logging interface specific to each product. You can use regular expressions for keywords and patterns to search log event messages. You can also export and download the log events matching your query as a spreadsheet.
 
+<Admonition type="note">
+
+For regular expression filtering, structured-field queries, and field discovery techniques, see [Advanced log filtering](/docs/guides/monitoring-and-debugging/advanced-log-filtering).
+
+</Admonition>
+
 {/* <!-- To update screenshots, ensure that at least one log line is selected to display the metadata. Can use meme.town as an example. --> */}
 
 <Tabs

apps/docs/content/guides/monitoring-and-debugging/metrics.mdx

@@ -39,5 +39,5 @@ Pick the workflow that best matches your tooling. Cards link to Supabase-authore
 - [Supabase Grafana repository](https://github.com/supabase/supabase-grafana) for dashboard JSON and alert examples.
 - [Grafana Cloud’s Supabase integration doc](https://grafana.com/docs/grafana-cloud/monitor-infrastructure/integrations/integration-reference/integration-supabase/) (community-maintained, built on this Metrics API).
 - [Datadog’s Supabase integration doc](https://docs.datadoghq.com/integrations/supabase/) (community-maintained, built on this Metrics API).
-- [Log Drains ](/docs/guides/telemetry/log-drains) for exporting event-based telemetry alongside metrics.
+- [Log Drains ](/docs/guides/monitoring-and-debugging/log-drains) for exporting event-based telemetry alongside metrics.
 - [Query Performance report](/dashboard/project/_/observability/query-performance) for built-in visualizations based on the same underlying metrics.

apps/docs/content/guides/platform/billing-on-supabase.mdx

@@ -84,7 +84,7 @@ While your subscription plan applies to your entire organization and is charged
 - [Compute](/docs/guides/platform/compute-and-disk#compute) to scale your database up to 64 cores and 256 GB RAM
 - [Read Replicas](/docs/guides/platform/read-replicas) to scale read operations and provide resiliency
 - [Disk](/docs/guides/platform/compute-and-disk#disk) to provision extra IOPS/throughput or use a high-performance SSD
-- [Log Drains](/docs/guides/telemetry/log-drains) to sync Supabase logs to a logging system of your choice
+- [Log Drains](/docs/guides/monitoring-and-debugging/log-drains) to sync Supabase logs to a logging system of your choice
 - [Custom Domains](/docs/guides/platform/custom-domains) to provide a branded experience
 - [PITR](/docs/guides/platform/backups#point-in-time-recovery) to roll back to any specific point in time, down to the minute
 - [IPv4](/docs/guides/platform/ipv4-address) for a dedicated IPv4 address

apps/docs/content/guides/platform/postgres-connection-logging.mdx

@@ -4,7 +4,7 @@ title: 'Postgres connection logging'
 description: 'Enable or disable Postgres connection logging for audit and compliance.'
 ---
 
-For security monitoring and compliance audits, Postgres can log connection lifecycle events to your project's [Postgres logs](/docs/guides/telemetry/logs#postgres), including events such as `connection received`, `connection authenticated`, and `connection authorized`.
+For security monitoring and compliance audits, Postgres can log connection lifecycle events to your project's [Postgres logs](/docs/guides/monitoring-and-debugging/logs#postgres), including events such as `connection received`, `connection authenticated`, and `connection authorized`.
 
 ## Default behavior
 
@@ -28,7 +28,7 @@ Connection logging supports audit and monitoring controls required by some compl
 - **HIPAA** — High-compliance projects should keep connection logging enabled. See the [shared responsibility model for healthcare data](/docs/guides/deployment/shared-responsibility-model#managing-healthcare-data) and [HIPAA compliance guide](/docs/guides/security/hipaa-compliance).
 - **SOC 2** — Users who need connection audit evidence should enable logging and retain logs according to their own policies. See the [SOC 2 compliance guide](/docs/guides/security/soc-2-compliance).
 
-Disabling connection logging does not affect other Supabase logging (for example, [Platform Audit Logs](/docs/guides/security/platform-audit-logs), [Auth Audit Logs](/docs/guides/auth/audit-logs), or [pgAudit](/docs/guides/telemetry/logs#configuring-pgauditlog)).
+Disabling connection logging does not affect other Supabase logging (for example, [Platform Audit Logs](/docs/guides/security/platform-audit-logs), [Auth Audit Logs](/docs/guides/auth/audit-logs), or [pgAudit](/docs/guides/monitoring-and-debugging/logs#configuring-pgauditlog)).
 
 ## Manage connection logging via the dashboard
 

apps/docs/content/guides/platform/read-replicas.mdx

@@ -152,7 +152,7 @@ When a Read Replica is deployed, it emits logs from the following services:
 - [PostgREST](/dashboard/project/_/logs/postgrest-logs)
 - [Supavisor](/dashboard/project/_/logs/pooler-logs)
 
-Views on [Log Explorer](/docs/guides/telemetry/logs) are automatically filtered by databases, with the logs of the Primary database displayed by default. Viewing logs from other databases can be toggled with the `Source` button found on the upper-right part section of the Logs Explorer page.
+Views on [Log Explorer](/docs/guides/monitoring-and-debugging/logs) are automatically filtered by databases, with the logs of the Primary database displayed by default. Viewing logs from other databases can be toggled with the `Source` button found on the upper-right part section of the Logs Explorer page.
 
 For API logs, logs can originate from the API Load Balancer as well. The upstream database or the one that eventually handles the request can be found under the `Redirect Identifier` field. This is equivalent to `metadata.load_balancer_redirect_identifier` when querying the underlying logs.
 
@@ -160,7 +160,7 @@ For API logs, logs can originate from the API Load Balancer as well. The upstrea
 
 Observability and metrics for Read Replicas are available on the Supabase Dashboard. Resource utilization for a specific Read Replica can be viewed on the [Database Reports page](/dashboard/project/_/observability/database) by toggling for `Source`. Likewise, metrics on API requests going through either a Read Replica or Load Balancer API endpoint are also available on the dashboard through the [API Reports page](/dashboard/project/_/observability/api-overview)
 
-We recommend ingesting your [project's metrics](/docs/guides/telemetry/metrics) into your own environment. If you have an existing ingestion pipeline set up for your project, you can [update it](https://github.com/supabase/supabase-grafana?tab=readme-ov-file#read-replica-support) to additionally ingest metrics from your Read Replicas.
+We recommend ingesting your [project's metrics](/docs/guides/monitoring-and-debugging/metrics) into your own environment. If you have an existing ingestion pipeline set up for your project, you can [update it](https://github.com/supabase/supabase-grafana?tab=readme-ov-file#read-replica-support) to additionally ingest metrics from your Read Replicas.
 
 ### Centralized configuration management
 

apps/docs/content/guides/platform/read-replicas/getting-started.mdx

@@ -129,7 +129,7 @@ There is no single threshold to indicate when you should address replication lag
 
 <Admonition type="note">
 
-If you are already ingesting your [project's metrics](/docs/guides/telemetry/metrics) into your own environment, you can also keep track of replication lag and set alarms with the `physical_replication_lag_physical_replica_lag_seconds` metric.
+If you are already ingesting your [project's metrics](/docs/guides/monitoring-and-debugging/metrics) into your own environment, you can also keep track of replication lag and set alarms with the `physical_replication_lag_physical_replica_lag_seconds` metric.
 
 </Admonition>
 

apps/docs/content/guides/security/platform-audit-logs.mdx

@@ -46,7 +46,7 @@ Each Supabase user account also has access to [Account Audit logs](/dashboard/ac
 
 ## Accessing Audit Log Drains
 
-Audit Log Drains can be configured under your [organization's audit log drains](/dashboard/org/_/audit-log-drains). For setup instructions and supported destinations, see the [Log Drains guide](/docs/guides/telemetry/log-drains).
+Audit Log Drains can be configured under your [organization's audit log drains](/dashboard/org/_/audit-log-drains). For setup instructions and supported destinations, see the [Log Drains guide](/docs/guides/monitoring-and-debugging/log-drains).
 
 ## Limitations
 

apps/docs/content/guides/storage/cdn/metrics.mdx

@@ -5,7 +5,7 @@ description: 'Learn how Supabase Storage caches objects with a CDN.'
 sidebar_label: 'CDN'
 ---
 
-Cache hits can be determined via the `metadata.response.headers.cf_cache_status` key in our [Logs Explorer](/docs/guides/telemetry/logs#logs-explorer). Any value that corresponds to either `HIT`, `STALE`, `REVALIDATED`, or `UPDATING` is categorized as a cache hit.
+Cache hits can be determined via the `metadata.response.headers.cf_cache_status` key in our [Logs Explorer](/docs/guides/monitoring-and-debugging/logs#logs-explorer). Any value that corresponds to either `HIT`, `STALE`, `REVALIDATED`, or `UPDATING` is categorized as a cache hit.
 The following example query will show the top cache misses from the `edge_logs`:
 
 ```sql

apps/docs/content/guides/storage/debugging/logs.mdx

@@ -11,7 +11,7 @@ For more advanced filtering needs, use the [Logs Explorer](/dashboard/project/_/
 
 <Admonition type="note">
   
-For more details on filtering the log tables, see [Advanced Log Filtering](/docs/guides/telemetry/advanced-log-filtering)
+For more details on filtering the log tables, see [Advanced Log Filtering](/docs/guides/monitoring-and-debugging/advanced-log-filtering)
 
 </Admonition>
 

apps/docs/content/guides/telemetry.mdx

@@ -1,13 +0,0 @@
----
-title: Telemetry
----
-
-Telemetry helps you understand what’s happening inside your app by collecting logs, metrics, and traces.
-
-- **Logs** capture individual events, such as errors or warnings, providing details about what happened at a specific moment.
-- **Metrics** track numerical data over time, like request latency or database query performance, helping you spot trends.
-- **Traces** show the flow of a request through different services, helping you debug slow or failing operations.
-
-Supabase is working towards full support for the [OpenTelemetry](https://opentelemetry.io/) standard, making it easier to integrate with observability tools.
-
-This section provides guidance on telemetry in Supabase, including how to work with Supabase Logs.

apps/docs/content/troubleshooting/exhaust-disk-io.mdx

@@ -25,7 +25,7 @@ Running out of Disk IO Budget means that your instance is using more disk than i
 
 To check your Disk IO Budget on the Supabase Platform, head over to [Database Health in the Observability section](/dashboard/project/_/observability/database).
 
-It is also possible to monitor your resources and set up alerts using Prometheus/Grafana. With Grafana you will be able to pinpoint potential causes and see more fine-grained metrics like how much of your RAM is used for caching and your Swap usage. Read the [Metrics Guide](/docs/guides/telemetry/metrics) to learn more.
+It is also possible to monitor your resources and set up alerts using Prometheus/Grafana. With Grafana you will be able to pinpoint potential causes and see more fine-grained metrics like how much of your RAM is used for caching and your Swap usage. Read the [Metrics Guide](/docs/guides/monitoring-and-debugging/metrics) to learn more.
 
 ## Common reasons for high disk IO usage
 

apps/docs/content/troubleshooting/exhaust-ram.mdx

@@ -31,7 +31,7 @@ High RAM usage could come with a range of issues:
 
 To check your RAM usage on the Supabase Platform, head over to [Database Health in the Observability section](/dashboard/project/_/observability/database).
 
-It is also possible to monitor your resources and set up alerts using Prometheus/Grafana. With Grafana you will be able to see how much of your RAM is used for caching and you can track other metrics such as your Swap usage. Read the [Metrics Guide](/docs/guides/telemetry/metrics) to learn more.
+It is also possible to monitor your resources and set up alerts using Prometheus/Grafana. With Grafana you will be able to see how much of your RAM is used for caching and you can track other metrics such as your Swap usage. Read the [Metrics Guide](/docs/guides/monitoring-and-debugging/metrics) to learn more.
 
 ## Common reasons for high RAM usage
 

apps/docs/content/troubleshooting/exhaust-swap.mdx

@@ -33,7 +33,7 @@ High Swap usage can affect your database performance. For example, you might see
 
 ## Monitor your swap
 
-You can monitor your resources and set up alerts using Prometheus/Grafana. See the [metrics guide](/docs/guides/telemetry/metrics) for more information.
+You can monitor your resources and set up alerts using Prometheus/Grafana. See the [metrics guide](/docs/guides/monitoring-and-debugging/metrics) for more information.
 
 An [example repository](https://github.com/supabase/supabase-grafana) to ingest metrics and visualize them with Grafana is provided in the linked guide, where we maintain a [list of the exported metrics](https://github.com/supabase/supabase-grafana/blob/main/docs/metrics.md).
 

apps/docs/content/troubleshooting/failed-to-retrieve-tables.mdx

@@ -43,4 +43,4 @@ Once you are confident there will not be a crash loop, you can review the follow
 - Continue to monitor your project's [query performance tab](/dashboard/project/_/observability/query-performance) and [enable index advisor](/docs/guides/database/extensions/index_advisor) if you haven't already - especially if there are a lot of select queries.
 - If after monitoring your changes you still do not notice improvements, consider upgrading compute if you think this level of activity is going to be regular. It will give you more memory overhead to process tasks like this. You can view all compute offerings [here](/dashboard/project/_/settings/infrastructure).
 
-If you want to effectively monitor your project's performance minute by minute, you can use the [Metrics API](/docs/guides/telemetry/metrics).
+If you want to effectively monitor your project's performance minute by minute, you can use the [Metrics API](/docs/guides/monitoring-and-debugging/metrics).

apps/docs/content/troubleshooting/failed-to-run-sql-query-connection-terminated-due-to-connection-timeout.mdx

@@ -23,4 +23,4 @@ Review the appropriate guides based on your scenario:
 - [High Disk I/O](/docs/guides/troubleshooting/exhaust-disk-io)
 - [Query optimization](/docs/guides/database/query-optimization)
 
-You can also set up alerts using a [Prometheus endpoint / Grafana charts](/docs/guides/telemetry/metrics) to monitor vital resources.
+You can also set up alerts using a [Prometheus endpoint / Grafana charts](/docs/guides/monitoring-and-debugging/metrics) to monitor vital resources.

apps/docs/content/troubleshooting/high-cpu-usage.mdx

@@ -25,7 +25,7 @@ You can check your CPU usage directly on the Supabase Platform. For this go to d
 
 ![CPU usage reported on Supabase dashboard](/docs/img/guides/platform/exhaust-cpu-report.png)
 
-It is also possible to monitor your resources and set up alerts using Prometheus/Grafana. You can find a guide for this [here](/docs/guides/telemetry/metrics).
+It is also possible to monitor your resources and set up alerts using Prometheus/Grafana. You can find a guide for this [here](/docs/guides/monitoring-and-debugging/metrics).
 
 ## Common reasons for high CPU usage
 

apps/docs/content/troubleshooting/how-to-interpret-and-explore-the-postgres-logs-OuCIOj.mdx

@@ -398,5 +398,5 @@ To see the default types of events that are logged, you can check this [guide](h
 - [Debugging with the DB API logs](https://github.com/orgs/supabase/discussions/22849)
 - [Debugging Database Functions](/docs/guides/database/functions#debugging-functions)
 - [pg_audit](/docs/guides/database/extensions/pgaudit)
-- [Supabase Logging](/docs/guides/telemetry/logs)
+- [Supabase Logging](/docs/guides/monitoring-and-debugging/logs)
 - [Self-Hosting Logs](/docs/reference/self-hosting-analytics/introduction)

apps/docs/content/troubleshooting/how-to-view-database-metrics-uqf2z_.mdx

@@ -7,6 +7,6 @@ keywords = [ "metrics", "grafana", "monitoring" ]
 database_id = "da2d95e5-abc5-47c8-8389-1554d12abf91"
 ---
 
-To monitor real-time metrics of your database, like CPU, EBS, active database connections, and memory usage, you can deploy a Grafana Dashboard. Check our [GitHub repo](https://github.com/supabase/supabase-grafana) for setup instructions for local or free [Fly.io](http://fly.io/) deployments. Refer to our concise [documentation](/docs/guides/telemetry/metrics) to learn more about the metrics endpoint.
+To monitor real-time metrics of your database, like CPU, EBS, active database connections, and memory usage, you can deploy a Grafana Dashboard. Check our [GitHub repo](https://github.com/supabase/supabase-grafana) for setup instructions for local or free [Fly.io](http://fly.io/) deployments. Refer to our concise [documentation](/docs/guides/monitoring-and-debugging/metrics) to learn more about the metrics endpoint.
 
 While the [Dashboard's Reports Page](/dashboard/project/_/observability) displays some metric data, it provides hourly averages, not real-time by the second data. However, it offers query metrics, which the Grafana Dashboard does not include.

apps/docs/content/troubleshooting/interpreting-supabase-grafana-io-charts-MUynDR.mdx

@@ -7,7 +7,7 @@ keywords = [ "io", "disk", "database", "grafana" ]
 database_id = "0056cd40-df04-4045-bbfb-c245cb15b85d"
 ---
 
-> [Supabase Grafana Installation Guide](/docs/guides/telemetry/metrics/grafana-self-hosted)
+> [Supabase Grafana Installation Guide](/docs/guides/monitoring-and-debugging/metrics/grafana-self-hosted)
 
 There are two primary values that matter for IO:
 

apps/docs/content/troubleshooting/monitor-supavisor-postgres-connections.mdx

@@ -19,7 +19,7 @@ _Visual of Grafana Dashboard_
 
 It can be run locally within Docker. Alternatively, you can deploy it to fly.io or Grafana Cloud, which are better for long-term data collection.
 
-Installation instructions can be found in it the [metrics docs ](/docs/guides/telemetry/metrics/grafana-self-hosted)
+Installation instructions can be found in it the [metrics docs ](/docs/guides/monitoring-and-debugging/metrics/grafana-self-hosted)
 
 ## Observing connections
 

apps/docs/content/troubleshooting/steps-to-improve-query-performance-with-indexes-q8PoC9.mdx

@@ -23,7 +23,7 @@ Supabase has an [open-source Grafana Repo](https://github.com/supabase/supabase-
 _Visual of Grafana Dashboard_
 ![image](/docs/img/troubleshooting/18ed2c88-332e-4e66-b9b4-c37e99a39104.png)
 
-It can be run locally within Docker or can be deployed for free to fly.io. Installation instructions can be found in [Supabase's metrics docs](/docs/guides/telemetry/metrics/grafana-self-hosted)
+It can be run locally within Docker or can be deployed for free to fly.io. Installation instructions can be found in [Supabase's metrics docs](/docs/guides/monitoring-and-debugging/metrics/grafana-self-hosted)
 
 ### Query optimization through indexes
 

apps/docs/content/troubleshooting/supabase-grafana-memory-charts.mdx

@@ -7,7 +7,7 @@ date_created = "2024-06-05"
 database_id = "179d70f3-1e26-4346-9ee8-d340fad382a3"
 ---
 
-> [Supabase Grafana Installation Guide](/docs/guides/telemetry/metrics/grafana-self-hosted)
+> [Supabase Grafana Installation Guide](/docs/guides/monitoring-and-debugging/metrics/grafana-self-hosted)
 
 Here are examples of unhealthy memory usage:
 ![image](https://github.com/supabase/supabase/assets/91111415/baebfc74-642d-4988-992c-bb0f473a05ad)

apps/docs/content/troubleshooting/supavisor-faq-YyP5tI.mdx

@@ -159,7 +159,7 @@ As a rule of thumb, if you're using the DB REST API or multiple app-based "user+
 
 Connection usage can be monitored with a Supabase Grafana Dashboard. It provides realtime visibility of over 200 database metrics, such as graphs of CPU, EBS, and active direct/pooler connections. It can be extremely useful for monitoring and debugging instances.
 
-You can check our [GitHub repo](https://github.com/supabase/supabase-grafana) for setup instructions for local deployments or free cloud deployments on [Fly.io](http://fly.io/). Refer to Supabase [documentation](/docs/guides/telemetry/metrics) to learn more about the metrics endpoint.
+You can check our [GitHub repo](https://github.com/supabase/supabase-grafana) for setup instructions for local deployments or free cloud deployments on [Fly.io](http://fly.io/). Refer to Supabase [documentation](/docs/guides/monitoring-and-debugging/metrics) to learn more about the metrics endpoint.
 
 ### **Can Supavisor really support a million connections?**
 

apps/docs/data/content-listings/index.ts

@@ -21,6 +21,7 @@ import {
   selfHostingShareExperience,
 } from './self-hosting.data'
 import { storageExamples, storageGetStarted, storageResources } from './storage.data'
+import { telemetryDebugging, telemetryMonitoring } from './telemetry.data'
 
 const ALL_GROUPS: readonly ContentListingGroup[] = [
   aiToolsSupportedAgents,
@@ -48,6 +49,8 @@ const ALL_GROUPS: readonly ContentListingGroup[] = [
   storageGetStarted,
   storageExamples,
   storageResources,
+  telemetryDebugging,
+  telemetryMonitoring,
 ]
 
 export const CONTENT_LISTINGS: Readonly<Record<string, ContentListingGroup>> = Object.fromEntries(

apps/docs/data/content-listings/log-drains.data.ts

@@ -9,55 +9,55 @@ export const logDrainsDestinations: ContentListingGroup = {
     {
       title: 'Custom Endpoint',
       description: 'Forward logs as a POST request to any custom HTTP endpoint.',
-      href: '/guides/telemetry/log-drains#custom-endpoint',
+      href: '/guides/monitoring-and-debugging/log-drains#custom-endpoint',
       icon: { kind: 'braces', color: '#3ECF8E', bg: 'rgba(62,207,142,0.1)' },
     },
     {
       title: 'OpenTelemetry (OTLP)',
       description: 'Send logs to any OTLP-compatible endpoint using Protocol Buffers over HTTP.',
-      href: '/guides/telemetry/log-drains#opentelemetry-otlp',
+      href: '/guides/monitoring-and-debugging/log-drains#opentelemetry-otlp',
       icon: { kind: 'otlp', color: '#F5A623', bg: 'rgba(245,166,35,0.1)' },
     },
     {
       title: 'Datadog',
       description: 'Stream logs directly into Datadog for monitoring and analysis.',
-      href: '/guides/telemetry/log-drains#datadog',
+      href: '/guides/monitoring-and-debugging/log-drains#datadog',
       icon: { kind: 'datadog', color: '#632CA6', bg: 'rgba(99,44,166,0.1)' },
     },
     {
       title: 'Loki',
       description: 'Ingest logs into Grafana Loki using the HTTP push API.',
-      href: '/guides/telemetry/log-drains#loki',
+      href: '/guides/monitoring-and-debugging/log-drains#loki',
       icon: { kind: 'grafana', color: '#F05A28', bg: 'rgba(240,90,40,0.1)' },
     },
     {
       title: 'Amazon S3',
       description: 'Write batched log files directly to an S3 bucket you own.',
-      href: '/guides/telemetry/log-drains#amazon-s3',
+      href: '/guides/monitoring-and-debugging/log-drains#amazon-s3',
       icon: { kind: 'cloud', color: '#FF9900', bg: 'rgba(255,153,0,0.1)' },
     },
     {
       title: 'Sentry',
       description: "Send logs to Sentry's Logging product for filtering and grouping.",
-      href: '/guides/telemetry/log-drains#sentry',
+      href: '/guides/monitoring-and-debugging/log-drains#sentry',
       icon: { kind: 'sentry', color: '#362D59', bg: 'rgba(54,45,89,0.1)' },
     },
     {
       title: 'Axiom',
       description: 'Forward logs to an Axiom dataset for storage and analysis.',
-      href: '/guides/telemetry/log-drains#axiom',
+      href: '/guides/monitoring-and-debugging/log-drains#axiom',
       icon: { kind: 'axiom', color: '#6366F1', bg: 'rgba(99,102,241,0.1)' },
     },
     {
       title: 'Last9',
       description: 'Stream logs to Last9 for OpenTelemetry-native observability.',
-      href: '/guides/telemetry/log-drains#last9',
+      href: '/guides/monitoring-and-debugging/log-drains#last9',
       icon: { kind: 'last9', color: '#00B4A0', bg: 'rgba(0,180,160,0.1)' },
     },
     {
       title: 'Syslog',
       description: 'Forward logs to a remote Syslog receiver over TCP or TLS (RFC 5424).',
-      href: '/guides/telemetry/log-drains#syslog',
+      href: '/guides/monitoring-and-debugging/log-drains#syslog',
       icon: { kind: 'server', color: '#64748B', bg: 'rgba(100,116,139,0.1)' },
     },
   ],

apps/docs/data/content-listings/telemetry.data.ts

@@ -0,0 +1,65 @@
+import type { ContentListingGroup } from '~/lib/content-listings.schema'
+
+export const telemetryDebugging: ContentListingGroup = {
+  id: 'telemetry-debugging',
+  heading: 'Debugging',
+  type: 'grid',
+  columns: 2,
+  items: [
+    {
+      title: 'Debugging guide',
+      href: '/guides/monitoring-and-debugging/debugging',
+      description:
+        'Isolate the failing layer, read logs as evidence, and match symptoms to troubleshooting guides.',
+    },
+    {
+      title: 'Logging',
+      href: '/guides/monitoring-and-debugging/logs',
+      description: 'Query events from any Supabase service using the Logs Explorer.',
+    },
+    {
+      title: 'Advanced log filtering',
+      href: '/guides/monitoring-and-debugging/advanced-log-filtering',
+      description: 'Regex filtering, structured-field queries, and field discovery in ClickHouse.',
+    },
+    {
+      title: 'Troubleshooting index',
+      href: '/guides/troubleshooting',
+      description: 'Searchable index of known error codes, symptoms, and fixes.',
+    },
+  ],
+}
+
+export const telemetryMonitoring: ContentListingGroup = {
+  id: 'telemetry-monitoring',
+  heading: 'Monitoring',
+  type: 'grid',
+  columns: 2,
+  items: [
+    {
+      title: 'Log drains',
+      href: '/guides/monitoring-and-debugging/log-drains',
+      description: 'Forward logs to Datadog, Loki, Axiom, S3, or a custom HTTP endpoint.',
+    },
+    {
+      title: 'Reports',
+      href: '/guides/monitoring-and-debugging/reports',
+      description: 'Built-in dashboards for API, Auth, Storage, and Realtime activity.',
+    },
+    {
+      title: 'Metrics',
+      href: '/guides/monitoring-and-debugging/metrics',
+      description: 'Prometheus-compatible database metrics for Grafana and other tools.',
+    },
+    {
+      title: 'Client-side tracing',
+      href: '/guides/monitoring-and-debugging/client-side-tracing',
+      description: 'Correlate browser requests end-to-end using W3C Trace Context.',
+    },
+    {
+      title: 'Sentry integration',
+      href: '/guides/monitoring-and-debugging/sentry-monitoring',
+      description: 'Send errors to Sentry for alerting and grouping.',
+    },
+  ],
+}

apps/docs/features/docs/GuidesMdx.utils.tsx

@@ -33,6 +33,7 @@ const PUBLISHED_SECTIONS = [
   'graphql',
   'integrations',
   'local-development',
+  'monitoring-and-debugging',
   'platform',
   'queues',
   'realtime',
@@ -40,7 +41,6 @@ const PUBLISHED_SECTIONS = [
   'security',
   'self-hosting',
   'storage',
-  'telemetry',
 ] as const
 
 const getGuidesMarkdownInternal = async (slug: string[]) => {

apps/docs/lib/breadcrumbs.ts

@@ -26,7 +26,7 @@ const SECTION_PATH_TO_KEY: Record<string, keyof typeof NavItems> = {
   security: 'security',
   'self-hosting': 'self_hosting',
   storage: 'storage',
-  telemetry: 'telemetry',
+  'monitoring-and-debugging': 'telemetry',
 }
 
 function getSectionMenu(pathname: string) {

apps/docs/lib/content-listings.test.ts

@@ -189,7 +189,7 @@ describe('dashboard content listing hrefs', () => {
 describe('contentListingItemSchema icon', () => {
   const baseItem = {
     title: 'Datadog',
-    href: '/guides/telemetry/log-drains#datadog',
+    href: '/guides/monitoring-and-debugging/log-drains#datadog',
     description: 'Stream logs directly into Datadog for monitoring and analysis.',
   }
 

apps/www/lib/redirects.js

@@ -119,6 +119,11 @@ module.exports = [
     source: '/docs/guides/reports/:match*',
     destination: '/docs/guides/observability/:match*',
   },
+  {
+    permanent: true,
+    source: '/docs/guides/telemetry/:match*',
+    destination: '/docs/guides/monitoring-and-debugging/:match*',
+  },
   {
     permanent: false,
     source: '/blog/2021/03/08/toad-a-link-shorterner-with-simple-apis-for-low-coders',