feat(core): Add Supabase Queues support #15921

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

Resolves: #14611

This PR adds Supabase Queues support to the Supabase

Sample Events: Link

Instrumented Operations

Producer operations (queue.publish):

send - Send a single message
send_batch - Send multiple messages

Consumer operations (queue.process):

pop - Read and delete message
read - Read message (with visibility timeout)
receive - Alias for read

Span Attributes

Follows OTEL Messaging Semantic Conventions and Sentry Queue Developer Docs:

messaging.destination.name - Queue name
messaging.message.id - Message ID (from msg_id)
messaging.message.retry.count - Retry count (from PGMQ's read_ct)
messaging.batch.message_count - Batch size for send_batch

Distributed Tracing

Producer spans inject sentry-trace and baggage into the message payload under _sentry key. Consumer spans create span links to the producer trace context.

Notes

Works with both client.rpc() and client.schema('pgmq_public').rpc() patterns
Queue operations are detected via RPC function names: send, send_batch, pop, read, receive
Empty consumer responses (no messages in queue) still create breadcrumbs and spans with messaging.batch.message_count: 0

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

size-limit report 📦

Path	Size	% Change	Change
@sentry/browser	24.8 kB	-	-
@sentry/browser - with treeshaking flags	23.31 kB	-	-
@sentry/browser (incl. Tracing)	41.54 kB	-	-
@sentry/browser (incl. Tracing, Profiling)	46.13 kB	-	-
@sentry/browser (incl. Tracing, Replay)	79.96 kB	-	-
@sentry/browser (incl. Tracing, Replay) - with treeshaking flags	69.69 kB	-	-
@sentry/browser (incl. Tracing, Replay with Canvas)	84.64 kB	-	-
@sentry/browser (incl. Tracing, Replay, Feedback)	96.88 kB	-	-
@sentry/browser (incl. Feedback)	41.48 kB	-	-
@sentry/browser (incl. sendFeedback)	29.49 kB	-	-
@sentry/browser (incl. FeedbackAsync)	34.47 kB	-	-
@sentry/react	26.52 kB	-	-
@sentry/react (incl. Tracing)	43.74 kB	-	-
@sentry/vue	29.25 kB	-	-
@sentry/vue (incl. Tracing)	43.34 kB	-	-
@sentry/svelte	24.82 kB	-	-
CDN Bundle	27.21 kB	-	-
CDN Bundle (incl. Tracing)	42.21 kB	-	-
CDN Bundle (incl. Tracing, Replay)	78.75 kB	-	-
CDN Bundle (incl. Tracing, Replay, Feedback)	84.2 kB	-	-
CDN Bundle - uncompressed	79.96 kB	-	-
CDN Bundle (incl. Tracing) - uncompressed	125.34 kB	-	-
CDN Bundle (incl. Tracing, Replay) - uncompressed	241.37 kB	-	-
CDN Bundle (incl. Tracing, Replay, Feedback) - uncompressed	254.13 kB	-	-
@sentry/nextjs (client)	45.96 kB	-	-
@sentry/sveltekit (client)	41.9 kB	-	-
@sentry/node-core	51.27 kB	-0.01%	-2 B 🔽
@sentry/node	159.53 kB	-	-
@sentry/node - without tracing	92.85 kB	-	-
@sentry/aws-serverless	108.14 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

cursor · 2025-12-09T10:33:11Z

packages/core/src/integrations/supabase.ts

+        if (traceparentData?.traceId && traceparentData?.parentSpanId) {
+          // Convert parentSampled boolean to traceFlags (W3C trace context spec)
+          // traceFlags bit 0 (LSB) = sampled flag: 1 if sampled, 0 if not sampled
+          const traceFlags = traceparentData.parentSampled ? 1 : 0;


Bug: Undefined parentSampled incorrectly converted to "not sampled"

When extracting producer trace context for span links, the code converts parentSampled to traceFlags using traceparentData.parentSampled ? 1 : 0. If parentSampled is undefined (meaning sampling decision was deferred/not yet made), this expression incorrectly sets traceFlags to 0 (not sampled). Per W3C trace context spec, undefined sampling state is semantically different from "not sampled". This could affect trace propagation for deferred sampling scenarios, though the impact is limited to span link attributes.

cursor · 2025-12-09T10:33:11Z

packages/core/src/integrations/supabase.ts

+              scope.addEventProcessor(e => {
+                addExceptionMechanism(e, {
+                  handled: false,
+                  type: 'auto.db.supabase.rpc',


Bug: Mechanism types don't align with span origins per rules (Bugbot Rules)

Per the user's review rules, captureException mechanism types must align with the wrapping span's SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN. Multiple mismatches exist: generic RPC uses mechanism 'auto.db.supabase.rpc' but span origin 'auto.db.supabase'; queue operations use mechanism 'auto.db.supabase.queue' but origins are 'auto.db.supabase.queue.producer' and 'auto.db.supabase.queue.consumer'; auth uses mechanism 'auto.db.supabase.auth' but origin 'auto.db.supabase'; PostgREST uses mechanism 'auto.db.supabase.postgres' but origin 'auto.db.supabase'. Flagged because the rules file specifies mechanism types should match span origins.

Additional Locations (2)

packages/core/src/integrations/supabase.ts#L1131-L1132

packages/core/src/integrations/supabase.ts#L1222-L1223

packages/core/src/integrations/supabase.ts

+
+/**
+ * Instruments Supabase auth operations.
+ *
+ * Creates auto.db.supabase spans for auth operations (signIn, signUp, etc.)
+ * to track authentication performance and errors.
+ */
+function _instrumentAuthOperation(operation: AuthOperationFn, isAdmin = false): AuthOperationFn {
  return new Proxy(operation, {
    apply(target, thisArg, argumentsList) {
      return startSpan(


…mentation

onurtemizkan · 2025-12-09T17:17:49Z

@AbhiPrasad, @Lms24, can I have another round of reviews on this, please? I updated the sample events in the PR description.

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 AbhiPrasad and Lms24 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

cursor bot reviewed Dec 9, 2025

View reviewed changes

sentry bot reviewed Dec 9, 2025

View reviewed changes

onurtemizkan added 26 commits December 9, 2025 15:26

feat(core): Add Supabase Queues support

f7c3918

Skip tests on bundles

359783d

Update test usage

483e965

Lint

1680b7d

Update implementation

fc78519

Update playwright tests

5533ae1

Tidy up test endpoints

84e22ee

Refactor / reimplement

11b06a3

Add missing import

6fce369

Rename SupabaseClientConstructor to SupabaseClientConstructorType

1705876

Extract instrumentRpcMethod

9b458f6

WIP

f3a22a0

Match with OTEL semantics improve tests

852a236

Add OTEL operation attributes to queue spans

157a39c

Fix browser integration tests

29ee5a0

Improve data integrity and distributed tracing

068661b

Use span links for consumer distributed tracing, fix prototype instru…

1992f4d

…mentation

Fix mutation and safety issues, ignore, empty queue consumers

f795cb3

Simplify queue spans and fix missing span.end() calls

dc33d2c

Re-address review comments

96e41a5

Address review comments

7486518

Fix linter

36ecce5

Add array check for messages from params

1511cf2

Remove rethrowing errors

e957e7f

Use OTEL-compliant messaging.batch.message_count attribute.

8298d8d

Add missing telemetry for empty Supabase queue consumer responses

608b31d

onurtemizkan force-pushed the onur/supabase-queues branch from c3e2644 to 608b31d Compare December 9, 2025 15:26

		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

Conversation

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

Uh oh!

Instrumented Operations

Span Attributes

Distributed Tracing

Notes

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!

cursor bot Dec 9, 2025

Choose a reason for hiding this comment

Bug: Undefined parentSampled incorrectly converted to "not sampled"

Uh oh!

cursor bot Dec 9, 2025

Choose a reason for hiding this comment

Bug: Mechanism types don't align with span origins per rules (Bugbot Rules)

Uh oh!

This comment was marked as outdated.

Uh oh!

onurtemizkan commented Dec 9, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

onurtemizkan commented Mar 28, 2025 •

edited

Loading

github-actions bot commented Mar 28, 2025 •

edited

Loading

Bug: Undefined `parentSampled` incorrectly converted to "not sampled"