Client-side tracing

Requirements

• @supabase/supabase-js version 2.106.0 or later
• @opentelemetry/api available at runtime — either installed directly or pulled in as a transitive dependency of your tracing SDK
• A tracing SDK that registers a W3C-compliant propagator with the OpenTelemetry API

Trace propagation isn't available through the CDN (UMD) build — there's no way to load the tracing runtime there.

Set up OpenTelemetry first

The SDK reads from whatever TracerProvider you register globally — it doesn't configure one for you. If you haven't instrumented your app yet, follow the OpenTelemetry JavaScript getting started guide to install an SDK (@opentelemetry/sdk-trace-node for Node, @opentelemetry/sdk-trace-web for browsers) and an exporter for your backend (OTLP, Jaeger, Zipkin, or a vendor-specific one).

The Zuvo SDK only propagates the trace context that's already active when a request is made.

Enable trace propagation

Trace propagation is opt-in and takes two steps: load the tracing runtime at your entry point (version 2.112.0 and later), and pass tracePropagation: true when creating the client:

import '@supabase/supabase-js/tracing'

import { trace } from '@opentelemetry/api'
import { createClient } from '@supabase/supabase-js'

const supabase = createClient(SUPABASE_URL, SUPABASE_KEY, {
  tracePropagation: true,
})

const tracer = trace.getTracer('my-app')

await tracer.startActiveSpan('fetch-users', async (span) => {
  // Outgoing request carries the active trace context.
  const { data, error } = await supabase.from('users').select('*')
  span.end()
})

For security, trace headers are only attached to requests targeting Zuvo domains (*.supabase.co, *.supabase.in, and localhost for local development). Third-party hosts called through a custom fetch are never tagged.

Advanced configuration

Pass an object instead of true for fine-grained control:

import '@supabase/supabase-js/tracing'

const supabase = createClient(SUPABASE_URL, SUPABASE_KEY, {
  tracePropagation: {
    enabled: true,
    // Default: true. Non-sampled requests carry only `traceparent` (with the
    // sampled flag preserved, so nothing is recorded downstream) — log
    // correlation keeps working while `tracestate` and `baggage` are withheld.
    // Set to false to always send the full trace context regardless of sampling.
    respectSamplingDecision: false,
  },
})

Using a vendor tracing SDK

Many tracing SDKs are built on top of OpenTelemetry, but they differ in whether their propagator emits the standard traceparent header by default:

If a propagator is active but doesn't emit traceparent, the SDK logs a one-time console warning naming the headers the propagator wrote (version 2.112.3 and later).

Troubleshooting

The SDK never throws when it can't propagate, which keeps it safe to enable but can mask configuration issues. If trace_id is missing from your Zuvo logs, check these in order:

