Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

blog(www): connect client traces to your logs (#49200)

Anacb9394246bc1
diff --git a/apps/www/_blog/2026-08-18-connect-client-traces-to-your-logs.mdx b/apps/www/_blog/2026-08-18-connect-client-traces-to-your-logs.mdx
new file mode 100644
index 00000000000..ea22c09fae3
--- /dev/null
+++ b/apps/www/_blog/2026-08-18-connect-client-traces-to-your-logs.mdx
@@ -0,0 +1,93 @@
+---
+title: 'Connect client traces to your logs'
+description: 'supabase-js now propagates W3C Trace Context to Supabase, so a client trace and the matching Supabase log share one trace_id.'
+author: katerina_skroumpelou, steven_eubank
+date: '2026-08-18'
+categories:
+ - product
+tags:
+ - logs
+ - observability
+imgSocial: 'connect-client-traces-to-your-logs/og.png'
+imgThumb: 'connect-client-traces-to-your-logs/thumb.png'
+toc_depth: 2
+---
+
+`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](https://supabase.com/docs/guides/monitoring-and-debugging/client-side-tracing) 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:
+
+```typescript
+import '@supabase/supabase-js/tracing'
+import { createClient } from '@supabase/supabase-js'
+
+const supabase = createClient(SUPABASE_URL, SUPABASE_KEY, {
+ tracePropagation: true,
+})
+```
+
+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:
+
+```typescript
+await tracer.startActiveSpan('load-dashboard', async (span) => {
+ const { data } = await supabase.from('profiles').select('*')
+ span.end()
+})
+```
+
+If your sampler drops most traces and you still want Supabase requests carried through, override the sampling decision:
+
+```typescript
+import '@supabase/supabase-js/tracing'
+
+const supabase = createClient(SUPABASE_URL, SUPABASE_KEY, {
+ tracePropagation: { enabled: true, respectSamplingDecision: false },
+})
+```
+
+## 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](https://supabase.com/docs/guides/monitoring-and-debugging/client-side-tracing).
diff --git a/apps/www/public/images/blog/connect-client-traces-to-your-logs/og.png b/apps/www/public/images/blog/connect-client-traces-to-your-logs/og.png
new file mode 100644
index 00000000000..aa4f84f09d0
Binary files /dev/null and b/apps/www/public/images/blog/connect-client-traces-to-your-logs/og.png differ
diff --git a/apps/www/public/images/blog/connect-client-traces-to-your-logs/thumb.png b/apps/www/public/images/blog/connect-client-traces-to-your-logs/thumb.png
new file mode 100644
index 00000000000..b9423c03d36
Binary files /dev/null and b/apps/www/public/images/blog/connect-client-traces-to-your-logs/thumb.png differ