From 31d1a639c0aa386b61732598fa782e39dbaa621d Mon Sep 17 00:00:00 2001 From: Guilherme Souza Date: Tue, 4 Aug 2026 09:58:13 -0300 Subject: [PATCH] docs: Update SDK references from recent releases (#47830) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary Updates SDK reference docs and the client-side tracing guide based on recent releases across all six Supabase SDKs. ## SDKs analyzed | SDK | Repo | Latest commit | Latest tag | |-----|------|--------------|------------| | js | supabase/supabase-js | `e4e8864` | v3.0.0-next.29 | | dart | supabase/supabase-flutter | `c3e3602` | yet_another_json_isolate-v2.1.1 | | py | supabase/supabase-py | `6570638` | v3.0.0a1 | | swift | supabase/supabase-swift | `ebef170` | v2.51.0 | | kt | supabase-community/supabase-kt | `e23df20` | 3.7.0-beta-1 | | csharp | supabase-community/supabase-csharp | `3fad62f` | v1.1.2 | ## Documentation changes ### `apps/docs/spec/supabase_dart_v2.yml` - **OAuth Server API** ([supabase-flutter#1561](https://github.com/supabase/supabase-flutter/pull/1561)): Added `oauth-server-api` group stub and `listGrants()` / `revokeGrant()` method entries, matching the existing `common-client-libs-sections.json` nav IDs. - **`listBuckets()` options** ([supabase-flutter#1557](https://github.com/supabase/supabase-flutter/pull/1557)): Added example showing `ListBucketsOptions` with `search`, `limit`, `offset`, `sortColumn`, and `sortOrder`. ### `apps/docs/spec/supabase_py_v2.yml` - **`on_postgres_changes` `select` param** ([supabase-py#1524](https://github.com/supabase/supabase-py/pull/1524)): Added `listening-to-selected-columns` example for the new `select=["id", "name"]` parameter. - **Expanded filter operators** ([supabase-py#1524](https://github.com/supabase/supabase-py/pull/1524)): Updated `listening-to-row-level-changes` note to list all supported operators (`eq`, `neq`, `lt`, `lte`, `gt`, `gte`, `in`, `like`, `ilike`, `is`, `match`, `imatch`, `isdistinct`) plus `not.` prefix and comma-AND. ### `apps/docs/spec/supabase_swift_v2.yml` - **OpenTelemetry tracing setup** ([supabase-swift#1101](https://github.com/supabase/supabase-swift/pull/1101)): Added `initialize-client-with-opentelemetry` example under the `initializing` section documenting the `OpenTelemetry` SwiftPM package trait, provider wiring, and known `_invokeWithStreamedResponse` limitation. ### `apps/docs/content/guides/telemetry/client-side-tracing.mdx` - **Merged Swift and Dart tracing docs** into the existing JS guide ([supabase-swift#1101](https://github.com/supabase/supabase-swift/pull/1101), [supabase-flutter#1564](https://github.com/supabase/supabase-flutter/pull/1564)). - **Converted to tabbed layout** (``) with JavaScript / Swift / Dart tabs, matching the pattern used across other multi-SDK guides. - Updated title to "Client-side tracing" and nav label accordingly. ## SDKs with no doc-worthy changes - **js**: Bug fixes only (auth session clearing, realtime heartbeat suppression) — no new API surface. - **kt**: PKCE for `resend()` — behavioral enhancement, no new spec entry needed. - **csharp**: Chore/compliance/maintenance only. --- 🤖 Generated with [Claude Code](https://claude.com/claude-code) ## Summary by CodeRabbit * **Documentation** * Added Dart “OAuth Server” API docs for listing OAuth grants and revoking grants (including signed-in context and the `clientId` parameter), with examples. * Extended Dart Storage docs with a new `listBuckets` example using `ListBucketsOptions` for filtering, pagination, and sorting. * Updated Python Realtime docs with generalized PostgREST-style row filter operators and added examples for listening to selected columns. * Reworked the “Client-side tracing” guide across JS, Swift, and Dart, including expanded configuration and troubleshooting (trace propagation and `traceparent` details). * Renamed the telemetry navigation label to “Client-side tracing.” --------- Co-authored-by: Claude Sonnet 4.6 --- .../NavigationMenu.constants.ts | 2 +- .../client-side-tracing.mdx | 142 ++++++++++++++++-- apps/docs/scripts/generate-dart-reference.ts | 2 +- apps/docs/spec/supabase_py_v2.yml | 26 +++- apps/docs/spec/supabase_swift_v2.yml | 20 +++ supa-mdx-lint/Rule003Spelling.toml | 1 + 6 files changed, 173 insertions(+), 20 deletions(-) diff --git a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts index 08c99b5eed0..77cbb1c8ef8 100644 --- a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts +++ b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts @@ -3062,7 +3062,7 @@ export const telemetry: NavMenuConstant = { url: '/guides/monitoring-and-debugging/sentry-monitoring' as `/${string}`, }, { - name: 'Tracing with the JS SDK', + name: 'Tracing with the client SDKs', url: '/guides/monitoring-and-debugging/client-side-tracing' as `/${string}`, }, ], diff --git a/apps/docs/content/guides/monitoring-and-debugging/client-side-tracing.mdx b/apps/docs/content/guides/monitoring-and-debugging/client-side-tracing.mdx index 901017e3b29..44b8a378ac4 100644 --- a/apps/docs/content/guides/monitoring-and-debugging/client-side-tracing.mdx +++ b/apps/docs/content/guides/monitoring-and-debugging/client-side-tracing.mdx @@ -1,12 +1,22 @@ --- id: 'client-side-tracing' -title: 'Tracing with the JS SDK' -description: 'Propagate W3C trace context from the Supabase JS SDK through Supabase services' +title: 'Client-side tracing' +description: 'Propagate W3C trace context from the Supabase JS, Swift, and Dart SDKs through Supabase services' --- -The Supabase JS SDK can attach [W3C Trace Context](https://www.w3.org/TR/trace-context/) headers (`traceparent`, `tracestate`, `baggage`) to outgoing requests. The resulting `trace_id` flows through Supabase services and appears in API Gateway and Edge Function logs, so you can correlate client-side spans with the server-side logs they produced — end-to-end, across the network boundary. +The Supabase JS, Swift, and Dart SDKs can attach [W3C Trace Context](https://www.w3.org/TR/trace-context/) headers (`traceparent`, `tracestate`, `baggage`) to outgoing requests. The resulting `trace_id` flows through Supabase services and appears in API Gateway and Edge Function logs, so you can correlate client-side spans with the server-side logs they produced — end-to-end, across the network boundary. -Because the headers follow the W3C standard, any compliant tracing SDK (OpenTelemetry, Sentry, Datadog, Honeycomb, etc.) can pick up the trace on the server side, including in self-hosted collectors. +Because the headers follow the W3C standard, any compliant tracing SDK (such as OpenTelemetry, Sentry, Datadog, or Honeycomb) can pick up the trace on the server side, including in self-hosted collectors. + + + + ## Requirements @@ -34,7 +44,7 @@ Trace propagation isn't available through the CDN (UMD) build — there's no way 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](https://opentelemetry.io/docs/languages/js/getting-started/) 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 Supabase SDK only takes care of propagating the trace context that's already active when a request is made. +The Supabase SDK only propagates the trace context that's already active when a request is made. ## Enable trace propagation @@ -84,18 +94,9 @@ const supabase = createClient(SUPABASE_URL, SUPABASE_KEY, { | `enabled` | `boolean` | `false` | Enable trace propagation. | | `respectSamplingDecision` | `boolean` | `true` | If `true`, skip propagation when the upstream trace is not sampled. | -## Correlating with Supabase logs - -Once trace context is flowing through, the `trace_id` appears in: - -- **API Gateway logs** — every request to PostgREST, Auth, Storage, and Realtime -- **Edge Function logs** — invocations and any structured logs emitted from within the function - -If you forward Supabase logs to a third-party backend via [Log Drains](/docs/guides/monitoring-and-debugging/log-drains), you can join Supabase logs to your own client and server traces using the shared `trace_id`. This is especially useful for self-hosted setups where you already operate your own OpenTelemetry collector — Supabase logs become first-class citizens in your existing tracing UI. - ## Using a vendor tracing SDK -Many tracing SDKs are built on top of OpenTelemetry. They work with this guide as long as a W3C-compliant propagator is registered — but propagator behavior varies. Some vendor SDKs inject only their proprietary headers by default and need extra configuration to also emit the standard `traceparent` header. Check your vendor's OTel integration docs for the exact setup. +Many tracing SDKs are built on top of OpenTelemetry. They work with this guide as long as a W3C-compliant propagator is registered. Some vendor SDKs inject only their proprietary headers by default and need extra configuration to also emit the standard `traceparent` header. Check your vendor's OTel integration docs for the exact setup. ## Troubleshooting @@ -104,7 +105,116 @@ The SDK never throws when it can't propagate, which keeps it safe to enable but - **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. Make sure your app calls `provider.register()` (or your vendor SDK's equivalent) before making requests. +- **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. - **The upstream trace is not sampled.** By default the SDK respects upstream sampling decisions. Set `respectSamplingDecision: false` to propagate every request regardless of sampling. - **You're calling a non-Supabase host through a custom `fetch`.** Trace headers are only attached to Supabase 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`: + + ```swift + // Package.swift + .package( + url: "https://github.com/supabase/supabase-swift.git", + from: "2.51.0", + traits: ["OpenTelemetry"] + ) + ``` + + No changes to `SupabaseClient` 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: + + ```swift + import Supabase + 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 `SupabaseClient`**. Any active span is now propagated automatically: + + ```swift + let supabase = SupabaseClient( + 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: + + ```dart + import 'package:supabase/supabase.dart'; + + final supabase = SupabaseClient( + '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 `Supabase.initialize`: + + ```dart + await Supabase.initialize( + url: 'https://xyzcompany.supabase.co', + anonKey: 'your-publishable-key', + tracePropagationOptions: TracePropagationOptions( + enabled: true, + traceContextProvider: () => yourTraceContextProvider(), + ), + ); + ``` + +## Options + +| Option | Type | Default | Description | +| ------------------------- | ----------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `enabled` | `bool` | `false` | Enable trace propagation. | +| `respectSamplingDecision` | `bool` | `true` | When `true`, skips propagation if the upstream trace is not sampled. Set to `false` to always attach a `trace_id` — useful for log correlation even when traces are not exported. | +| `traceContextProvider` | `TraceContextProvider?` | `null` | Callback returning the current `TraceContext`. Return `null` when there is no active span. | + +Headers are only injected on requests targeting Supabase hosts (`*.supabase.co`, `*.supabase.in`, your project host, and loopback addresses for local development). Third-party hosts never receive trace headers. + + + + + +## Correlating with Supabase logs + +After trace context is flowing through, the `trace_id` appears in: + +- **API Gateway logs** — every request to PostgREST, Auth, Storage, and Realtime +- **Edge Function logs** — invocations and any structured logs emitted from within the function + +If you forward Supabase logs to a third-party backend via [Log Drains](/docs/guides/monitoring-and-debugging/log-drains), you can join Supabase logs to your own client and server traces using the shared `trace_id`. This is especially useful for self-hosted setups where you already operate your own OpenTelemetry collector — Supabase logs become first-class citizens in your existing tracing UI. diff --git a/apps/docs/scripts/generate-dart-reference.ts b/apps/docs/scripts/generate-dart-reference.ts index 6171c1b47f9..f57cfc8db07 100644 --- a/apps/docs/scripts/generate-dart-reference.ts +++ b/apps/docs/scripts/generate-dart-reference.ts @@ -58,10 +58,10 @@ const OUT_PATH = join(VERSION_DIR, 'supabase_flutter.json') const HEADER_IDS = new Set([ 'auth-api', 'auth-mfa-api', + 'oauth-server-api', 'passkey-api', 'admin-api', 'admin-passkey-api', - 'oauth-server-api', 'admin-custom-providers-api', 'functions-api', 'database-api', diff --git a/apps/docs/spec/supabase_py_v2.yml b/apps/docs/spec/supabase_py_v2.yml index a75006f8135..5b77ff8d10e 100644 --- a/apps/docs/spec/supabase_py_v2.yml +++ b/apps/docs/spec/supabase_py_v2.yml @@ -7517,9 +7517,9 @@ functions: ``` - id: listening-to-row-level-changes name: Listen to row level changes - description: You can listen to individual rows using the format `{table}:{col}=eq.{val}` - where `{col}` is the column name, and `{val}` is the value which you want to match. + description: You can listen to individual rows using the format `{table}:{col}=op.{val}` - where `{col}` is the column name, `{op}` is the filter operator, and `{val}` is the value to match. notes: | - - ``eq`` filter works with all database types as under the hood, it's casting both the filter value and the database value to the correct type and then comparing them. + - Supported operators: ``eq``, ``neq``, ``lt``, ``lte``, ``gt``, ``gte``, ``in`` (e.g. ``"status=in.(active,pending)"``), ``like``, ``ilike``, ``is`` (e.g. ``"deleted_at=is.null"``), ``match``, ``imatch`` (POSIX regex), ``isdistinct`` (NULL-safe inequality). Prefix any operator with ``not.`` to negate it (e.g. ``"status=not.in.(draft,archived)"``). Combine multiple conditions with commas for an implicit ``AND`` (e.g. ``"amount=gt.100,status=in.(open,pending)"``). code: | ```python response = ( @@ -7528,6 +7528,28 @@ functions: .subscribe() ) ``` + - id: listening-to-selected-columns + name: Listen to selected columns only + description: | + Use the `select` parameter to receive only specific columns instead of the full row. + This reduces payload size, which is especially useful for tables with large `bytea` or `jsonb` columns. + code: | + ```python + def handle_record_updated(payload): + print("Updated country:", payload) + + response = ( + await supabase.channel("room1") + .on_postgres_changes( + "UPDATE", + schema="public", + table="countries", + select=["id", "name"], + callback=handle_record_updated, + ) + .subscribe() + ) + ``` - id: broadcast-message title: broadcastMessage() description: | diff --git a/apps/docs/spec/supabase_swift_v2.yml b/apps/docs/spec/supabase_swift_v2.yml index 921e5bde9d5..3c56ac8bc68 100644 --- a/apps/docs/spec/supabase_swift_v2.yml +++ b/apps/docs/spec/supabase_swift_v2.yml @@ -116,6 +116,26 @@ functions: Go to [Settings > API > Exposed schemas](/dashboard/project/_/settings/api) and add the schema which you want to expose to the API. Note: each client connection can only access a single schema, so the code above can access the `other_schema` schema but cannot access the `public` schema. + - id: initialize-client-with-opentelemetry + name: Initialize Client with OpenTelemetry tracing + description: | + Supabase Swift supports W3C `traceparent` header propagation via an opt-in SwiftPM package trait. + When enabled, the active OpenTelemetry span's trace context is automatically injected into every outgoing request across PostgREST, Storage, Auth, Functions, and Realtime — no additional runtime configuration needed. + + Enable the `OpenTelemetry` trait in your `Package.swift` dependency declaration: + code: | + ```swift + // Package.swift + .package( + url: "https://github.com/supabase/supabase-swift.git", + from: "2.51.0", + traits: ["OpenTelemetry"] + ) + ``` + notes: | + - Requires swift-tools-version 6.1 or later (trait support). + - The trait is **off by default** — no OTel dependency is linked unless you opt in. + - When no span is active, the header is not added; it is always safe to call unconditionally. - id: auth-api title: 'Overview' notes: | diff --git a/supa-mdx-lint/Rule003Spelling.toml b/supa-mdx-lint/Rule003Spelling.toml index 2a830738c95..309dd055091 100644 --- a/supa-mdx-lint/Rule003Spelling.toml +++ b/supa-mdx-lint/Rule003Spelling.toml @@ -404,6 +404,7 @@ allow_list = [ "mTLS", "Supavisor", "SvelteKit", + "SwiftPM", "SwiftUI", "Reddit", "Remapper",