Supabase

Import name: Sentry.supabaseIntegration

The supabaseIntegration adds instrumentation for the Supabase client to capture spans for both authentication and database operations.

Installation

You need to have both the Sentry SDK and the Supabase library installed. For Supabase installation instructions, refer to the Supabase JavaScript documentation.

Configuration

This is the preferred method for most use cases and follows Sentry's standard integration pattern.

import * as Sentry from "___SDK_PACKAGE___";
import { createClient } from "@supabase/supabase-js";

const supabaseClient = createClient(
  "YOUR_SUPABASE_URL",
  "YOUR_SUPABASE_KEY",
);

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  integrations: [Sentry.supabaseIntegration({ supabaseClient })],
  tracesSampleRate: 1.0,
});

import * as Sentry from "___SDK_PACKAGE___";
import { createClient } from "@supabase/supabase-js";

const supabaseClient = createClient(
  "YOUR_SUPABASE_URL",
  "YOUR_SUPABASE_KEY",
);

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  integrations: [Sentry.supabaseIntegration({ supabaseClient })],
  tracesSampleRate: 1.0,
});

Generated Spans

The integration provides comprehensive monitoring for both authentication and database operations:

Authentication Spans

The integration automatically instruments the following auth operations:

• signInWithPassword
• signOut
• signInAnonymously
• signInWithOAuth
• signInWithIdToken
• signInWithOtp
• signInWithSSO
• signUp
• verifyOtp
• reauthenticate

Admin operations are also instrumented:

• createUser
• deleteUser
• listUsers
• getUserById
• updateUserById
• inviteUserByEmail

Database Operation Spans

These spans are used to populate Sentry's pre-built Query Dashboards feature, which provides performance metrics and analysis for your database operations. With Query Dashboards, you can identify slow queries, track query frequency, and optimize your database interactions.

• db.table: The table being queried
• db.schema: The database schema
• db.url: The Supabase instance URL
• db.sdk: Client information
• db.system: Set to 'postgresql'
• db.query: The query parameters
• db.body: The request body (for mutations)

Queue Operation Spans (in progress)

Coming soon, the Sentry SDK will also support generating spans for interactions with Supabase queues. For more information, please follow this GitHub issue.

Error Tracking

The integration automatically:

• Captures errors from failed operations
• Adds breadcrumbs for database operations
• Includes detailed context about the operation that failed

Supported Versions

• @supabase/supabase-js: >=2.0.0

Trace Propagation

Supabase can add the W3C traceparent header to requests so its API Gateway and Edge Function logs share a trace ID with Sentry spans.

Before you begin, make sure that:

• Your app uses @supabase/supabase-js version 2.106.0 or later.
• Your app uses Sentry JavaScript SDK version 10.10.0 or later.
• Your app uses the Supabase npm package. Trace propagation isn't available in the CDN build.
• @opentelemetry/api is available at runtime. The Sentry SDK provides the required W3C-compliant OpenTelemetry provider.

Then configure trace propagation:

1. If you use @supabase/supabase-js version 2.112.0 or later, add import "@supabase/supabase-js/tracing"; once at your app's entry point.
2. Set propagateTraceparent: true in Sentry.init(). For browser apps, also add your Supabase project URL to tracePropagationTargets because Supabase requests are cross-origin.
3. Set tracePropagation: true when you create the Supabase client.
4. If the browser calls Supabase Edge Functions directly, add sentry-trace to the function's CORS allow-list.

Starting with @supabase/supabase-js version 2.112.3, unsampled requests include traceparent, but omit tracestate and baggage. To send the full trace context regardless of the sampling decision, set respectSamplingDecision: false on the Supabase client.

With Supabase Log Drains, you can use the shared trace ID to navigate from a Sentry span to the Supabase logs it produced. For configuration examples and troubleshooting, see the Supabase client-side tracing documentation.