@supabase/sentry-js-integration

Sentry JavaScript SDK Integration that can be used to instrument Supabase JavaScript SDK and collect traces, breadcrumbs and errors. The integration supports browser, Node, and edge environments.

See Showcase section for detailed screenshots of what is captured.

> [!IMPORTANT]
> If you are using Sentry JavaScript SDK v7, reference README-v7.md instead.

Install

``sh
npm install @supabase/sentry-js-integration
`

Usage

`js
import * as Sentry from "@sentry/browser";
import { SupabaseClient } from "@supabase/supabase-js";
import { supabaseIntegration } from "@supabase/sentry-js-integration";

Sentry.init({
dsn: SENTRY_DSN,
integrations: [
supabaseIntegration(SupabaseClient, Sentry, {
tracing: true,
breadcrumbs: true,
errors: true,
}),
],
});
`

or

`js
import * as Sentry from "@sentry/browser";
import { createClient } from "@supabase/supabase-js";
import { supabaseIntegration } from "@supabase/sentry-js-integration";

const supabaseClient = createClient(SUPABASE_URL, SUPABASE_KEY);

Sentry.init({
dsn: SENTRY_DSN,
integrations: [
supabaseIntegration(supabaseClient, Sentry, {
tracing: true,
breadcrumbs: true,
errors: true,
}),
],
});
`

Options

| Option | Description | Default |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| tracing | Enable tracing instrumentation for database calls | true |
| breadcrumbs | Enable capturing breadcrumbs for database calls | true |
| errors | Enable capturing non-throwable database errors as Sentry exceptions | false |
| operations | Configures which methods should be instrumented for the features above | - |
| sanitizeBody | Allows for modifying captured body values that are passed to insert, upsert, and update operations, before assigned to a span, breadcrumb, or error | - |
| shouldCreateSpan | Decide whether a span should be created based on the query payload used to capture this data | - |
| shouldCreateBreadcrumb | Decide whether a breadcrumb should be created based on the query payload used to capture this data | - |

See https://github.com/supabase-community/sentry-integration-js/blob/master/index.d.ts for detailed options types.

$3

If you are using built-in Http, Fetch or nativeNodeFetchIntegration integrations in your current Sentry setup, you might want to skip some of the spans that will be already covered by supabaseIntegration. Here's a quick snippet how to do that:

`js
import * as Sentry from "@sentry/browser";
import { SupabaseClient } from "@supabase/supabase-js";
import { supabaseIntegration } from "@supabase/sentry-js-integration";

Sentry.init({
dsn: SENTRY_DSN,
integrations: [
supabaseIntegration(SupabaseClient, Sentry, {
tracing: true,
breadcrumbs: true,
errors: true,
}),

// @sentry/browser
Sentry.browserTracingIntegration({
shouldCreateSpanForRequest: (url) => {
return !url.startsWith(${SUPABASE_URL}/rest);
},
}),

// or @sentry/node
Sentry.httpIntegration({
tracing: {
ignoreOutgoingRequests: (url) => {
return url.startsWith(${SUPABASE_URL}/rest);
},
},
}),

// or @sentry/node with Fetch support
Sentry.nativeNodeFetchIntegration({
ignoreOutgoingRequests: (url) => {
return url.startsWith(${SUPABASE_URL}/rest);
},
}),

// or @sentry/WinterCGFetch for Next.js Middleware & Edge Functions
Sentry.winterCGFetchIntegration({
breadcrumbs: true,
shouldCreateSpanForRequest: (url) => {
return !url.startsWith(${SUPABASE_URL}/rest);
},
}),
],
});
`

Example Next.js configuration

See this example for a setup with Next.js to cover browser, server, and edge environments. First, run through the Sentry Next.js wizard to generate the base Next.js configuration. Then add the Supabase Sentry Integration to all your Sentry.init calls with the appropriate filters.

sentry.client.config.ts

`js sentry.client.config.ts
import * as Sentry from "@sentry/nextjs";
import { SupabaseClient } from "@supabase/supabase-js";
import { supabaseIntegration } from "@supabase/sentry-js-integration";

