Sentry 集成

你可以使用 Sentry 来监控从 Supabase JavaScript 客户端抛出的错误。Sentry JavaScript SDK 已经直接内置了对 Supabase 的支持。

🌐 You can use Sentry to monitor errors thrown from a Supabase JavaScript client. Support for Supabase is built directly into the Sentry JavaScript SDK.

该集成工具会对通过 supabase-js 发出的数据库查询和身份验证调用进行处理，创建用于性能监控的跨度并捕捉错误。它支持浏览器、Node 和边缘环境。

🌐 The integration instruments database queries and authentication calls made through supabase-js, creating spans for performance monitoring and capturing errors. It supports browser, Node, and edge environments.

使用 #

🌐 Use

有两种方法可以启用集成。两种方法都需要一个已初始化的 Supabase 客户端实例。

🌐 There are two ways to enable the integration. Both take an initialized Supabase client instance.

1
import * as Sentry from '@sentry/browser'
2
import { createClient } from '@supabase/supabase-js'
3
4
const supabaseClient = createClient(SUPABASE_URL, SUPABASE_KEY)
5
6
Sentry.init({
7
  dsn: SENTRY_DSN,
8
  tracesSampleRate: 1.0,
9
  integrations: [
10
    Sentry.browserTracingIntegration(),
11
    Sentry.supabaseIntegration({ supabaseClient }),
12
  ],
13
})

去重跨度 #

🌐 Deduplicating spans

Sentry 的 HTTP 和 Fetch 跟踪集成在 Node 和 Next.js SDK 中默认启用，因此底层的 Supabase REST 调用除了 Supabase 集成产生的 db spans 外，还会被追踪为 http.client spans。这个清理是可选的：如果你不想同时看到两者，可以在其他集成中跳过 Supabase REST 请求。

🌐 Sentry's HTTP and Fetch tracing integrations are enabled by default in the Node and Next.js SDKs, so the underlying Supabase REST calls are traced as http.client spans in addition to the db spans from the Supabase integration. This is optional cleanup: if you'd rather not see both, skip the Supabase REST requests in your other integration.

1
import * as Sentry from '@sentry/browser'
2
import { createClient } from '@supabase/supabase-js'
3
4
const supabaseClient = createClient(SUPABASE_URL, SUPABASE_KEY)
5
6
Sentry.init({
7
  dsn: SENTRY_DSN,
8
  tracesSampleRate: 1.0,
9
  integrations: [
10
    Sentry.supabaseIntegration({ supabaseClient }),
11
12
    // @sentry/browser
13
    Sentry.browserTracingIntegration({
14
      shouldCreateSpanForRequest: (url) => {
15
        return !url.startsWith(`${SUPABASE_URL}/rest`)
16
      },
17
    }),
18
19
    // or @sentry/node (supabase-js uses fetch, so filter the Fetch integration)
20
    Sentry.nativeNodeFetchIntegration({
21
      ignoreOutgoingRequests: (url) => {
22
        return url.startsWith(`${SUPABASE_URL}/rest`)
23
      },
24
    }),
25
26
    // or @sentry/nextjs for Proxy & Edge Functions
27
    Sentry.winterCGFetchIntegration({
28
      breadcrumbs: true,
29
      shouldCreateSpanForRequest: (url) => {
30
        return !url.startsWith(`${SUPABASE_URL}/rest`)
31
      },
32
    }),
33
  ],
34
})

Next.js 的配置 #

🌐 Configuration for Next.js

Next.js 在浏览器、服务器和边缘运行时都会运行 Sentry，并且像 @supabase/ssr 这样的鉴权感知设置会为每个请求创建一个 Supabase 客户端。由于 instrumentSupabaseClient 会对每个运行时的数据库调用和每个客户端实例的鉴权调用进行修补，所以应该在你每个客户端工厂里调用它，而不是只在一个共享实例上调用。

🌐 Next.js runs Sentry across browser, server, and edge runtimes, and auth-aware setups (like @supabase/ssr) create a Supabase client per request. Since instrumentSupabaseClient patches database calls per runtime and auth calls per client instance, call it inside each of your client factories rather than on a single shared instance.

1. 通过 Sentry Next.js 向导 来设置基础的 Sentry 配置。
2. 在每个工厂中添加 Sentry.instrumentSupabaseClient。例如，带有 @supabase/ssr 的服务器客户端：

1
import * as Sentry from '@sentry/nextjs'
2
import { createServerClient } from '@supabase/ssr'
3
4
export async function createClient() {
5
  const client = createServerClient(/* your usual URL, key, and cookie config */)
6
7
  Sentry.instrumentSupabaseClient(client)
8
  return client
9
}

3. 在你的浏览器客户端使用 (createBrowserClient) 和中间件客户端应用同样的方法，这样每个运行时都会被覆盖。
4. 要包括查询过滤器和变更体，请在每个运行时的 Sentry 配置中启用 dataCollection: { userInfo: true }，或者在调用位置传入 Sentry.instrumentSupabaseClient(client, { sendOperationData: true })。
5. 构建并运行你的应用（npm run build && npm run start）。现在，Supabase 查询会以 db 跨度的形式出现在你的 Sentry 跟踪中。