feat(core): Deprecate beforeSendTransaction and ignoreTransactions and log warnings if used with streaming (#22908)

This PR:

1. Deprecates `beforeSendTransaction` and `ignoreTransactions`
2. Logs a console warning (intentionally not gated with `debug: true`)
to warn users if they use any of the two options with span streaming
enabled

I intentionally didn't update the migration guide. this is handled in
#22643.

more details in
#22856

closes #22856
closes #20279

Author: Lms24

.size-limit.js

@@ -286,7 +286,7 @@ module.exports = [
     path: createCDNPath('bundle.logs.metrics.min.js'),
     gzip: false,
     brotli: false,
-    limit: '100 KB',
+    limit: '101 KB',
     disablePlugins: ['@size-limit/esbuild'],
   },
   {

AGENTS.md

@@ -134,6 +134,8 @@ Uses **Git Flow** (see `docs/gitflow.md`).
 - Never expose secrets or keys
 - When modifying files, cover all occurrences (including `src/` and `test/`)
 - Comments explain **why**, never **what** — never add a comment that restates what the code does or describes the change being made; only comment when the reasoning isn't obvious from the code itself
+- Do not use `expect(someSpy.mock.calls[0]?.[0])` or similar constructs to check what a spy was called with.
+  Instead use `expect(someSpy).toHaveBeenCalledWith(...)` or derivatives for a more readable and less brittle test assertion.
 
 ## Lazy Loading Is a Last Resort
 

packages/bundler-plugins/src/core/sentry/telemetry.ts

@@ -45,6 +45,8 @@ export function createSentryInstance(
       return event;
     },
 
+    // Deprecated, but still applied because this client runs on the static trace lifecycle.
+    // oxlint-disable-next-line typescript/no-deprecated
     beforeSendTransaction: event => {
       delete event.server_name; // Server name might contain PII
       return event;

packages/core/src/client.ts

@@ -54,6 +54,7 @@ import { reparentChildSpans, shouldIgnoreSpan } from './utils/should-ignore-span
 import { showSpanDropWarning } from './utils/spanUtils';
 import { safeUnref } from './utils/timer';
 import { convertSpanJsonToTransactionEvent, convertTransactionEventToSpanJson } from './utils/transactionEvent';
+import { maybeWarnAboutIgnoredTransactionOptions } from './utils/warnAboutIgnoredTransactionOptions';
 import { resolveDataCollectionOptions } from './utils/data-collection/resolveDataCollectionOptions';
 
 const ALREADY_SEEN_ERROR = "Not capturing exception because it's already been captured.";
@@ -507,6 +508,8 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
       this._options.integrations.some(({ name }) => name.startsWith('Spotlight'))
     ) {
       this._setupIntegrations();
+
+      maybeWarnAboutIgnoredTransactionOptions(this._options);
     }
   }
 
@@ -1653,7 +1656,12 @@ function processBeforeSend(
   event: Event,
   hint: EventHint,
 ): PromiseLike<Event | null> | Event | null {
-  const { beforeSend, beforeSendTransaction, ignoreSpans } = options;
+  const {
+    beforeSend,
+    ignoreSpans,
+    // oxlint-disable-next-line typescript/no-deprecated
+    beforeSendTransaction,
+  } = options;
   const beforeSendSpan = !isStreamedBeforeSendSpanCallback(options.beforeSendSpan) && options.beforeSendSpan;
 
   let processedEvent = event;

packages/core/src/types/options.ts

@@ -337,10 +337,19 @@ export interface ClientOptions<TO extends BaseTransportOptions = BaseTransportOp
    * A pattern for transaction names which should not be sent to Sentry.
    * By default, all transactions will be sent.
    *
+   * Important: This option is ignored by default! It only has an effect if {@link traceLifecycle} is set to `'static'`.
+   * Use {@link ignoreSpans} instead, which works with both trace lifecycles.
+   *
    * Behavior of the `ignoreTransactions` option is controlled by the `Sentry.eventFiltersIntegration` integration.
    * If the event filters integration is not installed, the `ignoreTransactions` option will not have any effect.
    *
    * @default []
+   *
+   * @deprecated This option only has an effect if {@link traceLifecycle} is set to `'static'`. With span streaming
+   * (`traceLifecycle: 'stream'`, the default), the SDK ignores it. Use {@link ignoreSpans} instead, which works with both
+   * trace lifecycles. `ignoreTransactions` will be removed in v12.
+   *
+   * @see {@link ClientOptions.ignoreSpans}
    */
   ignoreTransactions?: Array<string | RegExp>;
 
@@ -637,12 +646,20 @@ export interface ClientOptions<TO extends BaseTransportOptions = BaseTransportOp
    * An event-processing callback for transaction events, guaranteed to be invoked after all other event
    * processors. This allows an event to be modified or dropped before it's sent.
    *
+   * Important: This callback is ignored by default! It only runs if {@link traceLifecycle} is set to `'static'`.
+   *
    * Note that you must return a valid event from this callback. If you do not wish to modify the event, simply return
    * it at the end. Returning `null` will cause the event to be dropped.
    *
-   * @param event The error or message event generated by the SDK.
+   * @param event The transaction event generated by the SDK.
    * @param hint Event metadata useful for processing.
    * @returns A new event that will be sent | null.
+   *
+   * @deprecated This option only has an effect if {@link traceLifecycle} is set to `'static'`. With span streaming
+   * (`traceLifecycle: 'stream'`, the default), the SDK ignores it. Use {@link beforeSendSpan} instead, which works with both
+   * trace lifecycles. `beforeSendTransaction` will be removed in v12 of the SDK.
+   *
+   * @see {@link ClientOptions.beforeSendSpan}
    */
   beforeSendTransaction?: (
     event: TransactionEvent,

packages/core/src/utils/warnAboutIgnoredTransactionOptions.ts

@@ -0,0 +1,26 @@
+import type { ClientOptions } from '../types/options';
+import { consoleSandbox } from './debug-logger';
+
+/**
+ * Warns about `beforeSendTransaction` and `ignoreTransactions` being ignored because span streaming is enabled.
+ *
+ * Both options are tied to the transaction event that span streaming no longer produces, so they silently
+ * stop taking effect when users upgrade. Since that's easy to miss, this warning bypasses the `debug` logger
+ * (which is opt-in and stripped from non-debug bundles) and writes to the console directly.
+ */
+export function maybeWarnAboutIgnoredTransactionOptions(options: ClientOptions): void {
+  if (
+    options.traceLifecycle !== 'stream' ||
+    // oxlint-disable-next-line typescript/no-deprecated
+    !(options.beforeSendTransaction || options.ignoreTransactions?.length)
+  ) {
+    return;
+  }
+
+  consoleSandbox(() => {
+    // oxlint-disable-next-line no-console
+    console.warn(
+      "[Sentry] `beforeSendTransaction` and `ignoreTransactions` are ignored with `traceLifecycle: 'stream'` (enabled by default). Use `beforeSendSpan` and `ignoreSpans` instead, or set `traceLifecycle: 'static'`.",
+    );
+  });
+}

packages/core/test/lib/client.test.ts

@@ -96,6 +96,93 @@ describe('Client', () => {
     });
   });
 
+  describe('init() / transaction option warnings', () => {
+    test('warns about transaction options ignored by span streaming', () => {
+      const consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+
+      const options = getDefaultTestClientOptions({
+        dsn: PUBLIC_DSN,
+        traceLifecycle: 'stream',
+        beforeSendTransaction: event => event,
+        ignoreTransactions: ['/healthcheck'],
+      });
+      new TestClient(options).init();
+
+      expect(consoleWarnSpy).toHaveBeenCalledTimes(1);
+      expect(consoleWarnSpy).toHaveBeenCalledWith(
+        expect.stringContaining(
+          "`beforeSendTransaction` and `ignoreTransactions` are ignored with `traceLifecycle: 'stream'` (enabled by default).",
+        ),
+      );
+      consoleWarnSpy.mockRestore();
+    });
+
+    test('stays silent when the client is disabled because no DSN was provided', () => {
+      const consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+
+      const options = getDefaultTestClientOptions({
+        traceLifecycle: 'stream',
+        beforeSendTransaction: event => event,
+        ignoreTransactions: ['/healthcheck'],
+      });
+      new TestClient(options).init();
+
+      expect(consoleWarnSpy).not.toHaveBeenCalled();
+      consoleWarnSpy.mockRestore();
+    });
+
+    test('stays silent when the client is disabled via `enabled: false`', () => {
+      const consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+
+      const options = getDefaultTestClientOptions({
+        dsn: PUBLIC_DSN,
+        enabled: false,
+        traceLifecycle: 'stream',
+        beforeSendTransaction: event => event,
+      });
+      new TestClient(options).init();
+
+      expect(consoleWarnSpy).not.toHaveBeenCalled();
+      consoleWarnSpy.mockRestore();
+    });
+
+    test('warns without a DSN when Spotlight is enabled, since spans are still sent', () => {
+      const consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+
+      const options = getDefaultTestClientOptions({
+        traceLifecycle: 'stream',
+        beforeSendTransaction: event => event,
+        integrations: [{ name: 'SpotlightBrowser' }],
+      });
+      new TestClient(options).init();
+
+      expect(consoleWarnSpy).toHaveBeenCalledTimes(1);
+      consoleWarnSpy.mockRestore();
+    });
+
+    test('stays silent when an integration falls back to the static trace lifecycle during setup', () => {
+      const consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+
+      const options = getDefaultTestClientOptions({
+        dsn: PUBLIC_DSN,
+        traceLifecycle: 'stream',
+        beforeSendTransaction: event => event,
+        integrations: [
+          {
+            name: 'FallsBackToStatic',
+            setup: client => {
+              client.getOptions().traceLifecycle = 'static';
+            },
+          },
+        ],
+      });
+      new TestClient(options).init();
+
+      expect(consoleWarnSpy).not.toHaveBeenCalled();
+      consoleWarnSpy.mockRestore();
+    });
+  });
+
   describe('getOptions()', () => {
     test('returns the options', () => {
       expect.assertions(1);

packages/core/test/lib/utils/warnAboutIgnoredTransactionOptions.test.ts

@@ -0,0 +1,85 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { ClientOptions } from '../../../src/types/options';
+import * as debugLoggerModule from '../../../src/utils/debug-logger';
+import { maybeWarnAboutIgnoredTransactionOptions } from '../../../src/utils/warnAboutIgnoredTransactionOptions';
+
+describe('maybeWarnAboutIgnoredTransactionOptions', () => {
+  let consoleWarnSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    vi.spyOn(debugLoggerModule, 'consoleSandbox').mockImplementation(cb => cb());
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  function options(overrides: Partial<ClientOptions>): ClientOptions {
+    return { integrations: [], transport: () => ({}) as never, stackParser: () => [], ...overrides } as ClientOptions;
+  }
+
+  it('warns when `beforeSendTransaction` is set and span streaming is enabled', () => {
+    maybeWarnAboutIgnoredTransactionOptions(
+      options({ traceLifecycle: 'stream', beforeSendTransaction: event => event }),
+    );
+
+    expect(consoleWarnSpy).toHaveBeenCalledTimes(1);
+    expect(consoleWarnSpy.mock.calls[0]?.[0]).toContain('`beforeSendTransaction` and `ignoreTransactions`');
+  });
+
+  it('warns when `ignoreTransactions` is set and span streaming is enabled', () => {
+    maybeWarnAboutIgnoredTransactionOptions(
+      options({ traceLifecycle: 'stream', ignoreTransactions: ['/healthcheck'] }),
+    );
+
+    expect(consoleWarnSpy).toHaveBeenCalledTimes(1);
+    expect(consoleWarnSpy.mock.calls[0]?.[0]).toContain('`beforeSendTransaction` and `ignoreTransactions`');
+  });
+
+  it('warns only once when both options are set', () => {
+    maybeWarnAboutIgnoredTransactionOptions(
+      options({
+        traceLifecycle: 'stream',
+        beforeSendTransaction: event => event,
+        ignoreTransactions: ['/healthcheck'],
+      }),
+    );
+
+    expect(consoleWarnSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('points at the replacement options and the opt-out', () => {
+    maybeWarnAboutIgnoredTransactionOptions(
+      options({ traceLifecycle: 'stream', beforeSendTransaction: event => event }),
+    );
+
+    const message = consoleWarnSpy.mock.calls[0]?.[0];
+    expect(message).toContain('`beforeSendSpan` and `ignoreSpans`');
+    expect(message).toContain("`traceLifecycle: 'static'`");
+  });
+
+  it('does not warn when the trace lifecycle is static', () => {
+    maybeWarnAboutIgnoredTransactionOptions(
+      options({
+        traceLifecycle: 'static',
+        beforeSendTransaction: event => event,
+        ignoreTransactions: ['/healthcheck'],
+      }),
+    );
+
+    expect(consoleWarnSpy).not.toHaveBeenCalled();
+  });
+
+  it('does not warn when neither option is set', () => {
+    maybeWarnAboutIgnoredTransactionOptions(options({ traceLifecycle: 'stream' }));
+
+    expect(consoleWarnSpy).not.toHaveBeenCalled();
+  });
+
+  it('does not warn for an empty `ignoreTransactions` array', () => {
+    maybeWarnAboutIgnoredTransactionOptions(options({ traceLifecycle: 'stream', ignoreTransactions: [] }));
+
+    expect(consoleWarnSpy).not.toHaveBeenCalled();
+  });
+});