From 99e66029c8d3cac8bacdf0bb9871a6207848d842 Mon Sep 17 00:00:00 2001 From: Katerina Skroumpelou Date: Mon, 3 Aug 2026 10:39:14 +0300 Subject: [PATCH] docs: document the supabase-js /tracing opt-in subpath (#48529) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## What kind of change does this PR introduce? Documentation update for `apps/docs/content/guides/monitoring-and-debugging/client-side-tracing.mdx`. As of `@supabase/supabase-js` 2.112.0 (supabase/supabase-js#2583), the OpenTelemetry integration moved out of the main bundle into an opt-in subpath. Enabling trace propagation now takes two steps: `import '@supabase/supabase-js/tracing'` at the application entry point, plus the existing `tracePropagation: true` client option. Guide changes: - Requirements: documents the subpath import (2.112.0+), the loud-resolution behavior when `@opentelemetry/api` is missing, the one-time warning when the runtime isn't loaded, the version note for 2.106.0–2.111.x (no import there), and that the CDN/UMD build does not support tracing. - Both code samples now start with the subpath import. - Troubleshooting: new first check (runtime not loaded → one-time console warning), updated `@opentelemetry/api` semantics per version, new CDN/UMD entry. The JS reference (`typeSpec.json`) is regenerated automatically by the docs-update pipeline from the supabase-js spec and is not touched here. **Timing note:** merge once 2.112.0 is promoted to `latest` (currently on `beta`/`canary`) so the guide doesn't get ahead of the stable release. ## Summary by CodeRabbit * **Documentation** * Updated client-side tracing guidance for `@supabase/supabase-js` 2.112.0 and later. * Added setup examples for the required one-time opt-in import. * Clarified behavior when tracing dependencies are missing and documented CDN usage limitations. * Expanded troubleshooting guidance for runtime loading, module resolution, and UMD usage. --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- .../client-side-tracing.mdx | 28 ++++++++++++++++--- supa-mdx-lint/Rule003Spelling.toml | 3 ++ 2 files changed, 27 insertions(+), 4 deletions(-) diff --git a/apps/docs/content/guides/monitoring-and-debugging/client-side-tracing.mdx b/apps/docs/content/guides/monitoring-and-debugging/client-side-tracing.mdx index 49fd270ab24..901017e3b29 100644 --- a/apps/docs/content/guides/monitoring-and-debugging/client-side-tracing.mdx +++ b/apps/docs/content/guides/monitoring-and-debugging/client-side-tracing.mdx @@ -14,7 +14,21 @@ Because the headers follow the W3C standard, any compliant tracing SDK (OpenTele - `@opentelemetry/api` available at runtime — either installed directly or pulled in as a transitive dependency of your tracing SDK - A tracing SDK that registers a W3C-compliant propagator with the OpenTelemetry API -If `@opentelemetry/api` is not installed, or there is no active trace context at request time, the SDK silently no-ops. + + +As of `@supabase/supabase-js` version `2.112.0`, the OpenTelemetry integration lives in an opt-in subpath that you load once at your application entry point: + +```ts +import '@supabase/supabase-js/tracing' +``` + +The main bundle contains no OpenTelemetry code — this import is what wires it up. The subpath imports `@opentelemetry/api` directly, so your bundler includes it and module resolution fails loudly if it isn't installed. If `tracePropagation` is enabled without this import, the SDK logs a one-time warning and sends requests without trace headers. + +On versions `2.106.0`–`2.111.x`, the subpath doesn't exist — don't add the import there. Those versions load `@opentelemetry/api` dynamically and silently no-op when it's missing. + + + +Trace propagation isn't available through the CDN (UMD) build — there's no way to load the tracing runtime there. ## Set up OpenTelemetry first @@ -24,9 +38,11 @@ The Supabase SDK only takes care of propagating the trace context that's already ## Enable trace propagation -Trace propagation is opt-in. Pass `tracePropagation: true` when creating the client: +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: ```ts +import '@supabase/supabase-js/tracing' + import { trace } from '@opentelemetry/api' import { createClient } from '@supabase/supabase-js' @@ -50,6 +66,8 @@ For security, trace headers are only attached to requests targeting Supabase dom Pass an object instead of `true` for fine-grained control: ```ts +import '@supabase/supabase-js/tracing' + const supabase = createClient(SUPABASE_URL, SUPABASE_KEY, { tracePropagation: { enabled: true, @@ -81,10 +99,12 @@ Many tracing SDKs are built on top of OpenTelemetry. They work with this guide a ## Troubleshooting -The SDK silently no-ops 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: +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: +- **The tracing runtime isn't loaded** (version `2.112.0` and later). `tracePropagation` is enabled but your entry point never imports `@supabase/supabase-js/tracing`. The SDK logs a one-time console warning and sends requests without trace headers — look for that warning in your console. - **No active span at request time.** The SDK reads the _current_ context. If `supabase.from(...)` is called outside `tracer.startActiveSpan(...)` (or equivalent), there's nothing to propagate. Wrap the call in a span or use OpenTelemetry's automatic instrumentation. -- **`@opentelemetry/api` is not installed** in the app making the request. The SDK imports it dynamically and no-ops if it's missing. +- **`@opentelemetry/api` is not installed** in the app making the request. On `2.112.0` and later the tracing subpath imports it directly, so a missing package surfaces as a module resolution error. On `2.106.0`–`2.111.x` it's loaded dynamically and the SDK silently no-ops. - **No `TracerProvider` registered.** `@opentelemetry/api` defaults to a noop provider that produces non-recorded spans. Make sure your app calls `provider.register()` (or your vendor SDK's equivalent) before making requests. - **The upstream trace is not sampled.** By default the SDK respects upstream sampling decisions. Set `respectSamplingDecision: false` to propagate every request regardless of sampling. - **You're calling a non-Supabase host through a custom `fetch`.** Trace headers are only attached to Supabase domains (`*.supabase.co`, `*.supabase.in`, `localhost`). +- **You're using the CDN (UMD) build.** Trace propagation isn't available there — the tracing runtime can't be loaded from a script tag. diff --git a/supa-mdx-lint/Rule003Spelling.toml b/supa-mdx-lint/Rule003Spelling.toml index 2d9bd6b8d3f..2a830738c95 100644 --- a/supa-mdx-lint/Rule003Spelling.toml +++ b/supa-mdx-lint/Rule003Spelling.toml @@ -35,6 +35,7 @@ allow_list = [ "BootFailure", "[Bb]reakpoints?", "[Bb]uilt-ins?", + "[Bb]undlers?", "[Cc]atalogs?", "[Cc]hangelogs?", "CircleCI", @@ -110,6 +111,7 @@ allow_list = [ "[Mm]ultipart", "[Mm]ultithreading", "[Nn]amespace(d|s)?", + "[Nn]o-ops?", "[Nn]onces?", "[Nn]ullable", "[Oo]ffboarding", @@ -149,6 +151,7 @@ allow_list = [ "[Ss]ubdomains?", "[Ss]ubfolders?", "[Ss]ubmodules?", + "[Ss]ubpaths?", "[Ss]wappiness", "TerminationRequested", "[Tt]imebox(ed)?",