feat(core)!: Stream beforeSendSpan payloads by default

Make streamed span JSON the default beforeSendSpan contract and provide
withStaticSpan for callbacks that still process transaction span JSON.
Deprecate withStreamedSpan for removal in version 12.

BREAKING CHANGE: beforeSendSpan receives StreamedSpanJSON by default.
Fixes #22349
Co-Authored-By: Cursor <cursoragent@cursor.com>

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: Lms24

dev-packages/browser-integration-tests/suites/public-api/beforeSendSpan-streamed/init.js

@@ -4,9 +4,9 @@ window.Sentry = Sentry;
 
 Sentry.init({
   dsn: 'https://public@dsn.ingest.sentry.io/1337',
-  integrations: [Sentry.browserTracingIntegration(), Sentry.spanStreamingIntegration()],
+  integrations: [Sentry.browserTracingIntegration()],
   tracesSampleRate: 1,
-  beforeSendSpan: Sentry.withStreamedSpan(span => {
+  beforeSendSpan: span => {
     if (span.attributes['sentry.op'] === 'pageload') {
       span.name = 'customPageloadSpanName';
       span.links = [
@@ -24,5 +24,5 @@ Sentry.init({
       span.status = 'something';
     }
     return span;
-  }),
+  },
 });

dev-packages/node-integration-tests/suites/public-api/beforeSendSpan-streamed/scenario.ts

@@ -4,10 +4,9 @@ import { loggingTransport } from '@sentry-internal/node-integration-tests';
 Sentry.init({
   dsn: 'https://public@dsn.ingest.sentry.io/1337',
   tracesSampleRate: 1.0,
-  traceLifecycle: 'stream',
   transport: loggingTransport,
   release: '1.0.0',
-  beforeSendSpan: Sentry.withStreamedSpan(span => {
+  beforeSendSpan: span => {
     if (span.name === 'test-child-span') {
       span.name = 'customChildSpanName';
       if (!span.attributes) {
@@ -27,7 +26,7 @@ Sentry.init({
       ];
     }
     return span;
-  }),
+  },
 });
 
 Sentry.startSpan({ name: 'test-span', op: 'test' }, () => {

dev-packages/rollup-utils/plugins/bundlePlugins.mjs

@@ -150,7 +150,8 @@ export function makeTerserPlugin() {
           '_resolveFilename',
           // Set on e.g. the shim feedbackIntegration to be able to detect it
           '_isShim',
-          // Marker set by `withStreamedSpan()` to tag streamed `beforeSendSpan` callbacks
+          // Markers used to distinguish static and explicitly streamed `beforeSendSpan` callbacks
+          '_static',
           '_streamed',
           // This is used in metadata integration
           '_sentryModuleMetadata',

packages/astro/src/index.server.ts

@@ -173,6 +173,8 @@ export {
   unleashIntegration,
   growthbookIntegration,
   spanStreamingIntegration,
+  withStaticSpan,
+  // eslint-disable-next-line typescript/no-deprecated
   withStreamedSpan,
   metrics,
 } from '@sentry/node';

packages/astro/src/index.types.ts

@@ -21,6 +21,8 @@ export declare function init(options: Options | clientSdk.BrowserOptions | NodeO
 export declare const linkedErrorsIntegration: typeof clientSdk.linkedErrorsIntegration;
 export declare const contextLinesIntegration: typeof clientSdk.contextLinesIntegration;
 export declare const spanStreamingIntegration: typeof clientSdk.spanStreamingIntegration;
+export declare const withStaticSpan: typeof clientSdk.withStaticSpan;
+// eslint-disable-next-line typescript/no-deprecated
 export declare const withStreamedSpan: typeof clientSdk.withStreamedSpan;
 
 export declare const getDefaultIntegrations: (options: Options) => Integration[];

packages/aws-serverless/src/index.ts

@@ -160,6 +160,8 @@ export {
   growthbookIntegration,
   metrics,
   spanStreamingIntegration,
+  withStaticSpan,
+  // eslint-disable-next-line typescript/no-deprecated
   withStreamedSpan,
   experimentalUseDiagnosticsChannelInjection,
   diagnosticsChannelInjectionIntegrations,

packages/browser/src/exports.ts

@@ -72,6 +72,8 @@ export {
   spanToTraceHeader,
   spanToBaggageHeader,
   updateSpanName,
+  withStaticSpan,
+  // eslint-disable-next-line typescript/no-deprecated
   withStreamedSpan,
   metrics,
 } from '@sentry/core/browser';

packages/browser/src/integrations/spanstreaming.ts

@@ -4,7 +4,7 @@ import {
   debug,
   defineIntegration,
   hasSpanStreamingEnabled,
-  isStreamedBeforeSendSpanCallback,
+  isStaticBeforeSendSpanCallback,
   SpanBuffer,
   spanIsSampled,
 } from '@sentry/core/browser';
@@ -36,12 +36,12 @@ export const spanStreamingIntegration = defineIntegration(() => {
       }
 
       const beforeSendSpan = clientOptions.beforeSendSpan;
-      // If users misconfigure their SDK by opting into span streaming but
-      // using an incompatible beforeSendSpan callback, we fall back to the static trace lifecycle.
-      if (beforeSendSpan && !isStreamedBeforeSendSpanCallback(beforeSendSpan)) {
+      if (isStaticBeforeSendSpanCallback(beforeSendSpan)) {
         clientOptions.traceLifecycle = 'static';
         DEBUG_BUILD &&
-          debug.warn(`${initialMessage} a beforeSendSpan callback using \`withStreamedSpan\`! ${fallbackMsg}`);
+          debug.warn(
+            `SpanStreaming integration is incompatible with a beforeSendSpan callback using \`withStaticSpan\`! ${fallbackMsg}`,
+          );
         return;
       }
 

packages/browser/test/integrations/spanstreaming.test.ts

@@ -79,21 +79,21 @@ describe('spanStreamingIntegration', () => {
     },
   );
 
-  it('falls back to static trace lifecycle if beforeSendSpan is not compatible with span streaming', () => {
+  it('falls back to static trace lifecycle if beforeSendSpan is marked as static', () => {
     const debugSpy = vi.spyOn(debug, 'warn').mockImplementation(() => {});
     const client = new BrowserClient({
       ...getDefaultBrowserClientOptions(),
       dsn: 'https://username@domain/123',
       integrations: [spanStreamingIntegration()],
       traceLifecycle: 'stream',
-      beforeSendSpan: (span: Span) => span,
+      beforeSendSpan: SentryCore.withStaticSpan(span => span),
     });
 
     SentryCore.setCurrentClient(client);
     client.init();
 
     expect(debugSpy).toHaveBeenCalledWith(
-      'SpanStreaming integration requires a beforeSendSpan callback using `withStreamedSpan`! Falling back to static trace lifecycle.',
+      'SpanStreaming integration is incompatible with a beforeSendSpan callback using `withStaticSpan`! Falling back to static trace lifecycle.',
     );
     debugSpy.mockRestore();
 

packages/bun/src/index.ts

@@ -178,6 +178,8 @@ export {
   unleashIntegration,
   metrics,
   spanStreamingIntegration,
+  withStaticSpan,
+  // eslint-disable-next-line typescript/no-deprecated
   withStreamedSpan,
 } from '@sentry/node';