Draft PR: Effect Integration for Sentry Node SDK by Divyanshu7001 · Pull Request #17432 · getsentry/sentry-javascript

Divyanshu7001 · 2025-08-19T00:17:05Z

1. Goal

This PR adds support for tracing Effect computations in the Sentry Node SDK. The goal is to automatically create Sentry spans for Effect operations and capture errors that occur within Effect computations as Sentry exceptions, providing better observability for users of the Effect library.

2. Pathway Taken

Added a new integration (effectIntegration) and instrumentation (instrumentEffect) under @sentry/node.
Followed the robust test/mocking patterns from other integrations to ensure isolated, reliable tests.
Updated the SDK’s auto-integration and preload logic to include Effect.
Added the effect package as a dependency and provided type definitions for Effect’s tracer API.
Wrote comprehensive unit tests for the integration, covering all tracer hooks and error scenarios.

3. How the integration has happened and where it is included now

The integration is implemented in packages/node/src/integrations/tracing/effect/.
It is exported from the main SDK entrypoint and included in the auto-performance integrations list.
The SDK will now automatically register the Effect tracer if the Effect library is present in the user’s project.

4. How users should integrate Effect into their own project

Basic usage:

const Sentry = require('@sentry/node');

Sentry.init({
  dsn: 'YOUR_DSN',
  integrations: [
    Sentry.effectIntegration(),
    // ...other integrations
  ],
  // ...other options
});

Just add Sentry.effectIntegration() to your integrations array.
The SDK will automatically patch Effect’s tracer and start capturing spans and errors.
No manual instrumentation is required for most use cases.

5. Where am i stuck / need help

Some test cases are still flaky or failing due to mocking or module loading order (see attached images).

6. What is my thinking about these errors?

I think these errors are due to me not being able to setup the test environment properly as in most errors..the problem is just Span processes being undefined.
I would appreciate some pointers of where i am going wrong and how should i setup the test environment properly to test.

closes #17126

marbemac · 2025-09-08T18:36:28Z

Just a quick note - @Divyanshu7001 the auto formatting on your machine resulted in lots of unrelated files being changed that make it more difficult to digest this PR.

Divyanshu7001 · 2025-09-08T19:00:22Z

Just a quick note - @Divyanshu7001 the auto formatting on your machine resulted in lots of unrelated files being changed that make it more difficult to digest this PR.

I was afraid of the same thing & thats why used github codespaces with no local settings
but yes..i did run yarn fix to do all the linting fixes on the package level , which has caused this issue.😅
@marbemac would you prefer another PR without the linting fixes?
i can do that if that will suit things better.

all open for it.

s1gr1d · 2025-09-16T08:53:32Z

Thanks for creating this PR!
Can you please run fix:prettier from the root package.json? And also update the PR (merging or rebasing).

And to make sure we don't forget to review the PR you can assign e.g. me as a reviewer when you are ready.

marbemac

@Divyanshu7001, after actually looking at it, I don't understand how this is supposed to work. Most of the interfaces and methods used are not present in effect.

I created a custom effect tracer for Sentry over here, if you are interested -> https://github.com/marbemac/cloudflare-sentry-effect-tracing/blob/main/worker/effect-sentry-tracer.ts.

marbemac · 2025-09-16T14:31:33Z

packages/node/src/integrations/tracing/effect/types.ts

+  onSpanStart?: (span: EffectSpan) => void;
+  onSpanEnd?: (span: EffectSpan, exit: EffectExit) => void;


Where can you find this in effect?

marbemac · 2025-09-16T14:32:00Z

packages/node/src/integrations/tracing/effect/types.ts

