Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

docs(python): add python docs for otel instrumention (#48898)

Leonardo Santiago34c29f0b983b
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 23ce8095775..790e92d11de 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
@@ -4,7 +4,7 @@ title: 'Client-side tracing'
description: 'Propagate W3C trace context from the Supabase JS, Swift, and Dart SDKs through Supabase services'
---
-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.
+The Supabase JS, Swift, Dart and Python 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 (such as OpenTelemetry, Sentry, Datadog, or Honeycomb) can pick up the trace on the server side, including in self-hosted collectors. On the client side, some vendor SDKs need a small configuration change before they emit the standard headers — see [Using a vendor tracing SDK](#using-a-vendor-tracing-sdk) in the JavaScript tab.
@@ -226,6 +226,50 @@ Headers are only injected on requests targeting Supabase hosts (`*.supabase.co`,
</TabPanel>
+<TabPanel id="python" label="Python">
+
+The Python `opentelemetry` propagation is handled entirely through the `opentelemetry-instrumentation-httpx` package.
+
+1. **Add** the `opentelemetry-sdk` and `opentelemetry-instrumentation-httpx` package:
+
+```sh
+uv add opentelemetry-sdk opentelemetry-instrumentation-httpx
+```
+
+2. **Instrument** the `httpx` client using the `HTTPXClientInstrumentor`:
+
+```python
+from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor
+HTTPXClientInstrumentor().instrument()
+```
+
+<Admonition type="note">
+
+This will instrument all `httpx` clients in your process. If you want to instrument only the Supabase client, you can use `HTTPXClientInstrumentor.instrument_client` in the specific sub-package client you want to trace.
+
+</Admonition>
+
+3. **Create** your `SupabaseClient`. Any active span is now propagated automatically:
+
+```python
+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()
+```
+
+</TabPanel>
+
</Tabs>
## Correlating with Supabase logs