Client-side tracing

Requirements#

• @supabase/supabase-js version 2.106.0 or later
• @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

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

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

Set up OpenTelemetry first#

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).

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

Enable trace propagation#

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
})

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#

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
})

Using a vendor tracing SDK#

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

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#

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. 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. Ensure your app calls provider.register() (or your vendor SDK's equivalent) before making requests.
• Your tracing SDK's propagator doesn't emit W3C traceparent. Sentry's propagator, for example, only emits it when propagateTraceparent: true is set. From version 2.112.3 the SDK logs a one-time warning naming the headers the propagator wrote — see Using a vendor tracing SDK.
• The upstream trace is not sampled (versions before 2.112.3). Older versions skip all trace headers when the upstream trace is not sampled. From 2.112.3, non-sampled requests still carry traceparent, so log correlation keeps working by default. Set respectSamplingDecision: false to always send the full trace context.
• 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.