Files
Saxon Fletcher 32341830b3 docs: organize observability by task and move SQL logs to Explorer (#50074)
## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.

Yes.

## What kind of change does this PR introduce?

Documentation update.

## What is the current behavior?

The observability overview and access page overlap; configuration
interrupts querying; related guides send log queries to the old editor.

## What is the new behavior?

The observability overview and navigation follow the same four sections:
Read project data, Detect and diagnose, Hire an agent, and Configure and
export. The overview absorbs the redundant access page, with permanent
redirects for both HTML and Markdown URLs.

“Query logs with SQL” owns ClickHouse querying through MCP, the
Management API, and Explorer with query source Logs. Logging
configuration moves to its own guide; sources, captured headers, and
limits live in the field reference. Inspection links to canonical
diagnostic SQL. Related Storage and database guides use the replacement
Explorer workflow and retain existing anchors where headings move.

## Additional context

Validation: Markdown generation, docs typecheck, targeted ESLint,
formatting, and content-listing tests. Browser overview/navigation
checked; old HTML and Markdown URLs return 308, and the new
configuration page returns 200 in both formats. Three ClickHouse
examples and the Postgres configuration query ran in a disposable
container sandbox. Changed pages have no MDX lint violations;
repository-wide existing failures remain.

Self-review: the Management API request was verified against its
published schema but not sent to a hosted project. Realtime ingestion
and hosted logging configuration still need a hosted smoke check. No
compatibility path for the deprecated logs engine is documented.

Stage 2 of 3; depends on stage 1.


Stack: #50073#50074#50075.

Production docs build also passes at the stack tip after standard
reference generation.



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

- **Documentation**
- Reorganized observability guidance around reading data, detecting
issues, diagnosing problems, agent setup, and exporting data.
  - Added a guide for configuring Postgres and Realtime logging.
- Updated log investigation instructions to use Explorer, SQL queries,
and clearer filters.
  - Added log source, field, and captured-header references.
  - Improved advisor guidance and database performance troubleshooting.
  - Added redirects for moved observability content.

- **Accessibility**
- Improved screen-reader labels for copy and feature-selection controls.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-16 17:03:43 +10:00

273 lines
7.7 KiB
JavaScript

// @ts-check
import configureBundleAnalyzer from '@next/bundle-analyzer'
import nextMdx from '@next/mdx'
import { withSentryConfig } from '@sentry/nextjs'
import withYaml from 'next-plugin-yaml'
import rehypeSlug from 'rehype-slug'
import remarkGfm from 'remark-gfm'
import { parse as parseToml } from 'smol-toml'
import remotePatterns from './lib/remotePatterns.js'
const withBundleAnalyzer = configureBundleAnalyzer({
enabled: process.env.ANALYZE === 'true',
})
const withMDX = nextMdx({
extension: /\.mdx?$/,
options: {
remarkPlugins: [remarkGfm],
rehypePlugins: [rehypeSlug],
providerImportSource: '@mdx-js/react',
},
})
/** @type {import('next').NextConfig} nextConfig */
const nextConfig = {
assetPrefix: getAssetPrefix(),
// Append the default value with md extensions
pageExtensions: ['ts', 'tsx', 'js', 'jsx', 'md', 'mdx'],
// reactStrictMode: true,
// swcMinify: true,
basePath: process.env.NEXT_PUBLIC_BASE_PATH || '/docs',
images: {
dangerouslyAllowSVG: false,
// @ts-ignore
remotePatterns,
},
webpack: (config) => {
config.module.rules.push({
test: /\.include$/,
type: 'asset/source',
})
config.module.rules.push({
test: /\.toml$/,
type: 'json',
parser: {
parse: parseToml,
},
})
return config
},
transpilePackages: [
'ui',
'ui-patterns',
'common',
'dayjs',
'shared-data',
'api-types',
'icons',
'next-mdx-remote',
],
outputFileTracingIncludes: {
'/api/crawlers': ['./features/docs/generated/**/*', './docs/ref/**/*'],
'/api/guides-md/**/*': ['./public/markdown/guides/**/*'],
'/guides/**/*': ['./content/guides/**/*', './content/troubleshooting/**/*', './examples/**/*'],
'/reference/**/*': ['./features/docs/generated/**/*', './docs/ref/**/*'],
},
serverExternalPackages: ['libpg-query', 'twoslash'],
async headers() {
return [
{
source: '/:path*',
headers: [
{
key: 'Strict-Transport-Security',
value: process.env.VERCEL === '1' ? 'max-age=31536000; includeSubDomains; preload' : '',
},
{
key: 'X-Robots-Tag',
value: 'all',
},
{
key: 'X-Frame-Options',
value: 'DENY',
},
],
has: [
{
type: 'host',
value: 'supabase.com',
},
],
},
{
source: '/:path*',
headers: [
{
key: 'Strict-Transport-Security',
value: process.env.VERCEL === '1' ? 'max-age=31536000; includeSubDomains; preload' : '',
},
{
key: 'X-Robots-Tag',
value: 'noindex',
},
{
key: 'X-Frame-Options',
value: 'DENY',
},
],
has: [
{
type: 'host',
value: '(?:.+\\.vercel\\.app)',
},
],
},
{
source: '/favicon/:slug*',
headers: [{ key: 'cache-control', value: 'public, max-age=86400' }],
},
]
},
/**
* Doc rewrites and redirects are
* handled by the `www` nextjs config:
*
* ./apps/www/lib/redirects.js
*
* Only add dev/preview specific redirects
* in this config.
*/
async redirects() {
return [
{
source: '/guides/observability/access-data',
destination: '/guides/observability',
permanent: true,
},
{
source: '/guides/observability/access-data.md',
destination: '/guides/observability.md',
permanent: true,
},
// Redirect root to docs base path in dev/preview envs
{
source: '/',
destination: '/docs',
basePath: false,
permanent: false,
},
// Redirect dashboard links in dev/preview envs
{
source: '/dashboard/:path*',
destination: 'https://supabase.com/dashboard/:path*',
basePath: false,
permanent: false,
},
// Redirect blog links in dev/preview envs
{
source: '/blog/:path*',
destination: 'https://supabase.com/blog/:path*',
basePath: false,
permanent: false,
},
// Redirect old managed pipeline slugs in dev/preview envs
{
source: '/guides/database/replication/external-replication-setup',
destination: '/guides/database/replication/pipelines',
permanent: true,
},
{
source: '/guides/database/replication/external-replication-monitoring',
destination: '/guides/database/replication/pipelines-monitoring',
permanent: true,
},
{
source: '/guides/database/replication/external-replication-faq',
destination: '/guides/database/replication/pipelines-faq',
permanent: true,
},
{
source: '/guides/database/replication/replication-setup',
destination: '/guides/database/replication/pipelines',
permanent: true,
},
{
source: '/guides/database/replication/replication-monitoring',
destination: '/guides/database/replication/pipelines-monitoring',
permanent: true,
},
{
source: '/guides/database/replication/replication-faq',
destination: '/guides/database/replication/pipelines-faq',
permanent: true,
},
{
source: '/guides/database/inspect',
destination: '/guides/monitoring-and-debugging/inspect',
permanent: true,
},
{
source: '/guides/database/database-advisors',
destination: '/guides/observability/advisors',
permanent: true,
},
]
},
typescript: {
// On previews, typechecking is run via GitHub Action only for efficiency
// On production, we turn it on to prevent errors from conflicting PRs getting into
// prod
ignoreBuildErrors: process.env.NEXT_PUBLIC_VERCEL_ENV === 'production' ? false : true,
},
eslint: {
// We are already running linting via GH action, this will skip linting during production build on Vercel
ignoreDuringBuilds: true,
},
}
const configExport = () => {
const plugins = [withMDX, withYaml, withBundleAnalyzer]
// @ts-ignore
return plugins.reduce((acc, next) => next(acc), nextConfig)
}
export default withSentryConfig(configExport, {
// For all available options, see:
// https://www.npmjs.com/package/@sentry/webpack-plugin#options
org: 'supabase',
project: 'docs',
unstable_sentryWebpackPluginOptions: {
applicationKey: 'supabase-docs',
},
// Only print logs for uploading source maps in CI
silent: !process.env.CI,
// For all available options, see:
// https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/
// Upload a larger set of source maps for prettier stack traces (increases build time)
widenClientFileUpload: true,
// Uncomment to route browser requests to Sentry through a Next.js rewrite to circumvent ad-blockers.
// This can increase your server load as well as your hosting bill.
// Note: Check that the configured route will not match with your Next.js middleware, otherwise reporting of client-
// side errors will fail.
// tunnelRoute: "/monitoring",
// Automatically tree-shake Sentry logger statements to reduce bundle size
disableLogger: true,
})
function getAssetPrefix() {
// If not force enabled, but not production env, disable CDN
if (process.env.FORCE_ASSET_CDN !== '1' && process.env.VERCEL_ENV !== 'production') {
return undefined
}
// Force disable CDN
if (process.env.FORCE_ASSET_CDN === '-1') {
return undefined
}
// @ts-ignore
return `https://frontend-assets.supabase.com/${process.env.SITE_NAME}/${process.env.VERCEL_GIT_COMMIT_SHA.substring(0, 12)}`
}