Connect client traces to your logs

supabase-js now propagates W3C Trace Context to Supabase. Turn it on and the trace_id from your client flows through Supabase's API Gateway and Edge Function logs, so you can follow one request from the browser into your backend logs.

Say a frontend trace shows a slow request leaving the browser, and a Supabase log shows the matching request on the server. Up to now nothing connected the two: the SDK made the call, Supabase logged it, and the two records lived in separate systems with no shared identifier. Debugging across that boundary meant lining up timestamps by hand.

Now, when tracePropagation is enabled, the SDK attaches three standard headers to requests aimed at Supabase domains:

• traceparent
• tracestate
• baggage

Supabase reads the incoming trace context and stamps the same trace_id onto the logs it generates. Any W3C-compliant tracer (OpenTelemetry, Sentry, Datadog, Honeycomb, Grafana) picks the trace back up on the server side.

How to set it up#

This walkthrough covers supabase-js. Trace propagation is also available in Swift, Flutter, and Python; see the docs for per-language setup and the current list.

The SDK doesn't configure OpenTelemetry for you. You bring your own tracer, then tell the client to propagate.

First, set up OpenTelemetry as you normally would: install an SDK (@opentelemetry/sdk-trace-node for Node, @opentelemetry/sdk-trace-web for the browser), add an exporter, and register a TracerProvider globally. The tracing runtime needs @opentelemetry/api resolvable in your app, install it directly if your package manager doesn't pull it in alongside the SDK.

Then load the tracing runtime once at your application entry point, and enable propagation on the client:

The main bundle ships no OpenTelemetry code, that first import is what wires it up.

Wrap your Supabase calls in an active span so there's a trace to propagate:

If your sampler drops most traces and you still want Supabase requests carried through, override the sampling decision:

Get more value from your Log Drains#

Log Drains forward your Supabase logs to an external backend. With trace propagation on, every drained log carries the same trace_id as your client and server traces, so you can join them in the tracing UI you already run.

When you do so, the browser span in Sentry and the matching API Gateway log forwarded to Datadog line up under one trace_id. For self-hosted setups running an OpenTelemetry collector, it's the same join on infrastructure you control.

Nothing to pay for if you don't use it#

The OpenTelemetry integration lives behind its own entry point, so the main supabase-js bundle contains zero OpenTelemetry code. Nothing is added to your bundle, and nothing to resolve at build time, unless you opt in. That keeps React Native/Hermes, Metro, and edge bundlers unaffected, and it means that when you do opt in, your bundler can actually see the dependency and include it.

Current limitations#

• No CDN/UMD support. The tracing runtime can't be loaded from a script tag, so trace propagation isn't available in the CDN build.
• Available in supabase-js, Swift, Flutter, and Python.
• Supabase domains only. Headers are attached to your project host, *.supabase.co, *.supabase.in, and local dev hosts (localhost, 127.0.0.1, [::1]), never to third-party hosts, even through a custom fetch.
• API Gateway and Edge Function logs. Those are the log sources that pick up the trace_id today.
• Needs a real span. With no active span at request time, or no registered TracerProvider (the API defaults to a noop provider), there is nothing to propagate and the SDK no-ops silently.
• Sampling is respected by default. Unsampled traces send no headers unless you set respectSamplingDecision: false.

Getting started#

Trace propagation is available now in supabase-js. Add import '@supabase/supabase-js/tracing' at your entry point, turn on tracePropagation, point your existing tracer at it, and your client traces will line up with your Supabase logs.

Already using tracePropagation from an earlier release? Upgrade to supabase-js 2.112.0 or later and add the import '@supabase/supabase-js/tracing' line. Versions 2.106.0 through 2.111.x silently sent no trace headers in bundled apps, so the upgrade is what actually fixes propagation, not just the import.

Full setup, including the sampling options, is in the client-side tracing guide.