fix(core): Fix withStreamedSpan typing error add missing exports (#20124)

This PR makes some changes to the span streaming `beforeSendSpan`
implementation:

Previously `beforeSendSpan` was typed via discriminated union. While I
initially thought this would work, it would break type checking for
user-provided static `beforeSendSpan` callbacks because TS couldn't
infer if the callback received a `SpanJSON` or a `StreamedSpanJSON`. So
it defaulted to `unknown`. Now, we "pretend" that every `beforeSendSpan`
callback receives and returns a `SpanJSON`. Since we instruct users for
span streaming to use the `withStreamedSpan` helper anyway, they will
get correct typing within the wrapper function (i.e. a callback
receiving and returning `StreamedSpanJSON`.

Other changes:
- added missing exports for the `withStreamedSpan` helper from every SDK
- added integration tests to demonstrate it being used
- downleveled the debug log from `warn` to `log` that the browser
`spanStreamingIntegration` automatically sets `traceLifecycle:
'stream'`. This is expected behaviour and we'll instruct users to only
set `spanStreamingIntegration` to avoid a double-opt-in situation.

Author: Lms24

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

@@ -0,0 +1,28 @@
+import * as Sentry from '@sentry/browser';
+
+window.Sentry = Sentry;
+
+Sentry.init({
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  integrations: [Sentry.browserTracingIntegration(), Sentry.spanStreamingIntegration()],
+  tracesSampleRate: 1,
+  beforeSendSpan: Sentry.withStreamedSpan(span => {
+    if (span.attributes['sentry.op'] === 'pageload') {
+      span.name = 'customPageloadSpanName';
+      span.links = [
+        {
+          context: {
+            traceId: '123',
+            spanId: '456',
+          },
+          attributes: {
+            'sentry.link.type': 'custom_link',
+          },
+        },
+      ];
+      span.attributes['sentry.custom_attribute'] = 'customAttributeValue';
+      span.status = 'something';
+    }
+    return span;
+  }),
+});

dev-packages/browser-integration-tests/suites/public-api/beforeSendSpan-streamed/test.ts

@@ -0,0 +1,35 @@
+import { expect } from '@playwright/test';
+import { sentryTest } from '../../../utils/fixtures';
+import { shouldSkipTracingTest, testingCdnBundle } from '../../../utils/helpers';
+import { getSpanOp, waitForStreamedSpan } from '../../../utils/spanUtils';
+
+sentryTest('beforeSendSpan applies changes to streamed span', async ({ getLocalTestUrl, page }) => {
+  sentryTest.skip(shouldSkipTracingTest() || testingCdnBundle());
+
+  const url = await getLocalTestUrl({ testDir: __dirname });
+
+  const pageloadSpanPromise = waitForStreamedSpan(page, span => getSpanOp(span) === 'pageload');
+
+  await page.goto(url);
+
+  const pageloadSpan = await pageloadSpanPromise;
+
+  expect(pageloadSpan.name).toBe('customPageloadSpanName');
+  expect(pageloadSpan.links).toEqual([
+    {
+      context: {
+        traceId: '123',
+        spanId: '456',
+      },
+      attributes: {
+        'sentry.link.type': { type: 'string', value: 'custom_link' },
+      },
+    },
+  ]);
+  expect(pageloadSpan.attributes?.['sentry.custom_attribute']).toEqual({
+    type: 'string',
+    value: 'customAttributeValue',
+  });
+  // we allow overriding any kinds of fields on the span, so we have to expect invalid values
+  expect(pageloadSpan.status).toBe('something');
+});

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

@@ -0,0 +1,42 @@
+import * as Sentry from '@sentry/node-core';
+import { loggingTransport } from '@sentry-internal/node-integration-tests';
+import { setupOtel } from '../../../utils/setupOtel';
+
+const client = 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 => {
+    if (span.name === 'test-child-span') {
+      span.name = 'customChildSpanName';
+      if (!span.attributes) {
+        span.attributes = {};
+      }
+      span.attributes['sentry.custom_attribute'] = 'customAttributeValue';
+      // @ts-ignore - technically this is something we have to expect, despite types saying it's invalid
+      span.status = 'something';
+      span.links = [
+        {
+          trace_id: '123',
+          span_id: '456',
+          attributes: {
+            'sentry.link.type': 'custom_link',
+          },
+        },
+      ];
+    }
+    return span;
+  }),
+});
+
+setupOtel(client);
+
+Sentry.startSpan({ name: 'test-span', op: 'test' }, () => {
+  Sentry.startSpan({ name: 'test-child-span', op: 'test-child' }, () => {
+    // noop
+  });
+});
+
+void Sentry.flush();

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

