ref(nextjs): Drop the proxy-only request span with ignoreSpans

Instead of enforcing the `beforeSampling` decision in core, add a
`beforeSpanStart` hook that runs right before `ignoreSpans` is checked and
can change the name and attributes of a span. The Next.js SDK uses it to mark
the request span that only runs the proxy with `sentry.drop_transaction`,
which the existing Next.js `ignoreSpans` pattern drops.

Refs #25370
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Author: Lms24

packages/core/src/client.ts

@@ -677,6 +677,16 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
     callback: (spanScope: { scope: Scope; parentSpan: Span | undefined }) => void,
   ): () => void;
 
+  /**
+   * Register a callback right before a span is created, before `ignoreSpans` is checked. Listeners can change the
+   * name and the attributes of the span by mutating the passed `spanStartData` object.
+   * @returns {() => void} A function that, when executed, removes the registered callback.
+   */
+  public on(
+    hook: 'beforeSpanStart',
+    callback: (spanStartData: { name: string | undefined; attributes: SpanAttributes }) => void,
+  ): () => void;
+
   /**
    * Register a callback before span sampling runs. Receives a `samplingDecision` object argument with a `decision`
    * property that can be used to make a sampling decision that will be enforced, before any span sampling runs.
@@ -1038,6 +1048,9 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
   /** A hook that is called right before a span is created; listeners mutate the passed object. */
   public emit(hook: 'prepareSpanScope', spanScope: { scope: Scope; parentSpan: Span | undefined }): void;
 
