将客户端追踪关联至日志
内容提要
supabase-js 现已支持 W3C Trace Context 传播，启用后可将客户端 trace_id 关联至 Supabase 日志，便于跨浏览器与后端调试。需自行配置 OpenTelemetry，通过导入 tracing 模块并设置 tracePropagation 启用。支持 Log Drains 集成，主包不含 OpenTelemetry 代码，无额外负担。限制：无 CDN 支持，仅限 Supabase 域名，需活动 span，默认遵循采样决策。
延伸解读
调试效率提升
启用 tracePropagation 后，浏览器端与后端日志通过同一 trace_id 关联，无需手动对齐时间戳。这能显著减少跨端调试的复杂度，尤其适合排查前端发起请求后后端响应缓慢的问题。
集成注意事项
需自行配置 OpenTelemetry，并确保 @opentelemetry/api 可解析。主包不含 OpenTelemetry 代码，需在入口导入 tracing 模块。注意无 CDN 支持，且仅对 Supabase 域名附加头信息。
采样决策影响
默认遵循采样决策，未采样的 trace 不会发送头信息。若需强制传播，可设置 respectSamplingDecision: false。这会影响数据量，需权衡可观测性与成本。
Q&A
supabase-js 如何将客户端追踪关联至日志？
通过启用 W3C Trace Context 传播，supabase-js 会向 Supabase 域名发送 traceparent、tracestate 和 baggage 三个标准头，Supabase 读取后会在日志中标记相同的 trace_id，从而将客户端请求与后端日志关联起来。
如何在 supabase-js 中启用 trace 传播？
首先需要自行配置 OpenTelemetry，安装 SDK 并注册 TracerProvider。然后在应用入口导入 '@supabase/supabase-js/tracing'，并在创建客户端时设置 tracePropagation: true。
启用 trace 传播后，如何确保请求被追踪？
需要确保在调用 Supabase 时有一个活动的 span，例如使用 tracer.startActiveSpan 包裹请求。如果没有活动 span 或未注册 TracerProvider，SDK 会静默无操作。
supabase-js 的 trace 传播支持哪些日志源？
目前支持 API Gateway 和 Edge Function 日志，这些日志会携带 trace_id。
trace 传播是否支持 CDN 或 UMD 方式？
不支持。tracing 运行时无法通过 script 标签加载，因此 CDN 构建中不可用。
trace 传播是否会增加包体积？
不会。主包不包含 OpenTelemetry 代码，只有显式导入 '@supabase/supabase-js/tracing' 时才会引入相关依赖，因此默认无额外负担。
如何让未采样的 trace 也发送请求头？
在创建客户端时设置 tracePropagation: { enabled: true, respectSamplingDecision: false }，即可忽略采样决策，强制发送 trace 头。
trace 传播支持哪些语言？
目前支持 supabase-js、Swift、Flutter 和 Python。
