[pull] master from supabase:master

apps/design-system/package.json

@@ -19,8 +19,8 @@
   "dependencies": {
     "@hookform/resolvers": "^3.1.1",
     "@tanstack/react-table": "catalog:",
-    "contentlayer2": "0.4.6",
     "common": "workspace:*",
+    "contentlayer2": "0.4.6",
     "date-fns": "^2.30.0",
     "dayjs": "1.11.13",
     "eslint-config-supabase": "workspace:*",
@@ -57,6 +57,7 @@
     "@types/lodash.template": "4.5.0",
     "@types/react": "catalog:",
     "@types/react-dom": "catalog:",
+    "@typescript/native": "catalog:",
     "config": "workspace:*",
     "mdast-util-toc": "^6.1.1",
     "npm-run-all": "^4.1.5",
@@ -66,7 +67,6 @@
     "tailwindcss": "catalog:",
     "tsconfig": "workspace:*",
     "tsx": "catalog:",
-    "@typescript/native": "catalog:",
     "typescript": "catalog:",
     "unist-builder": "3.0.0"
   }

apps/docs/app/guides/telemetry/[[...slug]]/page.tsx → 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/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,71 +2983,77 @@ 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',
               url: 'https://docs.datadoghq.com/integrations/supabase/' as `/${string}`,
             },
             {
               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/auth/managing-user-data.mdx

@@ -210,6 +210,22 @@ You will encounter an error when you try to delete an Auth user that owns any St
 
 </Admonition>
 
+### Removing account access
+
+When the goal is to remove an account so it can no longer access your app, delete the auth user with [`auth.admin.deleteUser()`](/docs/reference/javascript/auth-admin-deleteuser). With the default `shouldSoftDelete: false`, this removes the row from `auth.users`, which cascades to `auth.sessions` and invalidates the user's refresh tokens — so the account can no longer mint new access tokens.
+
+A few things are _not_ a substitute for deleting the user:
+
+- A temporary [ban](/docs/reference/javascript/auth-admin-updateuserbyid) only blocks sign-in for its duration and does not revoke existing sessions.
+- Marking the account as deleted only in your own application tables leaves the `auth.users` row intact, so it can still authenticate and refresh.
+
+Deleting the user still cannot retroactively invalidate an access token that was already issued. Supabase access tokens are stateless JWTs, so a token already in the user's hands stays valid until its `exp` claim passes, and during that window the account can still call the API. You have two ways to handle this window:
+
+- **Bound it:** keep the [access token (JWT) expiry](/docs/guides/auth/sessions) short, so any outstanding token expires soon after you delete the user.
+- **Close it for sensitive operations:** validate the `session_id` claim against the `auth.sessions` table on those operations. Because deleting the user removes the session row, an outstanding token fails this check — but only on the requests where you perform it; other API calls still accept the token until `exp`.
+
+See [User sessions](/docs/guides/auth/sessions) for details.
+
 ## Exporting users
 
 As Supabase is built on top of Postgres, you can query the `auth.users` and `auth.identities` table via the `SQL Editor` tab to extract all users:

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/telemetry/client-side-tracing.mdx → 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