feat(core): Add Supabase Queues support #15921

onurtemizkan · 2025-03-28T18:42:48Z

Resolves: #14611

Summary:

Sample Queue Event: Link

Adds queue spans and breadcrumbs for Supabase Queue operations.
- Usage with supabaseClient.rpc('<queue_op>', ...)
- Usage with supabaseClient.schema(...).rpc('queue_op', ...)
Mapped operations to their respective op names documented here
- producer ops: send, send_batch
- consumer op: pop
Added browser integration tests, and e2e tests.

github-actions · 2025-03-28T18:51:24Z

size-limit report 📦

Path	Size	% Change	Change
@sentry/browser	24.16 kB	-	-
@sentry/browser - with treeshaking flags	22.73 kB	-	-
@sentry/browser (incl. Tracing)	39.87 kB	-	-
@sentry/browser (incl. Tracing, Replay)	77.99 kB	-	-
@sentry/browser (incl. Tracing, Replay) - with treeshaking flags	67.83 kB	-	-
@sentry/browser (incl. Tracing, Replay with Canvas)	82.69 kB	-	-
@sentry/browser (incl. Tracing, Replay, Feedback)	94.79 kB	-	-
@sentry/browser (incl. Feedback)	40.83 kB	-	-
@sentry/browser (incl. sendFeedback)	28.81 kB	-	-
@sentry/browser (incl. FeedbackAsync)	33.7 kB	-	-
@sentry/react	25.88 kB	-	-
@sentry/react (incl. Tracing)	41.86 kB	-	-
@sentry/vue	28.64 kB	-	-
@sentry/vue (incl. Tracing)	41.69 kB	-	-
@sentry/svelte	24.18 kB	-	-
CDN Bundle	25.66 kB	-	-
CDN Bundle (incl. Tracing)	39.76 kB	-	-
CDN Bundle (incl. Tracing, Replay)	75.82 kB	-	-
CDN Bundle (incl. Tracing, Replay, Feedback)	81.27 kB	-	-
CDN Bundle - uncompressed	74.96 kB	-	-
CDN Bundle (incl. Tracing) - uncompressed	117.59 kB	-	-
CDN Bundle (incl. Tracing, Replay) - uncompressed	231.88 kB	-	-
CDN Bundle (incl. Tracing, Replay, Feedback) - uncompressed	244.48 kB	-	-
@sentry/nextjs (client)	43.89 kB	-	-
@sentry/sveltekit (client)	40.32 kB	-	-
@sentry/node-core	47.99 kB	-0.01%	-1 B 🔽
@sentry/node	147.03 kB	-	-
@sentry/node - without tracing	92.24 kB	-	-
@sentry/aws-serverless	103.67 kB	-	-

View base workflow run

lforst · 2025-05-08T11:57:52Z

packages/core/src/integrations/supabase.ts

+            },
+          },
+          async span => {
+            return (Reflect.apply(target, thisArg, argumentsList) as Promise<unknown>).then((res: unknown) => {


We should probably also end the span when it throws/rejects? We can also set the status of the span then.

lforst · 2025-05-08T11:58:38Z

packages/core/src/integrations/supabase.ts

+            name: 'supabase.db.rpc',
+            attributes: {
+              [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.db.supabase',
+              [SEMANTIC_ATTRIBUTE_SENTRY_OP]: op,


I think we can add the messaging.system attribute to be 'supabase' as described in https://develop.sentry.dev/sdk/telemetry/traces/modules/queues/

lforst · 2025-05-08T12:04:13Z

packages/core/src/integrations/supabase.ts

+        const isProducerSpan = argumentsList[0] === 'enqueue';
+        const isConsumerSpan = argumentsList[0] === 'dequeue';


I don't know if this recently changed, but here they show send and pop as rpc args: https://supabase.com/docs/guides/queues/quickstart#enqueueing-and-dequeueing-messages 🤔

AbhiPrasad · 2025-06-26T14:53:35Z

@sentry review

seer-by-sentry · 2025-06-26T14:54:48Z

On it! We are reviewing the PR and will provide feedback shortly.

seer-by-sentry · 2025-06-26T14:56:33Z

PR Description

This pull request introduces instrumentation for Supabase queue operations using pgmq, enabling Sentry to capture spans and breadcrumbs for queue publishing and processing. This provides visibility into asynchronous task execution within Supabase applications.

Click to see more

Key Technical Changes

The key technical changes include: 1) Instrumenting the rpc method of the Supabase client to detect queue operations (send, send_batch, pop). 2) Creating spans for queue publish and process operations, capturing relevant metadata like queue name and message ID. 3) Adding breadcrumbs for queue operations to provide context in Sentry events. 4) Modifying queue messages to inject Sentry trace context for distributed tracing. 5) Adding e2e tests to verify the instrumentation in a Next.js application.