Sentry.init({
dsn: SENTRY_DSN,
// Adjust this value in production, or use tracesSampler for greater control
tracesSampleRate: 1,

// Setting this option to true will print useful information to the console while you're setting up Sentry.
debug: true,

replaysOnErrorSampleRate: 1.0,

// This sets the sample rate to be 10%. You may want this to be 100% while
// in development and sample at a lower rate in production
replaysSessionSampleRate: 0.1,

// You can remove this option if you're not planning to use the Sentry Session Replay feature:
integrations: [
Sentry.replayIntegration({
// Additional Replay configuration goes in here, for example:
maskAllText: true,
blockAllMedia: true,
}),
supabaseIntegration(SupabaseClient, Sentry, {
tracing: true,
breadcrumbs: true,
errors: true,
}),
Sentry.browserTracingIntegration({
shouldCreateSpanForRequest: (url) => {
return !url.startsWith(${process.env.NEXT_PUBLIC_SUPABASE_URL}/rest);
},
}),
],
});
`

sentry.server.config.ts

`js sentry.server.config.ts
import * as Sentry from "@sentry/nextjs";
import { SupabaseClient } from "@supabase/supabase-js";
import { supabaseIntegration } from "@supabase/sentry-js-integration";

Sentry.init({
dsn: SENTRY_DSN,
integrations: [
supabaseIntegration(SupabaseClient, Sentry, {
tracing: true,
breadcrumbs: true,
errors: true,
}),
Sentry.nativeNodeFetchIntegration({
ignoreOutgoingRequests: (url) => {
console.log(
"server",
${process.env.NEXT_PUBLIC_SUPABASE_URL}/rest,
url
);
return url.startsWith(${process.env.NEXT_PUBLIC_SUPABASE_URL}/rest);
},
}),
],

// Adjust this value in production, or use tracesSampler for greater control
tracesSampleRate: 1,

// Setting this option to true will print useful information to the console while you're setting up Sentry.
debug: true,
});
`

sentry.edge.config.ts

`js sentry.edge.config.ts
import * as Sentry from "@sentry/nextjs";
import { SupabaseClient } from "@supabase/supabase-js";
import { supabaseIntegration } from "@supabase/sentry-js-integration";

Sentry.init({
dsn: SENTRY_DSN,
integrations: [
supabaseIntegration(SupabaseClient, Sentry, {
tracing: true,
breadcrumbs: true,
errors: true,
}),
Sentry.winterCGFetchIntegration({
breadcrumbs: true,
shouldCreateSpanForRequest: (url) => {
return !url.startsWith(${process.env.NEXT_PUBLIC_SUPABASE_URL}/rest);
},
}),
],
// Adjust this value in production, or use tracesSampler for greater control
tracesSampleRate: 1,

// Setting this option to true will print useful information to the console while you're setting up Sentry.
debug: true,
});
`

`js instrumentation.ts
export async function register() {
if (process.env.NEXT_RUNTIME === "nodejs") {
await import("./sentry.server.config");
}

if (process.env.NEXT_RUNTIME === "edge") {
await import("./sentry.edge.config");
}
}
`

Afterward build your application (npm run build) and start it locally (npm run start). You will now see the transactions being logged in the terminal when making supabase-js requests.

Developing

Run library unit tests:

`sh
npm install
npm run lint
npm run test
`

Run types tests for SDK v8:

`sh
cd tests-types/v8
npm install
npm run test
`

Run types tests for SDK v7:

`sh
cd tests-types/v7
npm install
npm run test
`

Publishing

`sh


Add new files to package.json#files if applicable


npm version
git push --follow-tags
npm publish
``

Then bump release version + changelog in https://github.com/supabase-community/sentry-integration-js/releases.

Showcase

_(click to enlarge image)_

$3

$3

$3

$3

$3