+export interface EffectTracer {
+  onSpanStart?: (span: EffectSpan) => void;
+  onSpanEnd?: (span: EffectSpan, exit: EffectExit) => void;
+  span<A>(name: string, f: () => A): A;


The span method on custom tracers takes 6 args, not 2.

marbemac · 2025-09-16T14:32:13Z

packages/node/src/integrations/tracing/effect/types.ts

+  onSpanStart?: (span: EffectSpan) => void;
+  onSpanEnd?: (span: EffectSpan, exit: EffectExit) => void;
+  span<A>(name: string, f: () => A): A;
+  withSpan<A>(span: EffectSpan, f: () => A): A;


Where can you find this in the effect tracer interface?

marbemac · 2025-09-16T14:33:03Z

packages/node/src/integrations/tracing/effect/effectIntegration.ts

+      if (typeof Effect.Tracer.set === 'function') {
+        Effect.Tracer.set(sentryTracer);
+      } else if (typeof Effect.Tracer.register === 'function') {
+        Effect.Tracer.register(sentryTracer);
+      } else if (typeof Effect.Tracer.use === 'function') {
+        Effect.Tracer.use(sentryTracer);
+      } else {
+        return;
+      }


Where did you find these methods on the effect tracer? I do not think they exist.

Co-Authored-By: Jan Peer Stöcklmair <jan.peer@sentry.io>

sentry · 2026-02-05T10:18:29Z

packages/node/src/integrations/tracing/effect/effectIntegration.ts

+              name: span.name,
+              op: 'effect.span',
+              origin: 'auto.effect',
+              startTime: Number(span.startTime) / 1000000, // Convert nanoseconds to milliseconds


Bug: The Effect integration incorrectly converts span timestamps from nanoseconds to milliseconds instead of seconds, causing all reported span timings to be off by a factor of 1000.
_{Severity: HIGH}

Suggested Fix

Update the timestamp conversion logic to divide the nanosecond value by 1_000_000_000 to correctly convert it to seconds, which is the unit expected by the Sentry startSpan function. The line should be changed to startTime: Number(span.startTime) / 1_000_000_000.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not valid. Location: packages/node/src/integrations/tracing/effect/effectIntegration.ts#L85 Potential issue: The Effect integration converts span start times from nanoseconds to milliseconds by dividing the `BigInt` timestamp by `1,000,000`. However, the Sentry `startSpan` function expects a numeric timestamp to be in seconds. As a result, a timestamp representing 1 second (`1000` milliseconds) will be interpreted by Sentry as 1000 seconds. This will cause all span start times and durations to be reported incorrectly by a factor of 1000, making the tracing data unusable.

_{Did we get this right? 👍 / 👎 to inform future reviews.}

cursor

Cursor Bugbot has reviewed your changes and found 6 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

cursor · 2026-02-05T10:20:33Z

packages/node/src/integrations/tracing/effect/effectIntegration.ts

+                startTime: Number(span.startTime),
+                endTime: span.endTime ? Number(span.endTime) : undefined,
+              });
+              captureException(exit.cause);


Missing mechanism parameter in captureException calls

Medium Severity

The captureException calls at lines 50, 72, and 105 are missing the mechanism parameter with handled and type properties. Other integrations like connect.ts, express.ts, and fastify/index.ts properly include { mechanism: { handled: false, type: 'auto.middleware.connect' } }. The mechanism should use a type like 'auto.effect' to align with the span origin.

Additional Locations (2)

packages/node/src/integrations/tracing/effect/effectIntegration.ts#L71-L72

packages/node/src/integrations/tracing/effect/effectIntegration.ts#L104-L105

cursor · 2026-02-05T10:20:33Z

packages/node/src/integrations/tracing/effect/types.ts

+  onSpanStart?: (span: EffectSpan) => void;
+  onSpanEnd?: (span: EffectSpan, exit: EffectExit) => void;
+  span<A>(name: string, f: () => A): A;
+  withSpan<A>(span: EffectSpan, f: () => A): A;


Effect tracer interface method signatures are incorrect

High Severity

The EffectTracer type definitions don't match Effect's actual tracer API. PR reviewer @marbemac noted that the span method takes 6 arguments, not 2, and the withSpan method doesn't exist in Effect's tracer interface. The implementation in effectIntegration.ts uses these incorrect signatures, meaning the integration won't work correctly with the actual Effect library.

Additional Locations (1)

packages/node/src/integrations/tracing/effect/effectIntegration.ts#L58-L77

cursor · 2026-02-05T10:20:33Z

packages/node/src/integrations/tracing/effect/effectIntegration.ts

