客户端跟踪

要求 #

🌐 Requirements

• @supabase/supabase-js 版本 2.106.0 或更高
• @opentelemetry/api 在运行时可用——可以直接安装，也可以作为你的追踪 SDK 的传递依赖被引入
• 一个追踪 SDK，它在 OpenTelemetry API 中注册了一个符合 W3C 标准的传播器

1
import '@supabase/supabase-js/tracing'

通过 CDN (UMD) 构建无法进行追踪传播——那里没办法加载追踪运行时。

🌐 Trace propagation isn't available through the CDN (UMD) build — there's no way to load the tracing runtime there.

先设置 OpenTelemetry #

🌐 Set up OpenTelemetry first

SDK 会读取你全局注册的任何 TracerProvider —— 它不会为你配置一个。如果你还没有为你的应用添加监控，可以按照 OpenTelemetry JavaScript 入门指南 安装 SDK（Node 用 @opentelemetry/sdk-trace-node，浏览器用 @opentelemetry/sdk-trace-web）以及你的后台导出器（OTLP、Jaeger、Zipkin 或特定厂商的导出器）。

🌐 The SDK reads from whatever TracerProvider you register globally — it doesn't configure one for you. If you haven't instrumented your app yet, follow the OpenTelemetry JavaScript getting started guide to install an SDK (@opentelemetry/sdk-trace-node for Node, @opentelemetry/sdk-trace-web for browsers) and an exporter for your backend (OTLP, Jaeger, Zipkin, or a vendor-specific one).

Supabase SDK 只会传递在发出请求时已经激活的跟踪上下文。

🌐 The Supabase SDK only propagates the trace context that's already active when a request is made.

启用跟踪传播 #

🌐 Enable trace propagation

追踪传播是可选的，需要两个步骤：在入口点加载追踪运行时（版本 2.112.0 及更高），并在创建客户端时传入 tracePropagation: true：

🌐 Trace propagation is opt-in and takes two steps: load the tracing runtime at your entry point (version 2.112.0 and later), and pass tracePropagation: true when creating the client:

1
import '@supabase/supabase-js/tracing'
2
3
import { trace } from '@opentelemetry/api'
4
import { createClient } from '@supabase/supabase-js'
5
6
const supabase = createClient(SUPABASE_URL, SUPABASE_KEY, {
7
  tracePropagation: true,
8
})
9
10
const tracer = trace.getTracer('my-app')
11
12
await tracer.startActiveSpan('fetch-users', async (span) => {
13
  // Outgoing request carries the active trace context.
14
  const { data, error } = await supabase.from('users').select('*')
15
  span.end()
16
})

为了安全起见，追踪头只会附加到针对 Supabase 域的请求（在本地开发中是 *.supabase.co、*.supabase.in 和 localhost）。通过自定义 fetch 调用的第三方主机从不被标记。

🌐 For security, trace headers are only attached to requests targeting Supabase domains (*.supabase.co, *.supabase.in, and localhost for local development). Third-party hosts called through a custom fetch are never tagged.

高级设置 #

🌐 Advanced configuration

传入一个对象而不是 true 来进行更精细的控制：

🌐 Pass an object instead of true for fine-grained control:

1
import '@supabase/supabase-js/tracing'
2
3
const supabase = createClient(SUPABASE_URL, SUPABASE_KEY, {
4
  tracePropagation: {
5
    enabled: true,
6
    // Default: true. Non-sampled requests carry only `traceparent` (with the
7
    // sampled flag preserved, so nothing is recorded downstream) — log
8
    // correlation keeps working while `tracestate` and `baggage` are withheld.
9
    // Set to false to always send the full trace context regardless of sampling.
10
    respectSamplingDecision: false,
11
  },
12
})

使用供应商追踪 SDK #

🌐 Using a vendor tracing SDK

许多追踪 SDK 都是建立在 OpenTelemetry 之上的，但它们在 propagator 是否默认发送标准的 traceparent 头部上有所不同：

🌐 Many tracing SDKs are built on top of OpenTelemetry, but they differ in whether their propagator emits the standard traceparent header by default:

如果一个传播器处于激活状态但没有发送 traceparent，SDK 会在控制台记录一次性警告，列出传播器写入的头信息（从 2.112.3 版本开始）。

🌐 If a propagator is active but doesn't emit traceparent, the SDK logs a one-time console warning naming the headers the propagator wrote (version 2.112.3 and later).

故障排除 #

🌐 Troubleshooting

当 SDK 无法传播时，它从不抛出异常，这让启用它很安全，但可能掩盖配置问题。如果你的 Supabase 日志中缺少 trace_id，请按以下顺序检查：

🌐 The SDK never throws when it can't propagate, which keeps it safe to enable but can mask configuration issues. If trace_id is missing from your Supabase logs, check these in order:

• 追踪运行时未加载（版本 2.112.0 及更高）。tracePropagation 已启用，但你的入口点从未导入 @supabase/supabase-js/tracing。SDK 会在控制台记录一次性警告，并发送不带追踪头的请求——在控制台中查找该警告。
• 请求时没有活动的 span。 SDK 会读取_当前_上下文。如果 supabase.from(...) 在 tracer.startActiveSpan(...)（或等效操作）之外被调用，就没有内容可以传播。把调用封装在一个 span 里，或者使用 OpenTelemetry 的自动化监控。
• @opentelemetry/api 没有安装 在发起请求的应用中。在 2.112.0 及更高版本中，跟踪子路径会直接导入它，因此缺少的包会以模块解析错误的形式出现。在 2.106.0–2.111.x 之间，它是动态加载的，SDK 会悄悄地不执行任何操作。
• 没有注册 TracerProvider。 @opentelemetry/api 默认为一个不会记录的空操作提供者。在发起请求前，确保你的应用调用了 provider.register()（或你的供应商 SDK 的等效方法）。
• 你的追踪 SDK 的传播器不会发送 W3C traceparent。 例如，Sentry 的传播器只有在设置了 propagateTraceparent: true 时才会发送。从 2.112.3 版本开始，SDK 会记录一次性警告，列出传播器写入的头信息——详见 使用厂商追踪 SDK。
• 上游追踪未被采样（2.112.3 之前的版本）。旧版本在上游追踪未被采样时会跳过所有追踪头。从 2.112.3 开始，未采样的请求仍然会携带 traceparent，因此日志关联默认依然有效。将 respectSamplingDecision: false 设置为始终发送完整的追踪上下文。
• 你正在通过自定义 fetch 调用非 Supabase 主机。 跟踪头只会附加到 Supabase 域名（*.supabase.co、*.supabase.in、localhost）。
• 你正在使用 CDN (UMD) 版本。 追踪传播在这里不可用——追踪运行时无法从脚本标签加载。