The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
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.mdxnew file mode 100644index 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.pngnew file mode 100644index 00000000000..aa4f84f09d0Binary files /dev/null and b/apps/www/public/images/blog/connect-client-traces-to-your-logs/og.png differdiff --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.pngnew file mode 100644index 00000000000..b9423c03d36Binary files /dev/null and b/apps/www/public/images/blog/connect-client-traces-to-your-logs/thumb.png differ