Architecture Decisions

The primary architectural decision involves using Proxy objects to intercept calls to the Supabase client's rpc method and the schema(...).rpc(...) method. This allows for non-intrusive instrumentation without modifying the Supabase client's core code. The trace context is injected directly into the message body to propagate tracing information across queue operations.

Dependencies and Interactions

This integration depends on the @supabase/supabase-js library and interacts with Sentry's tracing and breadcrumb APIs. It also relies on the pgmq extension being enabled in the Supabase database. The integration injects Sentry trace context into queue messages, which requires consumers to be instrumented to extract and continue the trace.

Risk Considerations

Potential risks include: 1) Performance overhead due to the instrumentation, although proxies are generally performant. 2) Incorrectly identifying queue operations, leading to spurious spans. 3) Failure to propagate trace context if consumers are not properly instrumented. 4) Security implications of modifying message bodies, although the injected data is limited to Sentry trace context. 5) The modification of the arguments list in place could lead to unexpected side effects.

Notable Implementation Details

Notable implementation details include: 1) The use of continueTrace to link consumer spans to producer spans. 2) The handling of both rpc and schema(...).rpc(...) calls. 3) The injection of Sentry trace context into the message body. 4) The vendoring of SQL code from the Supabase repository to enable queue access locally.

packages/core/src/integrations/supabase.ts

smeubank · 2025-07-14T18:42:36Z

anybody got eyes on this anymore? 😅

cursor · 2025-08-13T15:03:19Z

packages/core/src/integrations/supabase.ts

+        });
+    },
+  );
+}


Bug: Supabase RPC Error Handling Flaws

The instrumentRpcConsumer and instrumentRpcProducer functions throw a TypeError when computing messageId. This occurs because res?.data?.map(...).join(',') attempts to call join on undefined if res.data is null or undefined, which is common for Supabase RPC error responses. This prevents proper error handling (span status, exception capture), masks the original error, and can crash the application. A defensive check (e.g., Array.isArray(res.data)) is required. Additionally, the captureException call in instrumentRpcConsumer for Supabase errors is missing the mechanism attribute, which should be { handled: false, type: 'auto.db.supabase' }.

cursor · 2025-08-13T15:03:19Z

packages/core/src/integrations/supabase.ts

+      },
+    },
+  );
+}


Bug: Supabase Integration Errors: Exception Handling, Proxying, and Redundancy

The Supabase integration has three issues:

captureException in the instrumentRpcProducer's error handling lacks a mechanism.type, violating SDK conventions for proper error classification.

instrumentRpc unconditionally proxies client.rpc. If the Supabase constructor (instead of an instance) is passed to instrumentSupabaseClient, client.rpc is undefined, causing new Proxy(undefined, ...) to crash Sentry initialization.

The rpc method (and schema's rpc method) is proxied without an idempotency guard. This allows multiple wraps if the integration is initialized more than once, leading to duplicate spans, breadcrumbs, and _sentry metadata injection.

cursor · 2025-08-13T15:03:19Z

packages/core/src/integrations/supabase.ts

+        });
+    },
+  );
+}


Bug: Missing Mechanism Attributes in Exception Capture

captureException calls in instrumentRpcConsumer and instrumentRpcProducer are missing required mechanism attributes. Specifically, mechanism.handled and mechanism.type are missing in instrumentRpcConsumer and the res.error path of instrumentRpcProducer. The catch path in instrumentRpcProducer sets mechanism.handled but omits mechanism.type. Per SDK guidelines, all captureException calls must include both mechanism.handled and a mechanism.type (e.g., auto.db.supabase.queue) for consistent error context and diagnostics.

Additional Locations (1)

packages/core/src/integrations/supabase.ts#L366-L374

cursor · 2025-08-13T15:03:19Z

packages/core/src/integrations/supabase.ts

+          // and should not be instrumented here.
+          return Reflect.apply(target, thisArg, argumentsList);
+        }
+


Bug: RPC Observability Regression

Supabase RPC calls are no longer instrumented. The PostgRESTFilterBuilder now skips /rpc paths, and the new RPC instrumentation only covers queue operations (send, send_batch, pop). This regression causes a loss of spans and breadcrumbs for all other RPC calls, impacting observability.

onurtemizkan force-pushed the onur/supabase-queues branch from bbadd60 to e7b3370 Compare March 31, 2025 09:44

onurtemizkan force-pushed the onur/supabase-integration branch from 1bc2897 to d387514 Compare March 31, 2025 10:26

onurtemizkan force-pushed the onur/supabase-queues branch from e7b3370 to 56a2d84 Compare March 31, 2025 14:12