@@ -0,0 +1,32 @@
+import { expect, test } from 'vitest';
+import { createRunner } from '../../../utils/runner';
+
+test('beforeSendSpan applies changes to streamed span', async () => {
+  await createRunner(__dirname, 'scenario.ts')
+    .expect({
+      span: container => {
+        const spans = container.items;
+        expect(spans.length).toBe(2);
+
+        const customChildSpan = spans.find(s => s.name === 'customChildSpanName');
+
+        expect(customChildSpan).toBeDefined();
+        expect(customChildSpan!.attributes?.['sentry.custom_attribute']).toEqual({
+          type: 'string',
+          value: 'customAttributeValue',
+        });
+        expect(customChildSpan!.status).toBe('something');
+        expect(customChildSpan!.links).toEqual([
+          {
+            trace_id: '123',
+            span_id: '456',
+            attributes: {
+              'sentry.link.type': { type: 'string', value: 'custom_link' },
+            },
+          },
+        ]);
+      },
+    })
+    .start()
+    .completed();
+});

dev-packages/node-integration-tests/suites/tracing/ignoreSpans-streamed/children/instrument.mjs

@@ -7,6 +7,6 @@ Sentry.init({
   tracesSampleRate: 1.0,
   transport: loggingTransport,
   traceLifecycle: 'stream',
-  ignoreSpans: ['middleware - expressInit', /custom-to-drop/, { op: 'ignored-op' }],
+  ignoreSpans: ['expressInit', /custom-to-drop/, { op: 'ignored-op' }],
   clientReportFlushInterval: 1_000,
 });

dev-packages/node-integration-tests/suites/tracing/ignoreSpans-streamed/children/server.mjs

@@ -38,6 +38,12 @@ app.get('/test/express', (_req, res) => {
     () => {},
   );
   res.send({ response: 'response 1' });
+
+  setTimeout(() => {
+    // flush to avoid waiting for the span buffer timeout to send spans
+    // but defer it to the next tick to let the SDK finish the http.server span first.
+    Sentry.flush();
+  });
 });
 
 Sentry.setupExpressErrorHandler(app);

dev-packages/node-integration-tests/suites/tracing/ignoreSpans-streamed/segments/server.mjs

@@ -13,6 +13,11 @@ app.get('/health', (_req, res) => {
 
 app.get('/ok', (_req, res) => {
   res.send({ status: 'ok' });
+  setTimeout(() => {
+    // flush to avoid waiting for the span buffer timeout to send spans
+    // but defer it to the next tick to let the SDK finish the http.server span first.
+    Sentry.flush();
+  });
 });
 
 Sentry.setupExpressErrorHandler(app);

packages/astro/src/index.server.ts

@@ -174,6 +174,7 @@ export {
   unleashIntegration,
   growthbookIntegration,
   spanStreamingIntegration,
+  withStreamedSpan,
   metrics,
 } from '@sentry/node';
 

packages/astro/src/index.types.ts

@@ -21,6 +21,7 @@ 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 withStreamedSpan: typeof clientSdk.withStreamedSpan;
 
 export declare const getDefaultIntegrations: (options: Options) => Integration[];
 export declare const defaultStackParser: StackParser;

packages/aws-serverless/src/index.ts

@@ -161,6 +161,7 @@ export {
   growthbookIntegration,
   metrics,
   spanStreamingIntegration,
+  withStreamedSpan,
 } from '@sentry/node';
 
 export {