mirror of
https://github.com/supabase/supabase.git
synced 2026-10-05 01:15:03 +03:00
docs: Update SDK references from recent releases (#47830)
## 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** (`<Tabs queryGroup="language">`) 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) <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## 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.” <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Guilherme SouzaandClaude Sonnet 4.6 authored and GitHub committed
1 parent
a66dae48f2
commit
31d1a639c0
6 files changed
+173
-20
No files matched your search
@@ -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}`,
|
||||
},
|
||||
],
|
||||
|
||||
@@ -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.
|
||||
|
||||
<Tabs
|
||||
scrollable
|
||||
size="small"
|
||||
type="underlined"
|
||||
defaultActiveId="js"
|
||||
queryGroup="language"
|
||||
>
|
||||
|
||||
<TabPanel id="js" label="JavaScript">
|
||||
|
||||
## 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.
|
||||
|
||||
</TabPanel>
|
||||
|
||||
<TabPanel id="swift" label="Swift">
|
||||
|
||||
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"
|
||||
)
|
||||
```
|
||||
|
||||
</TabPanel>
|
||||
|
||||
<TabPanel id="dart" label="Dart">
|
||||
|
||||
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.
|
||||
|
||||
</TabPanel>
|
||||
|
||||
</Tabs>
|
||||
|
||||
## 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.
|
||||
@@ -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',
|
||||
|
||||
@@ -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: |
|
||||
|
||||
@@ -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: |
|
||||
|
||||
@@ -404,6 +404,7 @@ allow_list = [
|
||||
"mTLS",
|
||||
"Supavisor",
|
||||
"SvelteKit",
|
||||
"SwiftPM",
|
||||
"SwiftUI",
|
||||
"Reddit",
|
||||
"Remapper",
|
||||
|
||||
Reference in new issue
Block a user