---
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'
tags:
  - logs
  - observability
categories:
  - product
---
`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).