feat(effect): Add opt-in for external span parents and isolate root spans (#23900)

`@sentry/effect` parented every Effect span on the active Sentry span. A
`Tracer.ExternalSpan` parent was dropped, so a persisted trace continued
with `Tracer.externalSpan` started a disconnected trace, and a `root:
true` span or a span leaked from another fiber through the async context
could become the parent of an unrelated span. On the server, every
parentless span also shared the process-wide propagation context, so a
long-lived process put all of its work into one trace.

- A parentless span only nests under a foreign active Sentry span (an
`http.server` span from the Node SDK, a pageload), never under a span
this tracer created.
- The server tracer starts a new trace for every parentless span, unless
the user set up the current scope (`continueTrace`, `withScope`, an
isolation scope). The client tracer keeps parentless spans in the page
trace.
- An external parent is ignored by default, and the span nests where
Effect would have put it without the `parent` option: under the fiber's
current span, or parentless.
- The new `SentryEffectExternalSpanLayer` opts into continuing external
parents: the span becomes a new root span with the external span as
`parent_span_id`. No dynamic sampling context is frozen, so the SDK
builds one from the client. Next to the tracer layer it applies to the
whole runtime, with `Effect.provide` to a single effect only there.

### Decisions

**External parents are opt-in.** A `Tracer.externalSpan` parent bridges
a trace the SDK did not start, for example an OpenTelemetry span of
another app in the same process, or trace state persisted with a queue
message. Joining such a trace silently would re-parent spans into a
trace the SDK cannot vouch for, so the user adds the layer to ask for
it. Incoming trace headers on the Effect HTTP server are out of scope
here and get their own PR.

**The opt-in is a layer, not a second tracer.** Two layers that set the
tracer race inside `Layer.mergeAll`, and a wrapping tracer only sees the
Sentry one when nested with `Layer.provide`. A flag in the fiber context
composes in `Layer.mergeAll` like `Layer.setTracer` does, and also works
per effect. It is a plain service in both Effect versions, because v4
has no `FiberRef` and v3 has no `Context.Reference`.

**How the tracer reads the flag.** Effect's `span` hook gets no fiber in
either version, only the span's own context or annotations. The
`context` hook does get the fiber and wraps every operation the fiber
evaluates, and `span` runs synchronously inside it, so the hook keeps
the fiber in a module variable for that extent, the same way it already
sets the active Sentry span there. The flag is read only when an
external parent shows up.

These fixes apply to both trace lifecycles. One related limitation stays
and is specific to `traceLifecycle: 'static'`: a child span that ends
after its root span is dropped with the transaction. Long-running Effect
fibers, such as a background agent that outlives the request that
started it, lose those children unless `traceLifecycle: 'stream'` is
used, which sends every span on its own end and is the default since
v11.

The effect-3-node and effect-4-node e2e apps cover a
`Tracer.externalSpan` parent continued through the layer and a `root:
true` span inside a request.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: JPeer264

dev-packages/e2e-tests/test-applications/effect-3-node/src/app.ts

@@ -6,6 +6,7 @@ import * as Cause from 'effect/Cause';
 import * as Layer from 'effect/Layer';
 import * as Logger from 'effect/Logger';
 import * as LogLevel from 'effect/LogLevel';
+import * as Tracer from 'effect/Tracer';
 import { createServer } from 'http';
 
 const SentryLive = Layer.mergeAll(
@@ -42,6 +43,31 @@ const router = HttpRouter.empty.pipe(
     }),
   ),
 
