TracePropagationOptions

import type { TracePropagationOptions } from "https://esm.sh/@supabase/supabase-js@2.106.2/dist/index.d.mts";

Configuration options for trace context propagation.

Enables distributed tracing across Supabase services using W3C Trace Context and OpenTelemetry standards. When enabled, the SDK automatically attaches trace context headers (traceparent, tracestate, baggage) to outgoing requests to Supabase domains. The resulting trace_id appears in API Gateway and Edge Function logs, so logs forwarded through Log Drains can be correlated back to the originating client-side span.

Requires @opentelemetry/api to be installed in the consuming application. If it is not installed, or there is no active context at request time, propagation silently no-ops.

@example

Enable with defaults

const supabase = createClient(url, key, {
  tracePropagation: { enabled: true },
})

interface TracePropagationOptions {

enabled?: boolean;

respectSamplingDecision?: boolean;

}

§Properties

enabled?: boolean

[src]

Enable trace propagation. Disabled by default.

When enabled, automatically detects and propagates active trace context from the OpenTelemetry API to outgoing Supabase requests. Trace context is only propagated to Supabase domains (*.supabase.co, *.supabase.in, localhost) for security — third-party hosts never receive trace headers.

@example

const supabase = createClient(url, key, {
  tracePropagation: { enabled: true },
})

respectSamplingDecision?: boolean

[src]

Respect upstream sampling decisions.

When true (the default), trace context is not propagated if the upstream trace indicates non-sampling (sampled flag = 0 in the traceparent header). This avoids overhead when traces are being recorded but dropped.

Set to false to always propagate, regardless of the sampling decision — useful when you want every Supabase request tagged with a trace_id for log correlation, even if the trace itself will not be exported.

@example

Always propagate, ignore sampling

const supabase = createClient(url, key, {
  tracePropagation: { enabled: true, respectSamplingDecision: false },
})