+
+                // Set status based on span status
+                if (span.status && span.status.code !== 0) {
+                  sentrySpan.setStatus('internal_error');


setStatus called with incorrect argument type

High Severity

The setStatus calls pass a plain string 'internal_error' but Span.setStatus() expects a SpanStatus object with code (number: 0, 1, or 2) and optional message properties. Other integrations in the codebase correctly use span.setStatus({ code: SPAN_STATUS_ERROR, message: 'internal_error' }). This will cause the span status to not be set correctly.

Additional Locations (1)

packages/node/src/integrations/tracing/effect/effectIntegration.ts#L101-L102

cursor · 2026-02-05T10:20:33Z

packages/node/src/integrations/tracing/effect/effectIntegration.ts

+                if (span.status && span.status.code !== 0) {
+                  sentrySpan.setStatus('internal_error');
+                  if (span.status.message) {
+                    sentrySpan.setData('effect.status_message', span.status.message);


setData method does not exist on Span

High Severity

The call to sentrySpan.setData('effect.status_message', span.status.message) uses a method that doesn't exist on the Span interface. The correct method is setAttribute. This will cause a runtime error when this code path is executed.

cursor · 2026-02-05T10:20:33Z

packages/node/src/integrations/tracing/effect/effectIntegration.ts

+              op: 'effect.span',
+              origin: 'auto.effect',
+              startTime: Number(span.startTime) / 1000000, // Convert nanoseconds to milliseconds
+              data: span.attributes,


Span attributes silently ignored due to wrong property name

Medium Severity

The startSpan call passes data: span.attributes but StartSpanOptions expects attributes, not data. This means the Effect span's attributes will be silently dropped and not transferred to the Sentry span, resulting in loss of trace context.

cursor · 2026-02-05T10:20:33Z

packages/node/src/integrations/tracing/effect/effectIntegration.ts

+            {
+              name,
+              op: 'effect.span',
+              origin: 'auto.effect',


Span origin ignored because passed as wrong property

Medium Severity

The origin: 'auto.effect' property is passed directly on the startSpan options object, but StartSpanOptions doesn't have an origin property. The origin must be set via attributes using SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN. All Effect spans will incorrectly have origin 'manual' instead of 'auto.effect'.

Additional Locations (1)

packages/node/src/integrations/tracing/effect/effectIntegration.ts#L83-L84

JPeer264 · 2026-02-05T10:26:02Z

Alright a little update here. I was now rebasing the PR so it is easier to review.

I had a quick look at it and given that we need to install "Effect" as a dependency gives me the signal that we might need to add our own sdk for it: @sentry/effect, which means that it is possible that this PR can't be merged as is (even though the tests would pass).

I'll clarify this or, latest, next week how we go forward with this PR.

Divyanshu7001 requested a review from a team as a code owner August 19, 2025 00:17

marbemac suggested changes Sep 16, 2025

View reviewed changes

billyvg removed the request for review from a team February 2, 2026 22:15

JPeer264 mentioned this pull request Feb 5, 2026

Add effectIntegration to Node SDK #17126

Open

feat(node): Add Effect integration for tracing Effect computations

194e173

Co-Authored-By: Jan Peer Stöcklmair <jan.peer@sentry.io>

JPeer264 force-pushed the feat/effect-integration branch from 66549ef to 194e173 Compare February 5, 2026 10:14

sentry bot reviewed Feb 5, 2026

View reviewed changes

cursor bot reviewed Feb 5, 2026

View reviewed changes

JPeer264 self-assigned this Feb 5, 2026

		onSpanStart?: (span: EffectSpan) => void;
		onSpanEnd?: (span: EffectSpan, exit: EffectExit) => void;

Uh oh!

Comments

Conversation

Divyanshu7001 commented Aug 19, 2025 • edited by JPeer264 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

1. Goal

2. Pathway Taken

3. How the integration has happened and where it is included now

4. How users should integrate Effect into their own project

5. Where am i stuck / need help

6. What is my thinking about these errors?

Uh oh!

marbemac commented Sep 8, 2025

Uh oh!

Divyanshu7001 commented Sep 8, 2025

Uh oh!

s1gr1d commented Sep 16, 2025

Uh oh!

marbemac left a comment

Choose a reason for hiding this comment

Uh oh!

marbemac Sep 16, 2025

Choose a reason for hiding this comment

Uh oh!

marbemac Sep 16, 2025

Choose a reason for hiding this comment

Uh oh!

marbemac Sep 16, 2025

Choose a reason for hiding this comment

Uh oh!

marbemac Sep 16, 2025

Choose a reason for hiding this comment

Uh oh!

sentry bot Feb 5, 2026

Choose a reason for hiding this comment

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor bot Feb 5, 2026

Choose a reason for hiding this comment

Missing mechanism parameter in captureException calls

Uh oh!

cursor bot Feb 5, 2026

Choose a reason for hiding this comment

Effect tracer interface method signatures are incorrect

Uh oh!

cursor bot Feb 5, 2026

Choose a reason for hiding this comment

setStatus called with incorrect argument type

Uh oh!

cursor bot Feb 5, 2026

Choose a reason for hiding this comment

setData method does not exist on Span

Uh oh!

cursor bot Feb 5, 2026

Choose a reason for hiding this comment

Span attributes silently ignored due to wrong property name

Uh oh!

cursor bot Feb 5, 2026

Choose a reason for hiding this comment

Span origin ignored because passed as wrong property

Uh oh!

JPeer264 commented Feb 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Divyanshu7001 commented Aug 19, 2025 •

edited by JPeer264

Loading