onurtemizkan linked an issue Mar 31, 2025 that may be closed by this pull request

Support for Supabase Queues #14611

Open

onurtemizkan force-pushed the onur/supabase-queues branch from 56a2d84 to 13d60e0 Compare March 31, 2025 14:25

onurtemizkan force-pushed the onur/supabase-integration branch 4 times, most recently from 423397d to 556703c Compare April 14, 2025 15:26

Base automatically changed from onur/supabase-integration to develop April 17, 2025 13:35

onurtemizkan force-pushed the onur/supabase-queues branch from 13d60e0 to 74869e4 Compare April 22, 2025 14:16

onurtemizkan marked this pull request as ready for review April 24, 2025 09:32

onurtemizkan requested review from lforst and smeubank April 24, 2025 09:33

onurtemizkan force-pushed the onur/supabase-queues branch from e63915a to 719c8b6 Compare April 24, 2025 14:11

lforst reviewed May 8, 2025

View reviewed changes

onurtemizkan force-pushed the onur/supabase-queues branch 4 times, most recently from fb8eeb1 to a8da234 Compare May 31, 2025 20:58

onurtemizkan force-pushed the onur/supabase-queues branch 2 times, most recently from ff2f804 to 5ce5ee9 Compare June 23, 2025 15:58

onurtemizkan requested review from Lms24 and AbhiPrasad June 23, 2025 23:39

AbhiPrasad assigned onurtemizkan Jun 24, 2025

seer-by-sentry bot reviewed Jun 26, 2025

View reviewed changes

packages/core/src/integrations/supabase.ts Outdated Show resolved Hide resolved

seer-by-sentry bot reviewed Jun 26, 2025

View reviewed changes

packages/core/src/integrations/supabase.ts Outdated Show resolved Hide resolved

This comment was marked as outdated.

Sign in to view

onurtemizkan force-pushed the onur/supabase-queues branch from 4f19854 to 1c518a2 Compare July 3, 2025 14:40

This comment was marked as outdated.

Sign in to view

onurtemizkan force-pushed the onur/supabase-queues branch from 1c518a2 to 327b57a Compare July 24, 2025 11:29

This comment was marked as outdated.

Sign in to view

onurtemizkan added 11 commits August 13, 2025 15:43

feat(core): Add Supabase Queues support

6bb5f64

Skip tests on bundles

75676cc

Update test usage

3bca9d1

Lint

c1921ce

Update implementation

4eecc6c

Update playwright tests

825baea

Tidy up test endpoints

3fe61ff

Refactor / reimplement

ca43d3f

Add missing import

3c1e23d

Rename SupabaseClientConstructor to SupabaseClientConstructorType

7511cbc

Extract instrumentRpcMethod

1ed3684

onurtemizkan force-pushed the onur/supabase-queues branch from 327b57a to 1ed3684 Compare August 13, 2025 14:52

cursor bot reviewed Aug 13, 2025

View reviewed changes

		const isProducerSpan = argumentsList[0] === 'enqueue';
		const isConsumerSpan = argumentsList[0] === 'dequeue';

Uh oh!

feat(core): Add Supabase Queues support #15921

Are you sure you want to change the base?

feat(core): Add Supabase Queues support #15921

Uh oh!

Conversation

onurtemizkan commented Mar 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Mar 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

size-limit report 📦

Uh oh!

lforst May 8, 2025

Choose a reason for hiding this comment

Uh oh!

lforst May 8, 2025

Choose a reason for hiding this comment

Uh oh!

lforst May 8, 2025

Choose a reason for hiding this comment

Uh oh!

AbhiPrasad commented Jun 26, 2025

Uh oh!

seer-by-sentry bot commented Jun 26, 2025

Uh oh!

seer-by-sentry bot commented Jun 26, 2025

PR Description

Key Technical Changes

Architecture Decisions

Dependencies and Interactions

Risk Considerations

Notable Implementation Details

Uh oh!

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

smeubank commented Jul 14, 2025

Uh oh!

This comment was marked as outdated.

Uh oh!

cursor bot Aug 13, 2025

Choose a reason for hiding this comment

Bug: Supabase RPC Error Handling Flaws

Uh oh!

cursor bot Aug 13, 2025

Choose a reason for hiding this comment

Bug: Supabase Integration Errors: Exception Handling, Proxying, and Redundancy

Uh oh!

cursor bot Aug 13, 2025

Choose a reason for hiding this comment

Bug: Missing Mechanism Attributes in Exception Capture

Uh oh!

cursor bot Aug 13, 2025

Choose a reason for hiding this comment

Bug: RPC Observability Regression

Uh oh!

Uh oh!

onurtemizkan commented Mar 28, 2025 •

edited

Loading

github-actions bot commented Mar 28, 2025 •

edited

Loading