From bbef8f07ba7ead36366279bbdad19de052ba4997 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kamil=20Og=C3=B3rek?= Date: Fri, 7 Jun 2024 13:41:36 +0200 Subject: [PATCH] Separate v7 and v8 documentation into separate markdown files --- README-v7.md | 252 +++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 55 ++--------- 2 files changed, 261 insertions(+), 46 deletions(-) create mode 100644 README-v7.md diff --git a/README-v7.md b/README-v7.md new file mode 100644 index 0000000..9d066fc --- /dev/null +++ b/README-v7.md @@ -0,0 +1,252 @@ +
+ +

+ + + + Supabase logo + +
+ + + + Sentry logo + +

+ +# @supabase/sentry-js-integration + +Sentry JavaScript SDK v7 Integration that can be used to instrument Supabase JavaScript SDK and collect traces, breadcrumbs and errors. The integration supports browser, Node, and edge environments. + +> [!IMPORTANT] +> If you are using Sentry JavaScript SDK v8, reference [README.md](README.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: [ + new SupabaseIntegration(SupabaseClient, { + 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: [ + new SupabaseIntegration(supabaseClient, { + 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. + +### Removing duplicated http/fetch spans + +If you are using built-in `Http`, `Fetch` or `Undici` 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: [ + new SupabaseIntegration(SupabaseClient, Sentry, { + tracing: true, + breadcrumbs: true, + errors: true, + }), + + // @sentry/browser + new Sentry.BrowserTracing({ + shouldCreateSpanForRequest: (url) => { + return !url.startsWith(`${SUPABASE_URL}/rest`); + }, + }), + + // or @sentry/node + new Sentry.Integrations.Http({ + tracing: { + shouldCreateSpanForRequest: (url) => { + return !url.startsWith(`${SUPABASE_URL}/rest`); + }, + }, + }), + + // or @sentry/node with Fetch support + new Sentry.Integrations.Undici({ + shouldCreateSpanForRequest: (url) => { + return !url.startsWith(`${SUPABASE_URL}/rest`); + }, + }), + + // or @sentry/WinterCGFetch for Next.js Middleware & Edge Functions + new Sentry.Integrations.WinterCGFetch({ + 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](https://docs.sentry.io/platforms/javascript/guides/nextjs/#install) 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, + }), + new SupabaseIntegration(SupabaseClient, Sentry, { + tracing: true, + breadcrumbs: true, + errors: true, + }), + new Sentry.BrowserTracing({ + 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: [ + new SupabaseIntegration(SupabaseClient, Sentry, { + tracing: true, + breadcrumbs: true, + errors: true, + }), + new Sentry.Integrations.Undici({ + shouldCreateSpanForRequest: (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: [ + new SupabaseIntegration(SupabaseClient, Sentry, { + tracing: true, + breadcrumbs: true, + errors: true, + }), + new Sentry.Integrations.WinterCGFetch({ + 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, +}); +``` + +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. + +
diff --git a/README.md b/README.md index dfe716e..5abe8ba 100644 --- a/README.md +++ b/README.md @@ -20,13 +20,16 @@ Sentry JavaScript SDK Integration that can be used to instrument Supabase JavaSc See [Showcase](#showcase) section for detailed screenshots of what is captured. +> [!IMPORTANT] +> If you are using Sentry JavaScript SDK v7, reference [README-v7.md](README-v7.md) instead. + ## Install ```sh npm install @supabase/sentry-js-integration ``` -## Usage (Sentry SDK v8) +## Usage ```js import * as Sentry from "@sentry/browser"; @@ -66,46 +69,6 @@ Sentry.init({ }); ``` -## Usage (Sentry SDK v7) - -```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: [ - new SupabaseIntegration(SupabaseClient, { - 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: [ - new SupabaseIntegration(supabaseClient, { - tracing: true, - breadcrumbs: true, - errors: true, - }), - ], -}); -``` - ## Options | Option | Description | Default | @@ -288,12 +251,12 @@ Sentry.init({ ```js instrumentation.ts export async function register() { - if (process.env.NEXT_RUNTIME === 'nodejs') { - await import('./sentry.server.config'); + if (process.env.NEXT_RUNTIME === "nodejs") { + await import("./sentry.server.config"); } - if (process.env.NEXT_RUNTIME === 'edge') { - await import('./sentry.edge.config'); + if (process.env.NEXT_RUNTIME === "edge") { + await import("./sentry.edge.config"); } } ``` @@ -333,7 +296,7 @@ npm run test ```sh # Add new files to package.json#files if applicable npm version -git push +git push --follow-tags npm publish ```