+  /** A hook that is called right before a span is created, before `ignoreSpans` is checked. */
+  public emit(hook: 'beforeSpanStart', spanStartData: { name: string | undefined; attributes: SpanAttributes }): void;
+
   /** A hook that is called every time before a span is sampled. */
   public emit(
     hook: 'beforeSampling',

packages/core/src/tracing/trace.ts

@@ -362,6 +362,12 @@ function createChildOrRootSpan({
   }
 
   const client = getClient();
+  // Copy the attributes, so listeners do not mutate an object the caller passed in
+  const spanStartData = { name: spanArguments.name, attributes: { ...spanArguments.attributes } };
+  client?.emit('beforeSpanStart', spanStartData);
+  spanArguments.name = spanStartData.name;
+  spanArguments.attributes = spanStartData.attributes;
+
   if (_shouldIgnoreStreamedSpan(client, spanArguments)) {
     if (!isTracingSuppressed(scope)) {
       // if tracing is actively suppressed (Sentry.suppressTracing(...)),
@@ -490,10 +496,8 @@ function _startRootSpan(
 
   const mutableSpanSamplingData = { spanAttributes: { ...spanArguments.attributes }, spanName: name, parentSampled };
 
-  const samplingDecision = { decision: true };
-  client?.emit('beforeSampling', mutableSpanSamplingData, samplingDecision);
-  // Like suppressed tracing, a span dropped by a hook is SDK-internal and records no client outcome
-  const _isDroppedBeforeSampling = !samplingDecision.decision;
+  // we don't care about the decision for the moment; this is just a placeholder
+  client?.emit('beforeSampling', mutableSpanSamplingData, { decision: false });
 
   // If hook consumers override the parentSampled flag, we will use that value instead of the actual one
   const finalParentSampled = mutableSpanSamplingData.parentSampled ?? parentSampled;
@@ -502,20 +506,19 @@ function _startRootSpan(
   const currentPropagationContext = scope.getPropagationContext();
   const _isTracingSuppressed = isTracingSuppressed(scope);
 
-  const [sampled, sampleRate, localSampleRateWasApplied, dropReason] =
-    _isTracingSuppressed || _isDroppedBeforeSampling
-      ? [false]
-      : sampleSpan(
-          options,
-          {
-            name,
-            parentSampled: finalParentSampled,
-            attributes: finalAttributes,
-            normalizedRequest: isolationScope.getScopeData().sdkProcessingMetadata.normalizedRequest,
-            parentSampleRate: parseSampleRate(currentPropagationContext.dsc?.sample_rate),
-          },
-          currentPropagationContext.sampleRand,
-        );
+  const [sampled, sampleRate, localSampleRateWasApplied, dropReason] = _isTracingSuppressed
+    ? [false]
+    : sampleSpan(
+        options,
+        {
+          name,
+          parentSampled: finalParentSampled,
+          attributes: finalAttributes,
+          normalizedRequest: isolationScope.getScopeData().sdkProcessingMetadata.normalizedRequest,
+          parentSampleRate: parseSampleRate(currentPropagationContext.dsc?.sample_rate),
+        },
+        currentPropagationContext.sampleRand,
+      );
 
   const rootSpan = new SentrySpan({
     ...spanArguments,
@@ -528,7 +531,7 @@ function _startRootSpan(
     sampled,
   });
 
-  if (!sampled && client && !_isTracingSuppressed && !_isDroppedBeforeSampling) {
+  if (!sampled && client && !_isTracingSuppressed) {
     DEBUG_BUILD && debug.log('[Tracing] Discarding root span because its trace was not chosen to be sampled.');
     const outcomeReason = dropReason || 'sample_rate';
     // A standalone span is sent on its own and never becomes a transaction.

packages/core/test/lib/tracing/trace.test.ts

@@ -2717,6 +2717,51 @@ describe('ignoreSpans (core path, streaming)', () => {
     });
   });
 
+  it('ignores a span that a beforeSpanStart listener marks for ignoreSpans', () => {
+    const options = getDefaultTestClientOptions({
+      tracesSampleRate: 1,
+      traceLifecycle: 'stream',
+      ignoreSpans: [{ attributes: { 'test.ignore': true } }],
+    });
+    client = new TestClient(options);
+    setCurrentClient(client);
+    client.init();
+    const spyOnDroppedEvent = vi.spyOn(client, 'recordDroppedEvent');
+    client.on('beforeSpanStart', ({ name, attributes }) => {
+      if (name === 'GET') {
+        attributes['test.ignore'] = true;
+      }
+    });
+
+    startSpan({ name: 'GET' }, span => {
+      expect(span).toBeInstanceOf(SentryNonRecordingSpan);
+    });
+    startSpan({ name: 'GET /users' }, span => {
+      expect(span).toBeInstanceOf(SentrySpan);
+    });
+
+    expect(spyOnDroppedEvent).toHaveBeenCalledTimes(1);
+    expect(spyOnDroppedEvent).toHaveBeenCalledWith('ignored', 'span');
+  });
+
+  it('applies the changes of beforeSpanStart listeners without mutating the attributes passed in', () => {
+    const options = getDefaultTestClientOptions({ tracesSampleRate: 1 });
+    client = new TestClient(options);
+    setCurrentClient(client);
+    client.init();
+    client.on('beforeSpanStart', spanStartData => {
+      spanStartData.name = 'renamed';
+      spanStartData.attributes['test.added'] = 'yes';
+    });
+
+    const attributes = { 'test.original': 'yes' };
+    const span = startInactiveSpan({ name: 'original', attributes });
+
+    expect(spanToJSON(span).name).toBe('renamed');
+    expect(spanToJSON(span).attributes).toMatchObject({ 'test.original': 'yes', 'test.added': 'yes' });
+    expect(attributes).toEqual({ 'test.original': 'yes' });
+  });
+
   it('returns SentryNonRecordingSpan for startInactiveSpan matching ignoreSpans', () => {
     const options = getDefaultTestClientOptions({
       tracesSampleRate: 1,
@@ -2788,26 +2833,6 @@ describe('ignoreSpans (core path, streaming)', () => {
     expect(spyOnDroppedEvent).toHaveBeenNthCalledWith(2, 'sample_rate', 'span');
   });
 
-  it('does not record a root span that a beforeSampling hook drops, nor an outcome for it', () => {
-    const options = getDefaultTestClientOptions({
-      tracesSampleRate: 1,
-      traceLifecycle: 'stream',
-    });
-    client = new TestClient(options);
-    setCurrentClient(client);
-    client.init();
-    client.on('beforeSampling', (_samplingData, samplingDecision) => {
-      samplingDecision.decision = false;
-    });
-    const spyOnDroppedEvent = vi.spyOn(client, 'recordDroppedEvent');
-
-    startSpan({ name: 'GET /foo' }, span => {
-      expect(spanIsSampled(span)).toBe(false);
-    });
-
-    expect(spyOnDroppedEvent).not.toHaveBeenCalled();
-  });
-
   it('records sample_rate outcomes for the transaction and all of its spans on static path', () => {
     const options = getDefaultTestClientOptions({
       tracesSampleRate: 0,

packages/nextjs/src/server/serverSpanHooks.ts

@@ -83,9 +83,11 @@ export function addNextjsServerSpanHooks(client: Client): void {
     ) {
       samplingDecision.decision = false;
     }
+  });
 
-    if (isProxyInvocationSpan(spanAttributes)) {
-      samplingDecision.decision = false;
+  client.on('beforeSpanStart', ({ attributes }) => {
+    if (isProxyInvocationSpan(attributes)) {
+      attributes[TRANSACTION_ATTR_SHOULD_DROP_TRANSACTION] = true;
     }
   });
 
@@ -134,9 +136,8 @@ function isProxyInvocationSpan(spanAttributes: Record<string, unknown>): boolean
   }
 
   // Next.js sets this flag on the request before the call that only runs the proxy, and resets it before rendering
-  const request = _INTERNAL_getIncomingRequestForScope(getIsolationScope()) as
-    | { [NEXT_REQUEST_META]?: { middlewareInvoke?: boolean } }
-    | undefined;
+  const request: { [NEXT_REQUEST_META]?: { middlewareInvoke?: boolean } } | undefined =
+    _INTERNAL_getIncomingRequestForScope(getIsolationScope());
   return request?.[NEXT_REQUEST_META]?.middlewareInvoke === true;
 }
 

packages/nextjs/test/server/serverSpanHooks.test.ts

@@ -6,18 +6,23 @@ import {
   SENTRY_SEGMENT_NAME_SOURCE,
 } from '@sentry/conventions/attributes';
 import { MIDDLEWARE } from '@sentry/conventions/op';
-import type { Client } from '@sentry/core';
+import type { Client, SpanAttributes } from '@sentry/core';
 import {
   _INTERNAL_setIncomingRequestForScope,
   addChildSpanToSpan,
   GLOBAL_OBJ,
   SentrySpan,
+  shouldIgnoreSpan,
   spanToStaticSpanJSON,
   withIsolationScope,
 } from '@sentry/core';
 import { afterEach, describe, expect, it } from 'vitest';
 import { ATTR_NEXT_SPAN_NAME, ATTR_NEXT_SPAN_TYPE } from '../../src/common/nextSpanAttributes';
-import { addNextjsServerSpanHooks, handleOnSpanStart } from '../../src/server/serverSpanHooks';
+import {
+  addNextjsServerSpanHooks,
+  handleOnSpanStart,
+  NEXTJS_SERVER_IGNORE_SPANS,
+} from '../../src/server/serverSpanHooks';
 
 const client = { getOptions: () => ({}) } as unknown as Client;
 
@@ -179,51 +184,51 @@ describe('handleOnSpanStart', () => {
   });
 });
 
-describe('addNextjsServerSpanHooks beforeSampling', () => {
+describe('addNextjsServerSpanHooks beforeSpanStart', () => {
   const globalWithInjectedValues = GLOBAL_OBJ as typeof GLOBAL_OBJ & { _sentryNextJsVersion?: string };
 
   afterEach(() => {
     delete globalWithInjectedValues._sentryNextJsVersion;
   });
 
-  function getSamplingDecision(nextVersion: string | undefined, middlewareInvoke: boolean | undefined): boolean {
+  function isRequestSpanIgnored(nextVersion: string | undefined, middlewareInvoke: boolean | undefined): boolean {
     globalWithInjectedValues._sentryNextJsVersion = nextVersion;
 
-    let beforeSampling: ((data: unknown, decision: { decision: boolean }) => void) | undefined;
+    let beforeSpanStart: ((data: { name: string | undefined; attributes: SpanAttributes }) => void) | undefined;
     addNextjsServerSpanHooks({
-      on: (hook: string, callback: typeof beforeSampling) => {
-        if (hook === 'beforeSampling') {
-          beforeSampling = callback;
+      on: (hook: string, callback: typeof beforeSpanStart) => {
+        if (hook === 'beforeSpanStart') {
+          beforeSpanStart = callback;
         }
       },
       getOptions: () => ({}),
     } as unknown as Client);
 
     const request = { [Symbol.for('NextInternalRequestMeta')]: { middlewareInvoke } };
-    const samplingDecision = { decision: true };
+    const spanStartData = { name: 'GET', attributes: { [ATTR_NEXT_SPAN_TYPE]: 'BaseServer.handleRequest' } };
     withIsolationScope(isolationScope => {
       _INTERNAL_setIncomingRequestForScope(isolationScope, request);
-      beforeSampling?.(
-        { spanAttributes: { [ATTR_NEXT_SPAN_TYPE]: 'BaseServer.handleRequest' }, spanName: 'GET' },
-        samplingDecision,
-      );
+      beforeSpanStart?.(spanStartData);
     });
-    return samplingDecision.decision;
+    return shouldIgnoreSpan(
+      { description: spanStartData.name, attributes: spanStartData.attributes },
+      NEXTJS_SERVER_IGNORE_SPANS,
+    );
   }
 
-  it('drops the request span that Next.js only starts to run the proxy', () => {
-    expect(getSamplingDecision('16.3.0', true)).toBe(false);
+  it('ignores the request span that Next.js only starts to run the proxy', () => {
+    expect(isRequestSpanIgnored('16.3.0', true)).toBe(true);
   });
 
   it('keeps the request span that renders the route', () => {
-    expect(getSamplingDecision('16.3.0', false)).toBe(true);
+    expect(isRequestSpanIgnored('16.3.0', false)).toBe(false);
   });
 
   it('keeps the request span that runs the proxy before Next.js 16.3, since the proxy span is its child there', () => {
-    expect(getSamplingDecision('16.2.4', true)).toBe(true);
+    expect(isRequestSpanIgnored('16.2.4', true)).toBe(false);
   });
 
   it('keeps the request span that runs the proxy if the Next.js version is unknown', () => {
-    expect(getSamplingDecision(undefined, true)).toBe(true);
+    expect(isRequestSpanIgnored(undefined, true)).toBe(false);
   });
 });