+  HttpRouter.get(
+    '/test-root-span',
+    Effect.gen(function* () {
+      yield* Effect.void.pipe(Effect.withSpan('root-span-request-marker'));
+      yield* Effect.sleep('10 millis').pipe(Effect.withSpan('detached-root-span', { root: true }));
+      return yield* HttpServerResponse.json({ status: 'ok' });
+    }),
+  ),
+
+  HttpRouter.get(
+    '/test-external-parent',
+    Effect.gen(function* () {
+      yield* Effect.sleep('10 millis').pipe(
+        Effect.withSpan('continued-span', {
+          parent: Tracer.externalSpan({
+            traceId: 'fedcba0987654321fedcba0987654321',
+            spanId: '0987654321fedcba',
+            sampled: true,
+          }),
+        }),
+      );
+      return yield* HttpServerResponse.json({ status: 'ok' });
+    }).pipe(Effect.provide(Sentry.SentryEffectExternalSpanLayer)),
+  ),
+
   HttpRouter.get(
     '/test-error',
     Effect.gen(function* () {

dev-packages/e2e-tests/test-applications/effect-3-node/tests/spans.test.ts

@@ -65,3 +65,41 @@ test('Sends Effect spans with correct parent-child structure', async ({ baseURL
     expect(child.trace_id).toBe(segment.trace_id);
   }
 });
+
+test('Sends a root: true span as its own segment in a new trace', async ({ baseURL }) => {
+  const requestSpansPromise = collectStreamedSpans(
+    'effect-3-node',
+    spans =>
+      spans.some(
+        span =>
+          span.is_segment &&
+          getSpanOp(span) === 'http.server' &&
+          span.attributes['url.path']?.value === '/test-root-span',
+      ) && spans.some(span => span.name === 'root-span-request-marker'),
+  );
+  const detachedSpanPromise = waitForStreamedSpan('effect-3-node', span => span.name === 'detached-root-span');
+
+  await fetch(`${baseURL}/test-root-span`);
+
+  const [requestSpans, detachedSpan] = await Promise.all([requestSpansPromise, detachedSpanPromise]);
+  const segment = requestSpans.find(span => span.is_segment && getSpanOp(span) === 'http.server')!;
+  expect(segment.name).toBe('http.server GET');
+  expect(requestSpans.filter(span => !span.is_segment).map(span => span.name)).toEqual(['root-span-request-marker']);
+
+  expect(detachedSpan.is_segment).toBe(true);
+  expect(detachedSpan.parent_span_id).toBeUndefined();
+  expect(detachedSpan.trace_id).not.toBe(segment.trace_id);
+});
+
+test('Continues the trace of a Tracer.externalSpan parent with the external span layer', async ({ baseURL }) => {
+  const spanPromise = waitForStreamedSpan('effect-3-node', span => span.name === 'continued-span');
+
+  await fetch(`${baseURL}/test-external-parent`);
+
+  const span = await spanPromise;
+  expect(span).toMatchObject({
+    is_segment: true,
+    trace_id: 'fedcba0987654321fedcba0987654321',
+    parent_span_id: '0987654321fedcba',
+  });
+});

dev-packages/e2e-tests/test-applications/effect-4-node/src/app.ts

@@ -101,6 +101,33 @@ const Routes = Layer.mergeAll(
     }),
   ),
 
+  HttpRouter.add(
+    'GET',
+    '/test-root-span',
+    Effect.gen(function* () {
+      yield* Effect.void.pipe(Effect.withSpan('root-span-request-marker'));
+      yield* Effect.sleep('10 millis').pipe(Effect.withSpan('detached-root-span', { root: true }));
+      return yield* HttpServerResponse.json({ status: 'ok' });
+    }),
+  ),
+
+  HttpRouter.add(
+    'GET',
+    '/test-external-parent',
+    Effect.gen(function* () {
+      yield* Effect.sleep('10 millis').pipe(
+        Effect.withSpan('continued-span', {
+          parent: Tracer.externalSpan({
+            traceId: 'fedcba0987654321fedcba0987654321',
+            spanId: '0987654321fedcba',
+            sampled: true,
+          }),
+        }),
+      );
+      return yield* HttpServerResponse.json({ status: 'ok' });
+    }).pipe(Effect.provide(Sentry.SentryEffectExternalSpanLayer)),
+  ),
+
   HttpRouter.add(
     'GET',
     '/test-error',

dev-packages/e2e-tests/test-applications/effect-4-node/tests/spans.test.ts

@@ -65,3 +65,41 @@ test('Sends Effect spans with correct parent-child structure', async ({ baseURL
     expect(child.trace_id).toBe(segment.trace_id);
   }
 });
+
+test('Sends a root: true span as its own segment in a new trace', async ({ baseURL }) => {
+  const requestSpansPromise = collectStreamedSpans(
+    'effect-4-node',
+    spans =>
+      spans.some(
+        span =>
+          span.is_segment &&
+          getSpanOp(span) === 'http.server' &&
+          span.attributes['url.path']?.value === '/test-root-span',
+      ) && spans.some(span => span.name === 'root-span-request-marker'),
+  );
+  const detachedSpanPromise = waitForStreamedSpan('effect-4-node', span => span.name === 'detached-root-span');
+
+  await fetch(`${baseURL}/test-root-span`);
+
+  const [requestSpans, detachedSpan] = await Promise.all([requestSpansPromise, detachedSpanPromise]);
+  const segment = requestSpans.find(span => span.is_segment && getSpanOp(span) === 'http.server')!;
+  expect(segment.name).toBe('http.server GET');
+  expect(requestSpans.filter(span => !span.is_segment).map(span => span.name)).toEqual(['root-span-request-marker']);
+
+  expect(detachedSpan.is_segment).toBe(true);
+  expect(detachedSpan.parent_span_id).toBeUndefined();
+  expect(detachedSpan.trace_id).not.toBe(segment.trace_id);
+});
+
+test('Continues the trace of a Tracer.externalSpan parent with the external span layer', async ({ baseURL }) => {
+  const spanPromise = waitForStreamedSpan('effect-4-node', span => span.name === 'continued-span');
+
+  await fetch(`${baseURL}/test-external-parent`);
+
+  const span = await spanPromise;
+  expect(span).toMatchObject({
+    is_segment: true,
+    trace_id: 'fedcba0987654321fedcba0987654321',
+    parent_span_id: '0987654321fedcba',
+  });
+});

packages/effect/src/client/tracer.ts

@@ -8,4 +8,4 @@ import { makeSentryTracer } from '../tracer';
  * keeps the browser variant substitutable (mocks, bundler interop) exactly as it was when the tracer
  * called it directly.
  */
-export const SentryEffectTracer = makeSentryTracer(options => startInactiveSpan(options));
+export const SentryEffectTracer = makeSentryTracer(options => startInactiveSpan(options), false);

packages/effect/src/index.client.ts

@@ -7,5 +7,6 @@ export { effectLayer, init } from './client/index';
 export type { EffectClientLayerOptions } from './client/index';
 
 export { SentryEffectTracer } from './client/tracer';
+export { SentryEffectExternalSpanLayer } from './tracer';
 export { SentryEffectLogger } from './logger';
 export { SentryEffectMetricsLayer } from './metrics';

packages/effect/src/index.server.ts

@@ -4,5 +4,6 @@ export { effectLayer, init } from './server/index';
 export type { EffectServerLayerOptions } from './server/index';
 
 export { SentryEffectTracer } from './server/tracer';
+export { SentryEffectExternalSpanLayer } from './tracer';
 export { SentryEffectLogger } from './logger';
 export { SentryEffectMetricsLayer } from './metrics';

packages/effect/src/server/tracer.ts

@@ -8,6 +8,10 @@ import { makeSentryTracer } from '../tracer';
  * every span start with a `getClient()` lookup to lazily install `spanStreamingIntegration`, which on
  * the server is pure overhead — `ServerRuntimeClient` already installs it eagerly.
  *
+ * Every parentless Effect span starts a new trace. A server process forks no propagation context on
+ * its own, so without this every request, reactor and background job of the process would land in
+ * one trace.
+ *
  * See `./client/tracer.ts` for why the call is wrapped in an arrow.
  */
-export const SentryEffectTracer = makeSentryTracer(options => startInactiveSpan(options));
+export const SentryEffectTracer = makeSentryTracer(options => startInactiveSpan(options), true);