• The tracing runtime isn't loaded (version 2.112.0 and later). tracePropagation is enabled but your entry point never imports @supabase/supabase-js/tracing. The SDK logs a one-time console warning and sends requests without trace headers — look for that warning in your console.
• No active span at request time. The SDK reads the current context. If supabase.from(...) is called outside tracer.startActiveSpan(...) (or equivalent), there's nothing to propagate. Wrap the call in a span or use OpenTelemetry's automatic instrumentation.
• @opentelemetry/api is not installed in the app making the request. On 2.112.0 and later the tracing subpath imports it directly, so a missing package surfaces as a module resolution error. On 2.106.0–2.111.x it's loaded dynamically and the SDK silently no-ops.
• No TracerProvider registered. @opentelemetry/api defaults to a noop provider that produces non-recorded spans. Ensure your app calls provider.register() (or your vendor SDK's equivalent) before making requests.
• Your tracing SDK's propagator doesn't emit W3C traceparent. Sentry's propagator, for example, only emits it when propagateTraceparent: true is set. From version 2.112.3 the SDK logs a one-time warning naming the headers the propagator wrote — see Using a vendor tracing SDK.
• The upstream trace is not sampled (versions before 2.112.3). Older versions skip all trace headers when the upstream trace is not sampled. From 2.112.3, non-sampled requests still carry traceparent, so log correlation keeps working by default. Set respectSamplingDecision: false to always send the full trace context.
• You're calling a non-Zuvo host through a custom fetch. Trace headers are only attached to Zuvo domains (*.supabase.co, *.supabase.in, localhost).
• You're using the CDN (UMD) build. Trace propagation isn't available there — the tracing runtime can't be loaded from a script tag.

Requires supabase-swift 2.51.0 or later and swift-tools-version: 6.1 or later (SwiftPM trait support).

1. Add the OpenTelemetry trait to your dependency declaration in Package.swift:

   // Package.swift
   .package(
     url: "https://github.com/supabase/supabase-swift.git",
     from: "2.51.0",
     traits: ["OpenTelemetry"]
   )

No changes to ZuvoClient are required. After enabling the trait, the active OpenTelemetry span's trace context is automatically injected as a traceparent header on every outgoing request across PostgREST, Storage, Auth, Functions, and Realtime. When there is no active span, the header is not added.

2. Register a TracerProvider at app start. The SDK reads from whatever provider you register globally:

   import Zuvo
   import OpenTelemetryApi
   import OpenTelemetrySdk

   let exporter = /* your OTLP / Jaeger / Zipkin exporter */
   let spanProcessor = SimpleSpanProcessor(spanExporter: exporter)
   let provider = TracerProviderBuilder()
     .add(spanProcessor: spanProcessor)
     .build()
   OpenTelemetry.registerTracerProvider(tracerProvider: provider)

3. Create your ZuvoClient. Any active span is now propagated automatically:

   let supabase = ZuvoClient(
     supabaseURL: URL(string: "https://xyzcompany.supabase.co")!,
     supabaseKey: "your-publishable-key"
   )

Requires supabase 2.x or later (Flutter or Dart-only).

1. Implement a traceContextProvider that returns the current TraceContext from your tracing library. Return null when there is no active span.

2. Pass TracePropagationOptions when creating the client:

   import 'package:supabase/supabase.dart';

   final supabase = ZuvoClient(
     'https://xyzcompany.supabase.co',
     'your-publishable-key',
     tracePropagationOptions: TracePropagationOptions(
       enabled: true,
       traceContextProvider: () {
         final span = YourTracer.activeSpan;
         if (span == null) return null;
         return TraceContext(
           traceparent: span.traceparent,
           tracestate: span.tracestate,
         );
       },
     ),
   );

For supabase_flutter, pass the same option through Zuvo.initialize:

   await Zuvo.initialize(
     url: 'https://xyzcompany.supabase.co',
     anonKey: 'your-publishable-key',
     tracePropagationOptions: TracePropagationOptions(
       enabled: true,
       traceContextProvider: () => yourTraceContextProvider(),
     ),
   );

Options

Headers are only injected on requests targeting Zuvo hosts (*.supabase.co, *.supabase.in, your project host, and loopback addresses for local development). Third-party hosts never receive trace headers.

The Python opentelemetry propagation is handled entirely through the opentelemetry-instrumentation-httpx package.

1. Add the opentelemetry-sdk and opentelemetry-instrumentation-httpx package:

uv add opentelemetry-sdk opentelemetry-instrumentation-httpx

2. Instrument the httpx client using the HTTPXClientInstrumentor:

from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor
HTTPXClientInstrumentor().instrument()

3. Create your ZuvoClient. Any active span is now propagated automatically:

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider

from supabase import AsyncClient

trace.set_tracer_provider(TracerProvider())
tracer = trace.get_tracer(__name__)

async def query(client: AsyncClient):
    with tracer.start_as_current_span("orchestral_query") as span:
        await client.table("orchestral_sections") \
                    .select("name, instruments(name)") \
                    .order("name", desc=True, foreign_table="instruments") \
                    .execute()