[POC] W3C/OpenTelemetry Trace Context Propagation

[grdsdev]

⚠️ PROOF OF CONCEPT - DO NOT MERGE

This PR is a proof of concept to demonstrate W3C/OpenTelemetry trace context propagation in the Supabase JS SDK. It is not ready for production and should not be merged without further review, discussion, and refinement.

Summary

Implements automatic W3C/OpenTelemetry trace context propagation for HTTP requests to Supabase services (Auth, Storage, PostgREST, Functions). This enables end-to-end distributed tracing from client applications through Supabase services.

Key Design Principles:

• ✅ Security First: Only propagates to Supabase domains (*.supabase.co, *.supabase.in, localhost)
• ✅ OpenTelemetry Standard: Uses @opentelemetry/api as optional peer dependency
• ✅ HTTP Only: Applies to HTTP requests, not WebSocket connections
• ✅ Simple Configuration: Just two boolean flags
• ✅ Zero Breaking Changes: Enabled by default with opt-out available

Implementation

New Package: @supabase/tracing

Created shared package in packages/shared/tracing/ with:

• Trace context extraction from OpenTelemetry API (optional peer dependency)
• W3C traceparent header parsing and validation
• Target URL validation (Supabase domains only)
• Graceful fallback when OpenTelemetry is not available

Core Changes: @supabase/supabase-js

Enhanced fetchWithAuth in packages/core/supabase-js/src/lib/fetch.ts to inject trace headers:

• Centralized injection point for all HTTP libraries
• Extracts trace context once per request
• Validates target URLs before propagation
• Respects sampling decisions
• Never overwrites manually provided headers

Configuration

interface TracePropagationOptions {
  // Enable or disable trace propagation (default: true)
  enabled?: boolean

  // Respect upstream sampling decisions (default: true)
  respectSamplingDecision?: boolean
}

Usage Examples

Auto-Detection (Default)

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

const supabase = createClient('https://xyzcompany.supabase.co', 'public-anon-key')

const tracer = trace.getTracer('my-app')
await tracer.startActiveSpan('fetch-users', async (span) => {
  // This request automatically includes trace context headers
  const { data, error } = await supabase.from('users').select('*')
  span.end()
})

Disable Trace Propagation

const supabase = createClient('https://xyzcompany.supabase.co', 'public-anon-key', {
  tracePropagation: {
    enabled: false,
  },
})

Ignore Sampling Decisions

const supabase = createClient('https://xyzcompany.supabase.co', 'public-anon-key', {
  tracePropagation: {
    respectSamplingDecision: false, // Always propagate, ignore sampling
  },
})

Architecture

Centralized Injection Pattern:

User Code
  ↓
SupabaseClient
  ↓
Auth/Storage/PostgREST/Functions
  ↓
fetchWithAuth (SINGLE INJECTION POINT)
  ↓
HTTP Request with trace headers

Security Model:

• Trace context only propagated to trusted Supabase domains
• Automatic domain validation on every request
• No data leakage to third-party domains

Testing

• ✅ 58 unit tests in packages/shared/tracing/test/ (90%+ coverage)
• ✅ 9 integration tests in packages/core/supabase-js/test/unit/fetch.test.ts
• ✅ All tests passing
• ✅ Manual verification with real OpenTelemetry SDK in test-tracing/

What Still Needs Work

1. Documentation: Comprehensive docs for trace propagation configuration
2. Performance Impact: Measure any performance overhead
3. Security Review: Ensure no vulnerabilities introduced
4. Community Feedback: Get input on API design
5. Backend Support: Supabase services must accept and forward trace context
6. Examples: Real-world examples with observability backends (Jaeger, Datadog, etc.)

References

• W3C Trace Context Specification
• OpenTelemetry Context Propagation
• Linear Project SDK-578

Test Plan

# Build packages
npx nx build supabase-js

# Run tests
npx nx test tracing
npx nx test supabase-js

# Test with OpenTelemetry
cd test-tracing
npm install
node test-final.js

---

This is a POC for exploration and feedback. Do not merge without thorough review.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Central YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: 2cfd0095-8111-44c8-b7d2-e794cb4a3ab1

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[pkg-pr-new]

Open in StackBlitz

@supabase/auth-js

npm i https://pkg.pr.new/@supabase/auth-js@2163

@supabase/functions-js

npm i https://pkg.pr.new/@supabase/functions-js@2163

@supabase/postgrest-js

npm i https://pkg.pr.new/@supabase/postgrest-js@2163

@supabase/realtime-js

npm i https://pkg.pr.new/@supabase/realtime-js@2163

@supabase/storage-js

npm i https://pkg.pr.new/@supabase/storage-js@2163

@supabase/supabase-js

npm i https://pkg.pr.new/@supabase/supabase-js@2163

commit: f200bf5

[Ziinc]

Should keep 👍