feat(core)!: Enable span streaming by default

dev-packages/browser-integration-tests/loader-suites/loader/noOnLoad/pageloadTransaction/test.ts

@@ -1,27 +1,21 @@
 import { expect } from '@playwright/test';
 import { sentryTest } from '../../../../utils/fixtures';
-import {
- envelopeRequestParser,
- shouldSkipTracingTest,
- waitForTransactionRequestOnUrl,
-} from '../../../../utils/helpers';
+import { shouldSkipTracingTest } from '../../../../utils/helpers';
+import { getSpanOp, waitForStreamedSpan } from '../../../../utils/spanUtils';
 
-sentryTest('should create a pageload transaction', async ({ getLocalTestUrl, page }) => {
+sentryTest('should create a pageload span', async ({ getLocalTestUrl, page }) => {
  if (shouldSkipTracingTest()) {
  sentryTest.skip();
  }
 
+ const spanPromise = waitForStreamedSpan(page, s => getSpanOp(s) === 'pageload');
  const url = await getLocalTestUrl({ testDir: __dirname });
- const req = await waitForTransactionRequestOnUrl(page, url);
+ await page.goto(url);
+ const pageloadSpan = await spanPromise;
 
- const eventData = envelopeRequestParser(req);
  const timeOrigin = await page.evaluate<number>('window._testBaseTimestamp');
 
-const { start_timestamp: startTimestamp } = eventData;
+expect(pageloadSpan.start_timestamp).toBeCloseTo(timeOrigin, 1);
 
- expect(startTimestamp).toBeCloseTo(timeOrigin, 1);
-
- expect(eventData.contexts?.trace?.op).toBe('pageload');
- expect(eventData.spans?.length).toBeGreaterThan(0);
- expect(eventData.transaction_info?.source).toEqual('url');
+ expect(pageloadSpan.attributes?.['sentry.segment.name.source'].value).toEqual('url');
 });

dev-packages/e2e-tests/test-applications/astro-5-cf-workers/wrangler.jsonc

@@ -9,6 +9,7 @@
  "SENTRY_ENVIRONMENT": "qa",
  "SENTRY_TRACES_SAMPLE_RATE": "1.0",
  "SENTRY_TUNNEL": "http://localhost:3031/",
+ "SENTRY_TRACE_LIFECYCLE": "static",
  },
  "assets": {
  "binding": "ASSETS",

dev-packages/e2e-tests/test-applications/aws-serverless-layer/src/stack.ts

@@ -77,6 +77,7 @@ export class LocalLambdaStack extends Stack {
  Variables: {
  SENTRY_TRACES_SAMPLE_RATE: 1.0,
  SENTRY_DEBUG: true,
+ SENTRY_TRACE_LIFECYCLE: 'static',
  NODE_OPTIONS: `--import=@sentry/aws-serverless/awslambda-auto`,
  // We only set SENTRY_DSN if not running TunnelNoDsn, because there
  // we want to test that the extension tunnel forwards requests when SENTRY_DSN is missing.

dev-packages/e2e-tests/test-applications/aws-serverless/src/stack.ts

@@ -112,6 +112,7 @@ export class LocalLambdaStack extends Stack {
  SENTRY_DSN: dsn,
  SENTRY_TRACES_SAMPLE_RATE: 1.0,
  SENTRY_DEBUG: true,
+ SENTRY_TRACE_LIFECYCLE: 'static',
  NODE_OPTIONS: `--import=@sentry/aws-serverless/awslambda-auto`,
  },
  },

packages/browser/src/integrations/spanstreaming.ts

@@ -14,16 +14,6 @@ export const spanStreamingIntegration = defineIntegration(() => {
  return {
  name: 'SpanStreaming' as const,
 
- beforeSetup(client) {
- // If users only set spanStreamingIntegration, without traceLifecycle, we set it to "stream" for them.
- // This avoids the classic double-opt-in problem we'd otherwise have in the browser SDK.
- const clientOptions = client.getOptions();
- if (!clientOptions.traceLifecycle) {
- DEBUG_BUILD && debug.log('[SpanStreaming] setting `traceLifecycle` to "stream"');
- clientOptions.traceLifecycle = 'stream';
- }
- },
-
  setup(client) {
  const initialMessage = 'SpanStreaming integration requires';
  const fallbackMsg = 'Falling back to static trace lifecycle.';

packages/browser/src/sdk.ts

@@ -19,6 +19,7 @@ import { globalHandlersIntegration } from './integrations/globalhandlers';
 import { httpContextIntegration } from './integrations/httpcontext';
 import { linkedErrorsIntegration } from './integrations/linkederrors';
 import { spotlightBrowserIntegration } from './integrations/spotlight';
+import { spanStreamingIntegration } from './integrations/spanstreaming';
 import { defaultStackParser } from './stack-parsers';
 import { makeFetchTransport } from './transports/fetch';
 import { normalizeStringifyValue } from './normalizeStringifyValue';
@@ -110,14 +111,22 @@ export function init(options: BrowserOptions = {}): Client | undefined {
  }
  /*! rollup-include-development-only-end */
 
+ const integrations = getIntegrationsToSetup({
+ integrations: options.integrations,
+ defaultIntegrations,
+ });
+
+ options.traceLifecycle ??= 'stream';
+
+ if (options.traceLifecycle === 'stream' && !integrations.some(integration => integration.name === 'SpanStreaming')) {
+ integrations.push(spanStreamingIntegration());
+ }
+
  const clientOptions: BrowserClientOptions = {
  ...options,
  enabled: shouldDisableBecauseIsBrowserExtenstion ? false : options.enabled,
  stackParser: stackParserFromStackParserOptions(options.stackParser || defaultStackParser),
- integrations: getIntegrationsToSetup({
- integrations: options.integrations,
- defaultIntegrations,
- }),
+ integrations,
  transport: options.transport || makeFetchTransport,
  };
 

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

@@ -37,24 +37,9 @@ describe('spanStreamingIntegration', () => {
  const integration = spanStreamingIntegration();
  expect(integration.name).toBe('SpanStreaming');
  // eslint-disable-next-line @typescript-eslint/unbound-method
- expect(integration.beforeSetup).toBeDefined();
- // eslint-disable-next-line @typescript-eslint/unbound-method
  expect(integration.setup).toBeDefined();
  });
 
- it('sets traceLifecycle to "stream" if not set', () => {
- const client = new BrowserClient({
- ...getDefaultBrowserClientOptions(),
- dsn: 'https://username@domain/123',
- integrations: [spanStreamingIntegration()],
- });
-
- SentryCore.setCurrentClient(client);
- client.init();
-
- expect(client.getOptions().traceLifecycle).toBe('stream');
- });
-
  it.each(['static', 'somethingElse'])(
  'logs a warning if traceLifecycle is not set to "stream" but to %s',
  traceLifecycle => {

packages/browser/test/sdk.test.ts

@@ -61,6 +61,32 @@ describe('init', () => {
  expect(optionsPassed?.integrations.length).toBeGreaterThan(0);
  });
 
+ it('installs spanStreamingIntegration by default', () => {
+ // @ts-expect-error this is fine for testing
+ const initAndBindSpy = vi.spyOn(SentryCore, 'initAndBind').mockImplementationOnce(() => {});
+ const options = getDefaultBrowserOptions({ dsn: PUBLIC_DSN, defaultIntegrations: undefined });
+
+ init(options);
+
+ const optionsPassed = initAndBindSpy.mock.calls[0]?.[1];
+ expect(optionsPassed?.integrations.some(integration => integration.name === 'SpanStreaming')).toBe(true);
+ });
+
+ it('does not install spanStreamingIntegration when traceLifecycle is static', () => {
+ // @ts-expect-error this is fine for testing
+ const initAndBindSpy = vi.spyOn(SentryCore, 'initAndBind').mockImplementationOnce(() => {});
+ const options = getDefaultBrowserOptions({
+ dsn: PUBLIC_DSN,
+ defaultIntegrations: undefined,
+ traceLifecycle: 'static',
+ });
+
+ init(options);
+
+ const optionsPassed = initAndBindSpy.mock.calls[0]?.[1];
+ expect(optionsPassed?.integrations.some(integration => integration.name === 'SpanStreaming')).toBe(false);
+ });
+
  test("doesn't install default integrations if told not to", () => {
  const DEFAULT_INTEGRATIONS: Integration[] = [
  new MockIntegration('MockIntegration 0.3'),
@@ -73,6 +99,17 @@ describe('init', () => {
  expect(DEFAULT_INTEGRATIONS[1]!.setupOnce as Mock).toHaveBeenCalledTimes(0);
  });
 
+ it('installs spanStreamingIntegration with defaultIntegrations disabled', () => {
+ // @ts-expect-error this is fine for testing
+ const initAndBindSpy = vi.spyOn(SentryCore, 'initAndBind').mockImplementationOnce(() => {});
+ const options = getDefaultBrowserOptions({ dsn: PUBLIC_DSN, defaultIntegrations: false });
+
+ init(options);
+
+ const optionsPassed = initAndBindSpy.mock.calls[0]?.[1];
+ expect(optionsPassed?.integrations.some(integration => integration.name === 'SpanStreaming')).toBe(true);
+ });
+
  it('installs merged default integrations, with overrides provided through options', () => {
  const DEFAULT_INTEGRATIONS = [
  new MockIntegration('MockIntegration 1.1'),

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

@@ -27,6 +27,7 @@ export function createSentryInstance(
  dsn: 'https://4c2bae7d9fbc413e8f7385f55c515d51@o1.ingest.sentry.io/6690737',
 
  tracesSampleRate: 1,
+ traceLifecycle: 'static',
  sampleRate: 1,
 
  release: LIB_VERSION,

packages/cloudflare/src/options.ts

@@ -70,6 +70,7 @@ export function getFinalOptions(userOptions: CloudflareOptions = {}, env: unknow
  tracesSampleRate: isFinite(tracesSampleRate) ? tracesSampleRate : undefined,
  debug: userOptions.debug ?? envToBool(getEnvVar(env, 'SENTRY_DEBUG')),
  tunnel: userOptions.tunnel ?? getEnvVar(env, 'SENTRY_TUNNEL'),
+ traceLifecycle: userOptions.traceLifecycle ?? getTraceLifecycleFromEnv(getEnvVar(env, 'SENTRY_TRACE_LIFECYCLE')),
  /*! rollup-include-development-only */
  spotlight,
  /*! rollup-include-development-only-end */
@@ -102,3 +103,7 @@ function getSpotlightFromEnv(
  ? (envUrl ?? true) // true: use env URL if present, otherwise true
  : (envBool ?? envUrl); // undefined: use env var (bool or URL)
 }
+
+function getTraceLifecycleFromEnv(envVar: string | undefined): 'static' | 'stream' | undefined {
+ return envVar === 'stream' || envVar === 'static' ? envVar : undefined;
+}

packages/cloudflare/test/sdk.test.ts

@@ -22,10 +22,9 @@ describe('init', () => {
  expect(client).toBeInstanceOf(CloudflareClient);
  });
 
- test('installs SpanStreaming integration when traceLifecycle is "stream"', () => {
+ test('installs SpanStreaming integration by default', () => {
  init({
  dsn: 'https://public@dsn.ingest.sentry.io/1337',
- traceLifecycle: 'stream',
  });
  const client = getClient();
 
@@ -36,8 +35,8 @@ describe('init', () => {
  );
  });
 
- test("does not install SpanStreaming integration when traceLifecycle is not 'stream'", () => {
- init({ dsn: 'https://public@dsn.ingest.sentry.io/1337' });
+ test("does not install SpanStreaming integration when traceLifecycle is 'static'", () => {
+ init({ dsn: 'https://public@dsn.ingest.sentry.io/1337', traceLifecycle: 'static' });
  const client = getClient();
 
  expect(client?.getOptions()).toEqual(

packages/core/src/client.ts

@@ -234,7 +234,7 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
  * @param options Options for the client.
  */
  protected constructor(options: O) {
- this._options = { attachStacktrace: true, ...options };
+ this._options = { attachStacktrace: true, traceLifecycle: 'stream', ...options };
  this._integrations = {};
  this._numProcessing = 0;
  this._outcomes = {};

packages/core/src/server-runtime-client.ts

@@ -40,6 +40,8 @@ export class ServerRuntimeClient<
  public constructor(options: O) {
  addUserAgentToTransportHeaders(options);
 
+ options.traceLifecycle ??= 'stream';
+
  // When span streaming is enabled (`traceLifecycle: 'stream'`), the `spanStreamingIntegration`
  // is required to flush spans. We add it here so the individual server SDKs don't have to.
  // A user-provided `spanStreamingIntegration` always takes precedence over the one we add.

packages/core/src/types/options.ts

@@ -543,7 +543,7 @@ export interface ClientOptions<TO extends BaseTransportOptions = BaseTransportOp
  * The trace lifecycle, determining whether spans are sent statically when the entire local span tree is complete,
  * or streamed in batches, following interval- and action-based triggers.
  *
- * @default 'static'
+ * @default 'stream'
  */
  traceLifecycle?: 'static' | 'stream';
 

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

@@ -103,7 +103,21 @@ describe('Client', () => {
  const options = getDefaultTestClientOptions({ dsn: PUBLIC_DSN, test: true });
  const client = new TestClient(options);
 
- expect(client.getOptions()).toEqual({ attachStacktrace: true, ...options });
+ expect(client.getOptions()).toEqual({ attachStacktrace: true, traceLifecycle: 'stream', ...options });
+ });
+
+ test('defaults traceLifecycle to stream', () => {
+ const options = getDefaultTestClientOptions();
+ delete options.traceLifecycle;
+ const client = new TestClient(options);
+
+ expect(client.getOptions().traceLifecycle).toBe('stream');
+ });
+
+ test('preserves an explicit static traceLifecycle', () => {
+ const client = new TestClient(getDefaultTestClientOptions({ traceLifecycle: 'static' }));
+
+ expect(client.getOptions().traceLifecycle).toBe('static');
  });
  });
 

packages/deno/test/sdk.test.ts

@@ -8,17 +8,17 @@ Deno.test('init() should return client', () => {
  assertNotEquals(init({}), undefined);
 });
 
-Deno.test('adds spanStreamingIntegration when traceLifecycle is "stream"', () => {
- const client = init({ traceLifecycle: 'stream' });
+Deno.test('adds spanStreamingIntegration by default', () => {
+ const client = init({});
  const integrations = client.getOptions().integrations;
  assertArrayIncludes(
  integrations.map(i => i.name),
  ['SpanStreaming'],
  );
 });
 
-Deno.test('doesn\'t add spanStreamingIntegration when traceLifecycle is not "stream"', () => {
- const client = init({});
+Deno.test('doesn\'t add spanStreamingIntegration when traceLifecycle is "static"', () => {
+ const client = init({ traceLifecycle: 'static' });
  const integrations = client.getOptions().integrations;
  assert(!integrations.some(i => i.name === 'SpanStreaming'));
 });

packages/node/src/sdk/index.ts

@@ -300,6 +300,7 @@ function getClientOptions(
  const spotlight = getSpotlightConfig(options.spotlight);
 
  const tracesSampleRate = getTracesSampleRate(options.tracesSampleRate);
+ const traceLifecycle = getTraceLifecycle(options.traceLifecycle);
 
  const mergedOptions = {
  ...options,
@@ -311,6 +312,7 @@ function getClientOptions(
  release,
  tracesSampleRate,
  spotlight,
+ traceLifecycle,
  debug: envToBool(options.debug ?? process.env.SENTRY_DEBUG),
  };
 
@@ -355,6 +357,20 @@ function getTracesSampleRate(tracesSampleRate: NodeOptions['tracesSampleRate']):
  return isFinite(parsed) ? parsed : undefined;
 }
 
+function getTraceLifecycle(traceLifecycle: NodeOptions['traceLifecycle']): 'stream' | 'static' {
+ if (traceLifecycle !== undefined) {
+ return traceLifecycle;
+ }
+
+ const lifecycleFromEnv = process.env.SENTRY_TRACE_LIFECYCLE;
+
+ if (lifecycleFromEnv === 'stream' || lifecycleFromEnv === 'static') {
+ return lifecycleFromEnv;
+ }
+
+ return 'stream';
+}
+
 /**
  * Update scope and propagation context based on environmental variables.
  *

packages/node/test/sdk/init.test.ts

@@ -59,16 +59,12 @@ describe('init()', () => {
  });
 
  describe('integrations', () => {
- it("doesn't install default integrations if told not to", () => {
+ it('only installs the required spanStreaming integration if default integrations are disabled', () => {
  init({ dsn: PUBLIC_DSN, defaultIntegrations: false });
 
  const client = getClient();
 
- expect(client?.getOptions()).toEqual(
- expect.objectContaining({
- integrations: [],
- }),
- );
+ expect(client?.getOptions().integrations.map(integration => integration.name)).toEqual(['SpanStreaming']);
 
  expect(mockAutoPerformanceIntegrations).toHaveBeenCalledTimes(0);
  });
@@ -169,8 +165,8 @@ describe('init()', () => {
  );
  });
 
- it('installs spanStreaming integration when traceLifecycle is "stream"', () => {
- init({ dsn: PUBLIC_DSN, traceLifecycle: 'stream' });
+ it('installs spanStreaming integration by default', () => {
+ init({ dsn: PUBLIC_DSN });
  const client = getClient();
 
  expect(client?.getOptions()).toEqual(
@@ -180,8 +176,8 @@ describe('init()', () => {
  );
  });
 
- it("doesn't install spanStreaming integration when traceLifecycle is not 'stream'", () => {
- init({ dsn: PUBLIC_DSN });
+ it("doesn't install spanStreaming integration when traceLifecycle is 'static'", () => {
+ init({ dsn: PUBLIC_DSN, traceLifecycle: 'static' });
 
  const client = getClient();
  expect(client?.getOptions()).toEqual(
@@ -192,7 +188,7 @@ describe('init()', () => {
  });
 
  it('installs spanStreaming integration even with custom defaultIntegrations', () => {
- init({ dsn: PUBLIC_DSN, traceLifecycle: 'stream', defaultIntegrations: [] });
+ init({ dsn: PUBLIC_DSN, defaultIntegrations: [] });
  const client = getClient();
 
  expect(client?.getOptions()).toEqual(

dev-packages/browser-integration-tests/loader-suites/loader/noOnLoad/pageloadTransaction/test.ts

@@ -1,27 +1,21 @@
 import { expect } from '@playwright/test';
 import { sentryTest } from '../../../../utils/fixtures';
-import {
- envelopeRequestParser,
- shouldSkipTracingTest,
- waitForTransactionRequestOnUrl,
-} from '../../../../utils/helpers';
+import { shouldSkipTracingTest } from '../../../../utils/helpers';
+import { getSpanOp, waitForStreamedSpan } from '../../../../utils/spanUtils';
 
-sentryTest('should create a pageload transaction', async ({ getLocalTestUrl, page }) => {
+sentryTest('should create a pageload span', async ({ getLocalTestUrl, page }) => {
  if (shouldSkipTracingTest()) {
  sentryTest.skip();
  }
 
+ const spanPromise = waitForStreamedSpan(page, s => getSpanOp(s) === 'pageload');
  const url = await getLocalTestUrl({ testDir: __dirname });
- const req = await waitForTransactionRequestOnUrl(page, url);
+ await page.goto(url);
+ const pageloadSpan = await spanPromise;
 
- const eventData = envelopeRequestParser(req);
  const timeOrigin = await page.evaluate<number>('window._testBaseTimestamp');
 
-const { start_timestamp: startTimestamp } = eventData;
+expect(pageloadSpan.start_timestamp).toBeCloseTo(timeOrigin, 1);
 
- expect(startTimestamp).toBeCloseTo(timeOrigin, 1);
-
- expect(eventData.contexts?.trace?.op).toBe('pageload');
- expect(eventData.spans?.length).toBeGreaterThan(0);
- expect(eventData.transaction_info?.source).toEqual('url');
+ expect(pageloadSpan.attributes?.['sentry.segment.name.source'].value).toEqual('url');
 });

dev-packages/e2e-tests/test-applications/astro-5-cf-workers/wrangler.jsonc

@@ -9,6 +9,7 @@
  "SENTRY_ENVIRONMENT": "qa",
  "SENTRY_TRACES_SAMPLE_RATE": "1.0",
  "SENTRY_TUNNEL": "http://localhost:3031/",
+ "SENTRY_TRACE_LIFECYCLE": "static",
  },
  "assets": {
  "binding": "ASSETS",

dev-packages/e2e-tests/test-applications/aws-serverless-layer/src/stack.ts

@@ -77,6 +77,7 @@ export class LocalLambdaStack extends Stack {
  Variables: {
  SENTRY_TRACES_SAMPLE_RATE: 1.0,
  SENTRY_DEBUG: true,
+ SENTRY_TRACE_LIFECYCLE: 'static',
  NODE_OPTIONS: `--import=@sentry/aws-serverless/awslambda-auto`,
  // We only set SENTRY_DSN if not running TunnelNoDsn, because there
  // we want to test that the extension tunnel forwards requests when SENTRY_DSN is missing.

dev-packages/e2e-tests/test-applications/aws-serverless/src/stack.ts

@@ -112,6 +112,7 @@ export class LocalLambdaStack extends Stack {
  SENTRY_DSN: dsn,
  SENTRY_TRACES_SAMPLE_RATE: 1.0,
  SENTRY_DEBUG: true,
+ SENTRY_TRACE_LIFECYCLE: 'static',
  NODE_OPTIONS: `--import=@sentry/aws-serverless/awslambda-auto`,
  },
  },

packages/browser/src/integrations/spanstreaming.ts

@@ -14,16 +14,6 @@ export const spanStreamingIntegration = defineIntegration(() => {
  return {
  name: 'SpanStreaming' as const,
 
- beforeSetup(client) {
- // If users only set spanStreamingIntegration, without traceLifecycle, we set it to "stream" for them.
- // This avoids the classic double-opt-in problem we'd otherwise have in the browser SDK.
- const clientOptions = client.getOptions();
- if (!clientOptions.traceLifecycle) {
- DEBUG_BUILD && debug.log('[SpanStreaming] setting `traceLifecycle` to "stream"');
- clientOptions.traceLifecycle = 'stream';
- }
- },
-
  setup(client) {
  const initialMessage = 'SpanStreaming integration requires';
  const fallbackMsg = 'Falling back to static trace lifecycle.';

packages/browser/src/sdk.ts

@@ -19,6 +19,7 @@ import { globalHandlersIntegration } from './integrations/globalhandlers';
 import { httpContextIntegration } from './integrations/httpcontext';
 import { linkedErrorsIntegration } from './integrations/linkederrors';
 import { spotlightBrowserIntegration } from './integrations/spotlight';
+import { spanStreamingIntegration } from './integrations/spanstreaming';
 import { defaultStackParser } from './stack-parsers';
 import { makeFetchTransport } from './transports/fetch';
 import { normalizeStringifyValue } from './normalizeStringifyValue';
@@ -110,14 +111,22 @@ export function init(options: BrowserOptions = {}): Client | undefined {
  }
  /*! rollup-include-development-only-end */
 
+ const integrations = getIntegrationsToSetup({
+ integrations: options.integrations,
+ defaultIntegrations,
+ });
+
+ options.traceLifecycle ??= 'stream';
+
+ if (options.traceLifecycle === 'stream' && !integrations.some(integration => integration.name === 'SpanStreaming')) {
+ integrations.push(spanStreamingIntegration());
+ }
+
  const clientOptions: BrowserClientOptions = {
  ...options,
  enabled: shouldDisableBecauseIsBrowserExtenstion ? false : options.enabled,
  stackParser: stackParserFromStackParserOptions(options.stackParser || defaultStackParser),
- integrations: getIntegrationsToSetup({
- integrations: options.integrations,
- defaultIntegrations,
- }),
+ integrations,
  transport: options.transport || makeFetchTransport,
  };
 

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

@@ -37,24 +37,9 @@ describe('spanStreamingIntegration', () => {
  const integration = spanStreamingIntegration();
  expect(integration.name).toBe('SpanStreaming');
  // eslint-disable-next-line @typescript-eslint/unbound-method
- expect(integration.beforeSetup).toBeDefined();
- // eslint-disable-next-line @typescript-eslint/unbound-method
  expect(integration.setup).toBeDefined();
  });
 
- it('sets traceLifecycle to "stream" if not set', () => {
- const client = new BrowserClient({
- ...getDefaultBrowserClientOptions(),
- dsn: 'https://username@domain/123',
- integrations: [spanStreamingIntegration()],
- });
-
- SentryCore.setCurrentClient(client);
- client.init();
-
- expect(client.getOptions().traceLifecycle).toBe('stream');
- });
-
  it.each(['static', 'somethingElse'])(
  'logs a warning if traceLifecycle is not set to "stream" but to %s',
  traceLifecycle => {

packages/browser/test/sdk.test.ts

@@ -61,6 +61,32 @@ describe('init', () => {
  expect(optionsPassed?.integrations.length).toBeGreaterThan(0);
  });
 
+ it('installs spanStreamingIntegration by default', () => {
+ // @ts-expect-error this is fine for testing
+ const initAndBindSpy = vi.spyOn(SentryCore, 'initAndBind').mockImplementationOnce(() => {});
+ const options = getDefaultBrowserOptions({ dsn: PUBLIC_DSN, defaultIntegrations: undefined });
+
+ init(options);
+
+ const optionsPassed = initAndBindSpy.mock.calls[0]?.[1];
+ expect(optionsPassed?.integrations.some(integration => integration.name === 'SpanStreaming')).toBe(true);
+ });
+
+ it('does not install spanStreamingIntegration when traceLifecycle is static', () => {
+ // @ts-expect-error this is fine for testing
+ const initAndBindSpy = vi.spyOn(SentryCore, 'initAndBind').mockImplementationOnce(() => {});
+ const options = getDefaultBrowserOptions({
+ dsn: PUBLIC_DSN,
+ defaultIntegrations: undefined,
+ traceLifecycle: 'static',
+ });
+
+ init(options);
+
+ const optionsPassed = initAndBindSpy.mock.calls[0]?.[1];
+ expect(optionsPassed?.integrations.some(integration => integration.name === 'SpanStreaming')).toBe(false);
+ });
+
  test("doesn't install default integrations if told not to", () => {
  const DEFAULT_INTEGRATIONS: Integration[] = [
  new MockIntegration('MockIntegration 0.3'),
@@ -73,6 +99,17 @@ describe('init', () => {
  expect(DEFAULT_INTEGRATIONS[1]!.setupOnce as Mock).toHaveBeenCalledTimes(0);
  });
 
+ it('installs spanStreamingIntegration with defaultIntegrations disabled', () => {
+ // @ts-expect-error this is fine for testing
+ const initAndBindSpy = vi.spyOn(SentryCore, 'initAndBind').mockImplementationOnce(() => {});
+ const options = getDefaultBrowserOptions({ dsn: PUBLIC_DSN, defaultIntegrations: false });
+
+ init(options);
+
+ const optionsPassed = initAndBindSpy.mock.calls[0]?.[1];
+ expect(optionsPassed?.integrations.some(integration => integration.name === 'SpanStreaming')).toBe(true);
+ });
+
  it('installs merged default integrations, with overrides provided through options', () => {
  const DEFAULT_INTEGRATIONS = [
  new MockIntegration('MockIntegration 1.1'),

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

@@ -27,6 +27,7 @@ export function createSentryInstance(
  dsn: 'https://4c2bae7d9fbc413e8f7385f55c515d51@o1.ingest.sentry.io/6690737',
 
  tracesSampleRate: 1,
+ traceLifecycle: 'static',
  sampleRate: 1,
 
  release: LIB_VERSION,

packages/cloudflare/src/options.ts

@@ -70,6 +70,7 @@ export function getFinalOptions(userOptions: CloudflareOptions = {}, env: unknow
  tracesSampleRate: isFinite(tracesSampleRate) ? tracesSampleRate : undefined,
  debug: userOptions.debug ?? envToBool(getEnvVar(env, 'SENTRY_DEBUG')),
  tunnel: userOptions.tunnel ?? getEnvVar(env, 'SENTRY_TUNNEL'),
+ traceLifecycle: userOptions.traceLifecycle ?? getTraceLifecycleFromEnv(getEnvVar(env, 'SENTRY_TRACE_LIFECYCLE')),
  /*! rollup-include-development-only */
  spotlight,
  /*! rollup-include-development-only-end */
@@ -102,3 +103,7 @@ function getSpotlightFromEnv(
  ? (envUrl ?? true) // true: use env URL if present, otherwise true
  : (envBool ?? envUrl); // undefined: use env var (bool or URL)
 }
+
+function getTraceLifecycleFromEnv(envVar: string | undefined): 'static' | 'stream' | undefined {
+ return envVar === 'stream' || envVar === 'static' ? envVar : undefined;
+}

packages/cloudflare/test/sdk.test.ts

@@ -22,10 +22,9 @@ describe('init', () => {
  expect(client).toBeInstanceOf(CloudflareClient);
  });
 
- test('installs SpanStreaming integration when traceLifecycle is "stream"', () => {
+ test('installs SpanStreaming integration by default', () => {
  init({
  dsn: 'https://public@dsn.ingest.sentry.io/1337',
- traceLifecycle: 'stream',
  });
  const client = getClient();
 
@@ -36,8 +35,8 @@ describe('init', () => {
  );
  });
 
- test("does not install SpanStreaming integration when traceLifecycle is not 'stream'", () => {
- init({ dsn: 'https://public@dsn.ingest.sentry.io/1337' });
+ test("does not install SpanStreaming integration when traceLifecycle is 'static'", () => {
+ init({ dsn: 'https://public@dsn.ingest.sentry.io/1337', traceLifecycle: 'static' });
  const client = getClient();
 
  expect(client?.getOptions()).toEqual(

packages/core/src/client.ts

@@ -234,7 +234,7 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
  * @param options Options for the client.
  */
  protected constructor(options: O) {
- this._options = { attachStacktrace: true, ...options };
+ this._options = { attachStacktrace: true, traceLifecycle: 'stream', ...options };
  this._integrations = {};
  this._numProcessing = 0;
  this._outcomes = {};

packages/core/src/server-runtime-client.ts

@@ -40,6 +40,8 @@ export class ServerRuntimeClient<
  public constructor(options: O) {
  addUserAgentToTransportHeaders(options);
 
+ options.traceLifecycle ??= 'stream';
+
  // When span streaming is enabled (`traceLifecycle: 'stream'`), the `spanStreamingIntegration`
  // is required to flush spans. We add it here so the individual server SDKs don't have to.
  // A user-provided `spanStreamingIntegration` always takes precedence over the one we add.

packages/core/src/types/options.ts

@@ -543,7 +543,7 @@ export interface ClientOptions<TO extends BaseTransportOptions = BaseTransportOp
  * The trace lifecycle, determining whether spans are sent statically when the entire local span tree is complete,
  * or streamed in batches, following interval- and action-based triggers.
  *
- * @default 'static'
+ * @default 'stream'
  */
  traceLifecycle?: 'static' | 'stream';
 

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

@@ -103,7 +103,21 @@ describe('Client', () => {
  const options = getDefaultTestClientOptions({ dsn: PUBLIC_DSN, test: true });
  const client = new TestClient(options);
 
- expect(client.getOptions()).toEqual({ attachStacktrace: true, ...options });
+ expect(client.getOptions()).toEqual({ attachStacktrace: true, traceLifecycle: 'stream', ...options });
+ });
+
+ test('defaults traceLifecycle to stream', () => {
+ const options = getDefaultTestClientOptions();
+ delete options.traceLifecycle;
+ const client = new TestClient(options);
+
+ expect(client.getOptions().traceLifecycle).toBe('stream');
+ });
+
+ test('preserves an explicit static traceLifecycle', () => {
+ const client = new TestClient(getDefaultTestClientOptions({ traceLifecycle: 'static' }));
+
+ expect(client.getOptions().traceLifecycle).toBe('static');
  });
  });
 

packages/deno/test/sdk.test.ts

@@ -8,17 +8,17 @@ Deno.test('init() should return client', () => {
  assertNotEquals(init({}), undefined);
 });
 
-Deno.test('adds spanStreamingIntegration when traceLifecycle is "stream"', () => {
- const client = init({ traceLifecycle: 'stream' });
+Deno.test('adds spanStreamingIntegration by default', () => {
+ const client = init({});
  const integrations = client.getOptions().integrations;
  assertArrayIncludes(
  integrations.map(i => i.name),
  ['SpanStreaming'],
  );
 });
 
-Deno.test('doesn\'t add spanStreamingIntegration when traceLifecycle is not "stream"', () => {
- const client = init({});
+Deno.test('doesn\'t add spanStreamingIntegration when traceLifecycle is "static"', () => {
+ const client = init({ traceLifecycle: 'static' });
  const integrations = client.getOptions().integrations;
  assert(!integrations.some(i => i.name === 'SpanStreaming'));
 });

packages/node/src/sdk/index.ts

@@ -300,6 +300,7 @@ function getClientOptions(
  const spotlight = getSpotlightConfig(options.spotlight);
 
  const tracesSampleRate = getTracesSampleRate(options.tracesSampleRate);
+ const traceLifecycle = getTraceLifecycle(options.traceLifecycle);
 
  const mergedOptions = {
  ...options,
@@ -311,6 +312,7 @@ function getClientOptions(
  release,
  tracesSampleRate,
  spotlight,
+ traceLifecycle,
  debug: envToBool(options.debug ?? process.env.SENTRY_DEBUG),
  };
 
@@ -355,6 +357,20 @@ function getTracesSampleRate(tracesSampleRate: NodeOptions['tracesSampleRate']):
  return isFinite(parsed) ? parsed : undefined;
 }
 
+function getTraceLifecycle(traceLifecycle: NodeOptions['traceLifecycle']): 'stream' | 'static' {
+ if (traceLifecycle !== undefined) {
+ return traceLifecycle;
+ }
+
+ const lifecycleFromEnv = process.env.SENTRY_TRACE_LIFECYCLE;
+
+ if (lifecycleFromEnv === 'stream' || lifecycleFromEnv === 'static') {
+ return lifecycleFromEnv;
+ }
+
+ return 'stream';
+}
+
 /**
  * Update scope and propagation context based on environmental variables.
  *

packages/node/test/sdk/init.test.ts

@@ -59,16 +59,12 @@ describe('init()', () => {
  });
 
  describe('integrations', () => {
- it("doesn't install default integrations if told not to", () => {
+ it('only installs the required spanStreaming integration if default integrations are disabled', () => {
  init({ dsn: PUBLIC_DSN, defaultIntegrations: false });
 
  const client = getClient();
 
- expect(client?.getOptions()).toEqual(
- expect.objectContaining({
- integrations: [],
- }),
- );
+ expect(client?.getOptions().integrations.map(integration => integration.name)).toEqual(['SpanStreaming']);
 
  expect(mockAutoPerformanceIntegrations).toHaveBeenCalledTimes(0);
  });
@@ -169,8 +165,8 @@ describe('init()', () => {
  );
  });
 
- it('installs spanStreaming integration when traceLifecycle is "stream"', () => {
- init({ dsn: PUBLIC_DSN, traceLifecycle: 'stream' });
+ it('installs spanStreaming integration by default', () => {
+ init({ dsn: PUBLIC_DSN });
  const client = getClient();
 
  expect(client?.getOptions()).toEqual(
@@ -180,8 +176,8 @@ describe('init()', () => {
  );
  });
 
- it("doesn't install spanStreaming integration when traceLifecycle is not 'stream'", () => {
- init({ dsn: PUBLIC_DSN });
+ it("doesn't install spanStreaming integration when traceLifecycle is 'static'", () => {
+ init({ dsn: PUBLIC_DSN, traceLifecycle: 'static' });
 
  const client = getClient();
  expect(client?.getOptions()).toEqual(
@@ -192,7 +188,7 @@ describe('init()', () => {
  });
 
  it('installs spanStreaming integration even with custom defaultIntegrations', () => {
- init({ dsn: PUBLIC_DSN, traceLifecycle: 'stream', defaultIntegrations: [] });
+ init({ dsn: PUBLIC_DSN, defaultIntegrations: [] });
  const client = getClient();
 
  expect(client?.getOptions()).toEqual(

dev-packages/browser-integration-tests/loader-suites/loader/noOnLoad/pageloadTransaction/test.ts

@@ -1,27 +1,21 @@
 import { expect } from '@playwright/test';
 import { sentryTest } from '../../../../utils/fixtures';
-import {
- envelopeRequestParser,
- shouldSkipTracingTest,
- waitForTransactionRequestOnUrl,
-} from '../../../../utils/helpers';
+import { shouldSkipTracingTest } from '../../../../utils/helpers';
+import { getSpanOp, waitForStreamedSpan } from '../../../../utils/spanUtils';
 
-sentryTest('should create a pageload transaction', async ({ getLocalTestUrl, page }) => {
+sentryTest('should create a pageload span', async ({ getLocalTestUrl, page }) => {
  if (shouldSkipTracingTest()) {
  sentryTest.skip();
  }
 
+ const spanPromise = waitForStreamedSpan(page, s => getSpanOp(s) === 'pageload');
  const url = await getLocalTestUrl({ testDir: __dirname });
- const req = await waitForTransactionRequestOnUrl(page, url);
+ await page.goto(url);
+ const pageloadSpan = await spanPromise;
 
- const eventData = envelopeRequestParser(req);
  const timeOrigin = await page.evaluate<number>('window._testBaseTimestamp');
 
-const { start_timestamp: startTimestamp } = eventData;
+expect(pageloadSpan.start_timestamp).toBeCloseTo(timeOrigin, 1);
 
- expect(startTimestamp).toBeCloseTo(timeOrigin, 1);
-
- expect(eventData.contexts?.trace?.op).toBe('pageload');
- expect(eventData.spans?.length).toBeGreaterThan(0);
- expect(eventData.transaction_info?.source).toEqual('url');
+ expect(pageloadSpan.attributes?.['sentry.segment.name.source'].value).toEqual('url');
 });

dev-packages/e2e-tests/test-applications/astro-5-cf-workers/wrangler.jsonc

@@ -9,6 +9,7 @@
  "SENTRY_ENVIRONMENT": "qa",
  "SENTRY_TRACES_SAMPLE_RATE": "1.0",
  "SENTRY_TUNNEL": "http://localhost:3031/",
+ "SENTRY_TRACE_LIFECYCLE": "static",
  },
  "assets": {
  "binding": "ASSETS",

dev-packages/e2e-tests/test-applications/aws-serverless-layer/src/stack.ts

@@ -77,6 +77,7 @@ export class LocalLambdaStack extends Stack {
  Variables: {
  SENTRY_TRACES_SAMPLE_RATE: 1.0,
  SENTRY_DEBUG: true,
+ SENTRY_TRACE_LIFECYCLE: 'static',
  NODE_OPTIONS: `--import=@sentry/aws-serverless/awslambda-auto`,
  // We only set SENTRY_DSN if not running TunnelNoDsn, because there
  // we want to test that the extension tunnel forwards requests when SENTRY_DSN is missing.

dev-packages/e2e-tests/test-applications/aws-serverless/src/stack.ts

@@ -112,6 +112,7 @@ export class LocalLambdaStack extends Stack {
  SENTRY_DSN: dsn,
  SENTRY_TRACES_SAMPLE_RATE: 1.0,
  SENTRY_DEBUG: true,
+ SENTRY_TRACE_LIFECYCLE: 'static',
  NODE_OPTIONS: `--import=@sentry/aws-serverless/awslambda-auto`,
  },
  },

packages/browser/src/integrations/spanstreaming.ts

@@ -14,16 +14,6 @@ export const spanStreamingIntegration = defineIntegration(() => {
  return {
  name: 'SpanStreaming' as const,
 
- beforeSetup(client) {
- // If users only set spanStreamingIntegration, without traceLifecycle, we set it to "stream" for them.
- // This avoids the classic double-opt-in problem we'd otherwise have in the browser SDK.
- const clientOptions = client.getOptions();
- if (!clientOptions.traceLifecycle) {
- DEBUG_BUILD && debug.log('[SpanStreaming] setting `traceLifecycle` to "stream"');
- clientOptions.traceLifecycle = 'stream';
- }
- },
-
  setup(client) {
  const initialMessage = 'SpanStreaming integration requires';
  const fallbackMsg = 'Falling back to static trace lifecycle.';

packages/browser/src/sdk.ts

@@ -19,6 +19,7 @@ import { globalHandlersIntegration } from './integrations/globalhandlers';
 import { httpContextIntegration } from './integrations/httpcontext';
 import { linkedErrorsIntegration } from './integrations/linkederrors';
 import { spotlightBrowserIntegration } from './integrations/spotlight';
+import { spanStreamingIntegration } from './integrations/spanstreaming';
 import { defaultStackParser } from './stack-parsers';
 import { makeFetchTransport } from './transports/fetch';
 import { normalizeStringifyValue } from './normalizeStringifyValue';
@@ -110,14 +111,22 @@ export function init(options: BrowserOptions = {}): Client | undefined {
  }
  /*! rollup-include-development-only-end */
 
+ const integrations = getIntegrationsToSetup({
+ integrations: options.integrations,
+ defaultIntegrations,
+ });
+
+ options.traceLifecycle ??= 'stream';
+
+ if (options.traceLifecycle === 'stream' && !integrations.some(integration => integration.name === 'SpanStreaming')) {
+ integrations.push(spanStreamingIntegration());
+ }
+
  const clientOptions: BrowserClientOptions = {
  ...options,
  enabled: shouldDisableBecauseIsBrowserExtenstion ? false : options.enabled,
  stackParser: stackParserFromStackParserOptions(options.stackParser || defaultStackParser),
- integrations: getIntegrationsToSetup({
- integrations: options.integrations,
- defaultIntegrations,
- }),
+ integrations,
  transport: options.transport || makeFetchTransport,
  };
 

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

@@ -37,24 +37,9 @@ describe('spanStreamingIntegration', () => {
  const integration = spanStreamingIntegration();
  expect(integration.name).toBe('SpanStreaming');
  // eslint-disable-next-line @typescript-eslint/unbound-method
- expect(integration.beforeSetup).toBeDefined();
- // eslint-disable-next-line @typescript-eslint/unbound-method
  expect(integration.setup).toBeDefined();
  });
 
- it('sets traceLifecycle to "stream" if not set', () => {
- const client = new BrowserClient({
- ...getDefaultBrowserClientOptions(),
- dsn: 'https://username@domain/123',
- integrations: [spanStreamingIntegration()],
- });
-
- SentryCore.setCurrentClient(client);
- client.init();
-
- expect(client.getOptions().traceLifecycle).toBe('stream');
- });
-
  it.each(['static', 'somethingElse'])(
  'logs a warning if traceLifecycle is not set to "stream" but to %s',
  traceLifecycle => {

packages/browser/test/sdk.test.ts

@@ -61,6 +61,32 @@ describe('init', () => {
  expect(optionsPassed?.integrations.length).toBeGreaterThan(0);
  });
 
+ it('installs spanStreamingIntegration by default', () => {
+ // @ts-expect-error this is fine for testing
+ const initAndBindSpy = vi.spyOn(SentryCore, 'initAndBind').mockImplementationOnce(() => {});
+ const options = getDefaultBrowserOptions({ dsn: PUBLIC_DSN, defaultIntegrations: undefined });
+
+ init(options);
+
+ const optionsPassed = initAndBindSpy.mock.calls[0]?.[1];
+ expect(optionsPassed?.integrations.some(integration => integration.name === 'SpanStreaming')).toBe(true);
+ });
+
+ it('does not install spanStreamingIntegration when traceLifecycle is static', () => {
+ // @ts-expect-error this is fine for testing
+ const initAndBindSpy = vi.spyOn(SentryCore, 'initAndBind').mockImplementationOnce(() => {});
+ const options = getDefaultBrowserOptions({
+ dsn: PUBLIC_DSN,
+ defaultIntegrations: undefined,
+ traceLifecycle: 'static',
+ });
+
+ init(options);
+
+ const optionsPassed = initAndBindSpy.mock.calls[0]?.[1];
+ expect(optionsPassed?.integrations.some(integration => integration.name === 'SpanStreaming')).toBe(false);
+ });
+
  test("doesn't install default integrations if told not to", () => {
  const DEFAULT_INTEGRATIONS: Integration[] = [
  new MockIntegration('MockIntegration 0.3'),
@@ -73,6 +99,17 @@ describe('init', () => {
  expect(DEFAULT_INTEGRATIONS[1]!.setupOnce as Mock).toHaveBeenCalledTimes(0);
  });
 
+ it('installs spanStreamingIntegration with defaultIntegrations disabled', () => {
+ // @ts-expect-error this is fine for testing
+ const initAndBindSpy = vi.spyOn(SentryCore, 'initAndBind').mockImplementationOnce(() => {});
+ const options = getDefaultBrowserOptions({ dsn: PUBLIC_DSN, defaultIntegrations: false });
+
+ init(options);
+
+ const optionsPassed = initAndBindSpy.mock.calls[0]?.[1];
+ expect(optionsPassed?.integrations.some(integration => integration.name === 'SpanStreaming')).toBe(true);
+ });
+
  it('installs merged default integrations, with overrides provided through options', () => {
  const DEFAULT_INTEGRATIONS = [
  new MockIntegration('MockIntegration 1.1'),

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

@@ -27,6 +27,7 @@ export function createSentryInstance(
  dsn: 'https://4c2bae7d9fbc413e8f7385f55c515d51@o1.ingest.sentry.io/6690737',
 
  tracesSampleRate: 1,
+ traceLifecycle: 'static',
  sampleRate: 1,
 
  release: LIB_VERSION,

packages/cloudflare/src/options.ts

@@ -70,6 +70,7 @@ export function getFinalOptions(userOptions: CloudflareOptions = {}, env: unknow
  tracesSampleRate: isFinite(tracesSampleRate) ? tracesSampleRate : undefined,
  debug: userOptions.debug ?? envToBool(getEnvVar(env, 'SENTRY_DEBUG')),
  tunnel: userOptions.tunnel ?? getEnvVar(env, 'SENTRY_TUNNEL'),
+ traceLifecycle: userOptions.traceLifecycle ?? getTraceLifecycleFromEnv(getEnvVar(env, 'SENTRY_TRACE_LIFECYCLE')),
  /*! rollup-include-development-only */
  spotlight,
  /*! rollup-include-development-only-end */
@@ -102,3 +103,7 @@ function getSpotlightFromEnv(
  ? (envUrl ?? true) // true: use env URL if present, otherwise true
  : (envBool ?? envUrl); // undefined: use env var (bool or URL)
 }
+
+function getTraceLifecycleFromEnv(envVar: string | undefined): 'static' | 'stream' | undefined {
+ return envVar === 'stream' || envVar === 'static' ? envVar : undefined;
+}

packages/cloudflare/test/sdk.test.ts

@@ -22,10 +22,9 @@ describe('init', () => {
  expect(client).toBeInstanceOf(CloudflareClient);
  });
 
- test('installs SpanStreaming integration when traceLifecycle is "stream"', () => {
+ test('installs SpanStreaming integration by default', () => {
  init({
  dsn: 'https://public@dsn.ingest.sentry.io/1337',
- traceLifecycle: 'stream',
  });
  const client = getClient();
 
@@ -36,8 +35,8 @@ describe('init', () => {
  );
  });
 
- test("does not install SpanStreaming integration when traceLifecycle is not 'stream'", () => {
- init({ dsn: 'https://public@dsn.ingest.sentry.io/1337' });
+ test("does not install SpanStreaming integration when traceLifecycle is 'static'", () => {
+ init({ dsn: 'https://public@dsn.ingest.sentry.io/1337', traceLifecycle: 'static' });
  const client = getClient();
 
  expect(client?.getOptions()).toEqual(

packages/core/src/client.ts

@@ -234,7 +234,7 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
  * @param options Options for the client.
  */
  protected constructor(options: O) {
- this._options = { attachStacktrace: true, ...options };
+ this._options = { attachStacktrace: true, traceLifecycle: 'stream', ...options };
  this._integrations = {};
  this._numProcessing = 0;
  this._outcomes = {};

packages/core/src/server-runtime-client.ts

@@ -40,6 +40,8 @@ export class ServerRuntimeClient<
  public constructor(options: O) {
  addUserAgentToTransportHeaders(options);
 
+ options.traceLifecycle ??= 'stream';
+
  // When span streaming is enabled (`traceLifecycle: 'stream'`), the `spanStreamingIntegration`
  // is required to flush spans. We add it here so the individual server SDKs don't have to.
  // A user-provided `spanStreamingIntegration` always takes precedence over the one we add.

packages/core/src/types/options.ts

@@ -543,7 +543,7 @@ export interface ClientOptions<TO extends BaseTransportOptions = BaseTransportOp
  * The trace lifecycle, determining whether spans are sent statically when the entire local span tree is complete,
  * or streamed in batches, following interval- and action-based triggers.
  *
- * @default 'static'
+ * @default 'stream'
  */
  traceLifecycle?: 'static' | 'stream';
 

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

@@ -103,7 +103,21 @@ describe('Client', () => {
  const options = getDefaultTestClientOptions({ dsn: PUBLIC_DSN, test: true });
  const client = new TestClient(options);
 
- expect(client.getOptions()).toEqual({ attachStacktrace: true, ...options });
+ expect(client.getOptions()).toEqual({ attachStacktrace: true, traceLifecycle: 'stream', ...options });
+ });
+
+ test('defaults traceLifecycle to stream', () => {
+ const options = getDefaultTestClientOptions();
+ delete options.traceLifecycle;
+ const client = new TestClient(options);
+
+ expect(client.getOptions().traceLifecycle).toBe('stream');
+ });
+
+ test('preserves an explicit static traceLifecycle', () => {
+ const client = new TestClient(getDefaultTestClientOptions({ traceLifecycle: 'static' }));
+
+ expect(client.getOptions().traceLifecycle).toBe('static');
  });
  });
 

packages/deno/test/sdk.test.ts

@@ -8,17 +8,17 @@ Deno.test('init() should return client', () => {
  assertNotEquals(init({}), undefined);
 });
 
-Deno.test('adds spanStreamingIntegration when traceLifecycle is "stream"', () => {
- const client = init({ traceLifecycle: 'stream' });
+Deno.test('adds spanStreamingIntegration by default', () => {
+ const client = init({});
  const integrations = client.getOptions().integrations;
  assertArrayIncludes(
  integrations.map(i => i.name),
  ['SpanStreaming'],
  );
 });
 
-Deno.test('doesn\'t add spanStreamingIntegration when traceLifecycle is not "stream"', () => {
- const client = init({});
+Deno.test('doesn\'t add spanStreamingIntegration when traceLifecycle is "static"', () => {
+ const client = init({ traceLifecycle: 'static' });
  const integrations = client.getOptions().integrations;
  assert(!integrations.some(i => i.name === 'SpanStreaming'));
 });

packages/node/src/sdk/index.ts

@@ -300,6 +300,7 @@ function getClientOptions(
  const spotlight = getSpotlightConfig(options.spotlight);
 
  const tracesSampleRate = getTracesSampleRate(options.tracesSampleRate);
+ const traceLifecycle = getTraceLifecycle(options.traceLifecycle);
 
  const mergedOptions = {
  ...options,
@@ -311,6 +312,7 @@ function getClientOptions(
  release,
  tracesSampleRate,
  spotlight,
+ traceLifecycle,
  debug: envToBool(options.debug ?? process.env.SENTRY_DEBUG),
  };
 
@@ -355,6 +357,20 @@ function getTracesSampleRate(tracesSampleRate: NodeOptions['tracesSampleRate']):
  return isFinite(parsed) ? parsed : undefined;
 }
 
+function getTraceLifecycle(traceLifecycle: NodeOptions['traceLifecycle']): 'stream' | 'static' {
+ if (traceLifecycle !== undefined) {
+ return traceLifecycle;
+ }
+
+ const lifecycleFromEnv = process.env.SENTRY_TRACE_LIFECYCLE;
+
+ if (lifecycleFromEnv === 'stream' || lifecycleFromEnv === 'static') {
+ return lifecycleFromEnv;
+ }
+
+ return 'stream';
+}
+
 /**
  * Update scope and propagation context based on environmental variables.
  *

packages/node/test/sdk/init.test.ts

@@ -59,16 +59,12 @@ describe('init()', () => {
  });
 
  describe('integrations', () => {
- it("doesn't install default integrations if told not to", () => {
+ it('only installs the required spanStreaming integration if default integrations are disabled', () => {
  init({ dsn: PUBLIC_DSN, defaultIntegrations: false });
 
  const client = getClient();
 
- expect(client?.getOptions()).toEqual(
- expect.objectContaining({
- integrations: [],
- }),
- );
+ expect(client?.getOptions().integrations.map(integration => integration.name)).toEqual(['SpanStreaming']);
 
  expect(mockAutoPerformanceIntegrations).toHaveBeenCalledTimes(0);
  });
@@ -169,8 +165,8 @@ describe('init()', () => {
  );
  });
 
- it('installs spanStreaming integration when traceLifecycle is "stream"', () => {
- init({ dsn: PUBLIC_DSN, traceLifecycle: 'stream' });
+ it('installs spanStreaming integration by default', () => {
+ init({ dsn: PUBLIC_DSN });
  const client = getClient();
 
  expect(client?.getOptions()).toEqual(
@@ -180,8 +176,8 @@ describe('init()', () => {
  );
  });
 
- it("doesn't install spanStreaming integration when traceLifecycle is not 'stream'", () => {
- init({ dsn: PUBLIC_DSN });
+ it("doesn't install spanStreaming integration when traceLifecycle is 'static'", () => {
+ init({ dsn: PUBLIC_DSN, traceLifecycle: 'static' });
 
  const client = getClient();
  expect(client?.getOptions()).toEqual(
@@ -192,7 +188,7 @@ describe('init()', () => {
  });
 
  it('installs spanStreaming integration even with custom defaultIntegrations', () => {
- init({ dsn: PUBLIC_DSN, traceLifecycle: 'stream', defaultIntegrations: [] });
+ init({ dsn: PUBLIC_DSN, defaultIntegrations: [] });
  const client = getClient();
 
  expect(client?.getOptions()).toEqual(

dev-packages/browser-integration-tests/loader-suites/loader/noOnLoad/pageloadTransaction/test.ts

@@ -1,27 +1,21 @@
 import { expect } from '@playwright/test';
 import { sentryTest } from '../../../../utils/fixtures';
-import {
- envelopeRequestParser,
- shouldSkipTracingTest,
- waitForTransactionRequestOnUrl,
-} from '../../../../utils/helpers';
+import { shouldSkipTracingTest } from '../../../../utils/helpers';
+import { getSpanOp, waitForStreamedSpan } from '../../../../utils/spanUtils';
 
-sentryTest('should create a pageload transaction', async ({ getLocalTestUrl, page }) => {
+sentryTest('should create a pageload span', async ({ getLocalTestUrl, page }) => {
  if (shouldSkipTracingTest()) {
  sentryTest.skip();
  }
 
+ const spanPromise = waitForStreamedSpan(page, s => getSpanOp(s) === 'pageload');
  const url = await getLocalTestUrl({ testDir: __dirname });
- const req = await waitForTransactionRequestOnUrl(page, url);
+ await page.goto(url);
+ const pageloadSpan = await spanPromise;
 
- const eventData = envelopeRequestParser(req);
  const timeOrigin = await page.evaluate<number>('window._testBaseTimestamp');
 
-const { start_timestamp: startTimestamp } = eventData;
+expect(pageloadSpan.start_timestamp).toBeCloseTo(timeOrigin, 1);
 
- expect(startTimestamp).toBeCloseTo(timeOrigin, 1);
-
- expect(eventData.contexts?.trace?.op).toBe('pageload');
- expect(eventData.spans?.length).toBeGreaterThan(0);
- expect(eventData.transaction_info?.source).toEqual('url');
+ expect(pageloadSpan.attributes?.['sentry.segment.name.source'].value).toEqual('url');
 });

dev-packages/e2e-tests/test-applications/astro-5-cf-workers/wrangler.jsonc

@@ -9,6 +9,7 @@
  "SENTRY_ENVIRONMENT": "qa",
  "SENTRY_TRACES_SAMPLE_RATE": "1.0",
  "SENTRY_TUNNEL": "http://localhost:3031/",
+ "SENTRY_TRACE_LIFECYCLE": "static",
  },
  "assets": {
  "binding": "ASSETS",

dev-packages/e2e-tests/test-applications/aws-serverless-layer/src/stack.ts

@@ -77,6 +77,7 @@ export class LocalLambdaStack extends Stack {
  Variables: {
  SENTRY_TRACES_SAMPLE_RATE: 1.0,
  SENTRY_DEBUG: true,
+ SENTRY_TRACE_LIFECYCLE: 'static',
  NODE_OPTIONS: `--import=@sentry/aws-serverless/awslambda-auto`,
  // We only set SENTRY_DSN if not running TunnelNoDsn, because there
  // we want to test that the extension tunnel forwards requests when SENTRY_DSN is missing.

dev-packages/e2e-tests/test-applications/aws-serverless/src/stack.ts

@@ -112,6 +112,7 @@ export class LocalLambdaStack extends Stack {
  SENTRY_DSN: dsn,
  SENTRY_TRACES_SAMPLE_RATE: 1.0,
  SENTRY_DEBUG: true,
+ SENTRY_TRACE_LIFECYCLE: 'static',
  NODE_OPTIONS: `--import=@sentry/aws-serverless/awslambda-auto`,
  },
  },

packages/browser/src/integrations/spanstreaming.ts

@@ -14,16 +14,6 @@ export const spanStreamingIntegration = defineIntegration(() => {
  return {
  name: 'SpanStreaming' as const,
 
- beforeSetup(client) {
- // If users only set spanStreamingIntegration, without traceLifecycle, we set it to "stream" for them.
- // This avoids the classic double-opt-in problem we'd otherwise have in the browser SDK.
- const clientOptions = client.getOptions();
- if (!clientOptions.traceLifecycle) {
- DEBUG_BUILD && debug.log('[SpanStreaming] setting `traceLifecycle` to "stream"');
- clientOptions.traceLifecycle = 'stream';
- }
- },
-
  setup(client) {
  const initialMessage = 'SpanStreaming integration requires';
  const fallbackMsg = 'Falling back to static trace lifecycle.';

packages/browser/src/sdk.ts

@@ -19,6 +19,7 @@ import { globalHandlersIntegration } from './integrations/globalhandlers';
 import { httpContextIntegration } from './integrations/httpcontext';
 import { linkedErrorsIntegration } from './integrations/linkederrors';
 import { spotlightBrowserIntegration } from './integrations/spotlight';
+import { spanStreamingIntegration } from './integrations/spanstreaming';
 import { defaultStackParser } from './stack-parsers';
 import { makeFetchTransport } from './transports/fetch';
 import { normalizeStringifyValue } from './normalizeStringifyValue';
@@ -110,14 +111,22 @@ export function init(options: BrowserOptions = {}): Client | undefined {
  }
  /*! rollup-include-development-only-end */
 
+ const integrations = getIntegrationsToSetup({
+ integrations: options.integrations,
+ defaultIntegrations,
+ });
+
+ options.traceLifecycle ??= 'stream';
+
+ if (options.traceLifecycle === 'stream' && !integrations.some(integration => integration.name === 'SpanStreaming')) {
+ integrations.push(spanStreamingIntegration());
+ }
+
  const clientOptions: BrowserClientOptions = {
  ...options,
  enabled: shouldDisableBecauseIsBrowserExtenstion ? false : options.enabled,
  stackParser: stackParserFromStackParserOptions(options.stackParser || defaultStackParser),
- integrations: getIntegrationsToSetup({
- integrations: options.integrations,
- defaultIntegrations,
- }),
+ integrations,
  transport: options.transport || makeFetchTransport,
  };
 

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

@@ -37,24 +37,9 @@ describe('spanStreamingIntegration', () => {
  const integration = spanStreamingIntegration();
  expect(integration.name).toBe('SpanStreaming');
  // eslint-disable-next-line @typescript-eslint/unbound-method
- expect(integration.beforeSetup).toBeDefined();
- // eslint-disable-next-line @typescript-eslint/unbound-method
  expect(integration.setup).toBeDefined();
  });
 
- it('sets traceLifecycle to "stream" if not set', () => {
- const client = new BrowserClient({
- ...getDefaultBrowserClientOptions(),
- dsn: 'https://username@domain/123',
- integrations: [spanStreamingIntegration()],
- });
-
- SentryCore.setCurrentClient(client);
- client.init();
-
- expect(client.getOptions().traceLifecycle).toBe('stream');
- });
-
  it.each(['static', 'somethingElse'])(
  'logs a warning if traceLifecycle is not set to "stream" but to %s',
  traceLifecycle => {

packages/browser/test/sdk.test.ts

@@ -61,6 +61,32 @@ describe('init', () => {
  expect(optionsPassed?.integrations.length).toBeGreaterThan(0);
  });
 
+ it('installs spanStreamingIntegration by default', () => {
+ // @ts-expect-error this is fine for testing
+ const initAndBindSpy = vi.spyOn(SentryCore, 'initAndBind').mockImplementationOnce(() => {});
+ const options = getDefaultBrowserOptions({ dsn: PUBLIC_DSN, defaultIntegrations: undefined });
+
+ init(options);
+
+ const optionsPassed = initAndBindSpy.mock.calls[0]?.[1];
+ expect(optionsPassed?.integrations.some(integration => integration.name === 'SpanStreaming')).toBe(true);
+ });
+
+ it('does not install spanStreamingIntegration when traceLifecycle is static', () => {
+ // @ts-expect-error this is fine for testing
+ const initAndBindSpy = vi.spyOn(SentryCore, 'initAndBind').mockImplementationOnce(() => {});
+ const options = getDefaultBrowserOptions({
+ dsn: PUBLIC_DSN,
+ defaultIntegrations: undefined,
+ traceLifecycle: 'static',
+ });
+
+ init(options);
+
+ const optionsPassed = initAndBindSpy.mock.calls[0]?.[1];
+ expect(optionsPassed?.integrations.some(integration => integration.name === 'SpanStreaming')).toBe(false);
+ });
+
  test("doesn't install default integrations if told not to", () => {
  const DEFAULT_INTEGRATIONS: Integration[] = [
  new MockIntegration('MockIntegration 0.3'),
@@ -73,6 +99,17 @@ describe('init', () => {
  expect(DEFAULT_INTEGRATIONS[1]!.setupOnce as Mock).toHaveBeenCalledTimes(0);
  });
 
+ it('installs spanStreamingIntegration with defaultIntegrations disabled', () => {
+ // @ts-expect-error this is fine for testing
+ const initAndBindSpy = vi.spyOn(SentryCore, 'initAndBind').mockImplementationOnce(() => {});
+ const options = getDefaultBrowserOptions({ dsn: PUBLIC_DSN, defaultIntegrations: false });
+
+ init(options);
+
+ const optionsPassed = initAndBindSpy.mock.calls[0]?.[1];
+ expect(optionsPassed?.integrations.some(integration => integration.name === 'SpanStreaming')).toBe(true);
+ });
+
  it('installs merged default integrations, with overrides provided through options', () => {
  const DEFAULT_INTEGRATIONS = [
  new MockIntegration('MockIntegration 1.1'),

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

@@ -27,6 +27,7 @@ export function createSentryInstance(
  dsn: 'https://4c2bae7d9fbc413e8f7385f55c515d51@o1.ingest.sentry.io/6690737',
 
  tracesSampleRate: 1,
+ traceLifecycle: 'static',
  sampleRate: 1,
 
  release: LIB_VERSION,

packages/cloudflare/src/options.ts

@@ -70,6 +70,7 @@ export function getFinalOptions(userOptions: CloudflareOptions = {}, env: unknow
  tracesSampleRate: isFinite(tracesSampleRate) ? tracesSampleRate : undefined,
  debug: userOptions.debug ?? envToBool(getEnvVar(env, 'SENTRY_DEBUG')),
  tunnel: userOptions.tunnel ?? getEnvVar(env, 'SENTRY_TUNNEL'),
+ traceLifecycle: userOptions.traceLifecycle ?? getTraceLifecycleFromEnv(getEnvVar(env, 'SENTRY_TRACE_LIFECYCLE')),
  /*! rollup-include-development-only */
  spotlight,
  /*! rollup-include-development-only-end */
@@ -102,3 +103,7 @@ function getSpotlightFromEnv(
  ? (envUrl ?? true) // true: use env URL if present, otherwise true
  : (envBool ?? envUrl); // undefined: use env var (bool or URL)
 }
+
+function getTraceLifecycleFromEnv(envVar: string | undefined): 'static' | 'stream' | undefined {
+ return envVar === 'stream' || envVar === 'static' ? envVar : undefined;
+}

packages/cloudflare/test/sdk.test.ts

@@ -22,10 +22,9 @@ describe('init', () => {
  expect(client).toBeInstanceOf(CloudflareClient);
  });
 
- test('installs SpanStreaming integration when traceLifecycle is "stream"', () => {
+ test('installs SpanStreaming integration by default', () => {
  init({
  dsn: 'https://public@dsn.ingest.sentry.io/1337',
- traceLifecycle: 'stream',
  });
  const client = getClient();
 
@@ -36,8 +35,8 @@ describe('init', () => {
  );
  });
 
- test("does not install SpanStreaming integration when traceLifecycle is not 'stream'", () => {
- init({ dsn: 'https://public@dsn.ingest.sentry.io/1337' });
+ test("does not install SpanStreaming integration when traceLifecycle is 'static'", () => {
+ init({ dsn: 'https://public@dsn.ingest.sentry.io/1337', traceLifecycle: 'static' });
  const client = getClient();
 
  expect(client?.getOptions()).toEqual(

packages/core/src/client.ts

@@ -234,7 +234,7 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
  * @param options Options for the client.
  */
  protected constructor(options: O) {
- this._options = { attachStacktrace: true, ...options };
+ this._options = { attachStacktrace: true, traceLifecycle: 'stream', ...options };
  this._integrations = {};
  this._numProcessing = 0;
  this._outcomes = {};

packages/core/src/server-runtime-client.ts

@@ -40,6 +40,8 @@ export class ServerRuntimeClient<
  public constructor(options: O) {
  addUserAgentToTransportHeaders(options);
 
+ options.traceLifecycle ??= 'stream';
+
  // When span streaming is enabled (`traceLifecycle: 'stream'`), the `spanStreamingIntegration`
  // is required to flush spans. We add it here so the individual server SDKs don't have to.
  // A user-provided `spanStreamingIntegration` always takes precedence over the one we add.

packages/core/src/types/options.ts

@@ -543,7 +543,7 @@ export interface ClientOptions<TO extends BaseTransportOptions = BaseTransportOp
  * The trace lifecycle, determining whether spans are sent statically when the entire local span tree is complete,
  * or streamed in batches, following interval- and action-based triggers.
  *
- * @default 'static'
+ * @default 'stream'
  */
  traceLifecycle?: 'static' | 'stream';
 

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

@@ -103,7 +103,21 @@ describe('Client', () => {
  const options = getDefaultTestClientOptions({ dsn: PUBLIC_DSN, test: true });
  const client = new TestClient(options);
 
- expect(client.getOptions()).toEqual({ attachStacktrace: true, ...options });
+ expect(client.getOptions()).toEqual({ attachStacktrace: true, traceLifecycle: 'stream', ...options });
+ });
+
+ test('defaults traceLifecycle to stream', () => {
+ const options = getDefaultTestClientOptions();
+ delete options.traceLifecycle;
+ const client = new TestClient(options);
+
+ expect(client.getOptions().traceLifecycle).toBe('stream');
+ });
+
+ test('preserves an explicit static traceLifecycle', () => {
+ const client = new TestClient(getDefaultTestClientOptions({ traceLifecycle: 'static' }));
+
+ expect(client.getOptions().traceLifecycle).toBe('static');
  });
  });
 

packages/deno/test/sdk.test.ts

@@ -8,17 +8,17 @@ Deno.test('init() should return client', () => {
  assertNotEquals(init({}), undefined);
 });
 
-Deno.test('adds spanStreamingIntegration when traceLifecycle is "stream"', () => {
- const client = init({ traceLifecycle: 'stream' });
+Deno.test('adds spanStreamingIntegration by default', () => {
+ const client = init({});
  const integrations = client.getOptions().integrations;
  assertArrayIncludes(
  integrations.map(i => i.name),
  ['SpanStreaming'],
  );
 });
 
-Deno.test('doesn\'t add spanStreamingIntegration when traceLifecycle is not "stream"', () => {
- const client = init({});
+Deno.test('doesn\'t add spanStreamingIntegration when traceLifecycle is "static"', () => {
+ const client = init({ traceLifecycle: 'static' });
  const integrations = client.getOptions().integrations;
  assert(!integrations.some(i => i.name === 'SpanStreaming'));
 });

packages/node/src/sdk/index.ts

@@ -300,6 +300,7 @@ function getClientOptions(
  const spotlight = getSpotlightConfig(options.spotlight);
 
  const tracesSampleRate = getTracesSampleRate(options.tracesSampleRate);
+ const traceLifecycle = getTraceLifecycle(options.traceLifecycle);
 
  const mergedOptions = {
  ...options,
@@ -311,6 +312,7 @@ function getClientOptions(
  release,
  tracesSampleRate,
  spotlight,
+ traceLifecycle,
  debug: envToBool(options.debug ?? process.env.SENTRY_DEBUG),
  };
 
@@ -355,6 +357,20 @@ function getTracesSampleRate(tracesSampleRate: NodeOptions['tracesSampleRate']):
  return isFinite(parsed) ? parsed : undefined;
 }
 
+function getTraceLifecycle(traceLifecycle: NodeOptions['traceLifecycle']): 'stream' | 'static' {
+ if (traceLifecycle !== undefined) {
+ return traceLifecycle;
+ }
+
+ const lifecycleFromEnv = process.env.SENTRY_TRACE_LIFECYCLE;
+
+ if (lifecycleFromEnv === 'stream' || lifecycleFromEnv === 'static') {
+ return lifecycleFromEnv;
+ }
+
+ return 'stream';
+}
+
 /**
  * Update scope and propagation context based on environmental variables.
  *

packages/node/test/sdk/init.test.ts

@@ -59,16 +59,12 @@ describe('init()', () => {
  });
 
  describe('integrations', () => {
- it("doesn't install default integrations if told not to", () => {
+ it('only installs the required spanStreaming integration if default integrations are disabled', () => {
  init({ dsn: PUBLIC_DSN, defaultIntegrations: false });
 
  const client = getClient();
 
- expect(client?.getOptions()).toEqual(
- expect.objectContaining({
- integrations: [],
- }),
- );
+ expect(client?.getOptions().integrations.map(integration => integration.name)).toEqual(['SpanStreaming']);
 
  expect(mockAutoPerformanceIntegrations).toHaveBeenCalledTimes(0);
  });
@@ -169,8 +165,8 @@ describe('init()', () => {
  );
  });
 
- it('installs spanStreaming integration when traceLifecycle is "stream"', () => {
- init({ dsn: PUBLIC_DSN, traceLifecycle: 'stream' });
+ it('installs spanStreaming integration by default', () => {
+ init({ dsn: PUBLIC_DSN });
  const client = getClient();
 
  expect(client?.getOptions()).toEqual(
@@ -180,8 +176,8 @@ describe('init()', () => {
  );
  });
 
- it("doesn't install spanStreaming integration when traceLifecycle is not 'stream'", () => {
- init({ dsn: PUBLIC_DSN });
+ it("doesn't install spanStreaming integration when traceLifecycle is 'static'", () => {
+ init({ dsn: PUBLIC_DSN, traceLifecycle: 'static' });
 
  const client = getClient();
  expect(client?.getOptions()).toEqual(
@@ -192,7 +188,7 @@ describe('init()', () => {
  });
 
  it('installs spanStreaming integration even with custom defaultIntegrations', () => {
- init({ dsn: PUBLIC_DSN, traceLifecycle: 'stream', defaultIntegrations: [] });
+ init({ dsn: PUBLIC_DSN, defaultIntegrations: [] });
  const client = getClient();
 
  expect(client?.getOptions()).toEqual(

dev-packages/browser-integration-tests/loader-suites/loader/noOnLoad/pageloadTransaction/test.ts

@@ -1,27 +1,21 @@
 import { expect } from '@playwright/test';
 import { sentryTest } from '../../../../utils/fixtures';
-import {
- envelopeRequestParser,
- shouldSkipTracingTest,
- waitForTransactionRequestOnUrl,
-} from '../../../../utils/helpers';
+import { shouldSkipTracingTest } from '../../../../utils/helpers';
+import { getSpanOp, waitForStreamedSpan } from '../../../../utils/spanUtils';
 
-sentryTest('should create a pageload transaction', async ({ getLocalTestUrl, page }) => {
+sentryTest('should create a pageload span', async ({ getLocalTestUrl, page }) => {
  if (shouldSkipTracingTest()) {
  sentryTest.skip();
  }
 
+ const spanPromise = waitForStreamedSpan(page, s => getSpanOp(s) === 'pageload');
  const url = await getLocalTestUrl({ testDir: __dirname });
- const req = await waitForTransactionRequestOnUrl(page, url);
+ await page.goto(url);
+ const pageloadSpan = await spanPromise;
 
- const eventData = envelopeRequestParser(req);
  const timeOrigin = await page.evaluate<number>('window._testBaseTimestamp');
 
-const { start_timestamp: startTimestamp } = eventData;
+expect(pageloadSpan.start_timestamp).toBeCloseTo(timeOrigin, 1);
 
- expect(startTimestamp).toBeCloseTo(timeOrigin, 1);
-
- expect(eventData.contexts?.trace?.op).toBe('pageload');
- expect(eventData.spans?.length).toBeGreaterThan(0);
- expect(eventData.transaction_info?.source).toEqual('url');
+ expect(pageloadSpan.attributes?.['sentry.segment.name.source'].value).toEqual('url');
 });

dev-packages/e2e-tests/test-applications/astro-5-cf-workers/wrangler.jsonc

@@ -9,6 +9,7 @@
  "SENTRY_ENVIRONMENT": "qa",
  "SENTRY_TRACES_SAMPLE_RATE": "1.0",
  "SENTRY_TUNNEL": "http://localhost:3031/",
+ "SENTRY_TRACE_LIFECYCLE": "static",
  },
  "assets": {
  "binding": "ASSETS",

dev-packages/e2e-tests/test-applications/aws-serverless-layer/src/stack.ts

@@ -77,6 +77,7 @@ export class LocalLambdaStack extends Stack {
  Variables: {
  SENTRY_TRACES_SAMPLE_RATE: 1.0,
  SENTRY_DEBUG: true,
+ SENTRY_TRACE_LIFECYCLE: 'static',
  NODE_OPTIONS: `--import=@sentry/aws-serverless/awslambda-auto`,
  // We only set SENTRY_DSN if not running TunnelNoDsn, because there
  // we want to test that the extension tunnel forwards requests when SENTRY_DSN is missing.

dev-packages/e2e-tests/test-applications/aws-serverless/src/stack.ts

@@ -112,6 +112,7 @@ export class LocalLambdaStack extends Stack {
  SENTRY_DSN: dsn,
  SENTRY_TRACES_SAMPLE_RATE: 1.0,
  SENTRY_DEBUG: true,
+ SENTRY_TRACE_LIFECYCLE: 'static',
  NODE_OPTIONS: `--import=@sentry/aws-serverless/awslambda-auto`,
  },
  },

packages/browser/src/integrations/spanstreaming.ts

@@ -14,16 +14,6 @@ export const spanStreamingIntegration = defineIntegration(() => {
  return {
  name: 'SpanStreaming' as const,
 
- beforeSetup(client) {
- // If users only set spanStreamingIntegration, without traceLifecycle, we set it to "stream" for them.
- // This avoids the classic double-opt-in problem we'd otherwise have in the browser SDK.
- const clientOptions = client.getOptions();
- if (!clientOptions.traceLifecycle) {
- DEBUG_BUILD && debug.log('[SpanStreaming] setting `traceLifecycle` to "stream"');
- clientOptions.traceLifecycle = 'stream';
- }
- },
-
  setup(client) {
  const initialMessage = 'SpanStreaming integration requires';
  const fallbackMsg = 'Falling back to static trace lifecycle.';

packages/browser/src/sdk.ts

@@ -19,6 +19,7 @@ import { globalHandlersIntegration } from './integrations/globalhandlers';
 import { httpContextIntegration } from './integrations/httpcontext';
 import { linkedErrorsIntegration } from './integrations/linkederrors';
 import { spotlightBrowserIntegration } from './integrations/spotlight';
+import { spanStreamingIntegration } from './integrations/spanstreaming';
 import { defaultStackParser } from './stack-parsers';
 import { makeFetchTransport } from './transports/fetch';
 import { normalizeStringifyValue } from './normalizeStringifyValue';
@@ -110,14 +111,22 @@ export function init(options: BrowserOptions = {}): Client | undefined {
  }
  /*! rollup-include-development-only-end */
 
+ const integrations = getIntegrationsToSetup({
+ integrations: options.integrations,
+ defaultIntegrations,
+ });
+
+ options.traceLifecycle ??= 'stream';
+
+ if (options.traceLifecycle === 'stream' && !integrations.some(integration => integration.name === 'SpanStreaming')) {
+ integrations.push(spanStreamingIntegration());
+ }
+
  const clientOptions: BrowserClientOptions = {
  ...options,
  enabled: shouldDisableBecauseIsBrowserExtenstion ? false : options.enabled,
  stackParser: stackParserFromStackParserOptions(options.stackParser || defaultStackParser),
- integrations: getIntegrationsToSetup({
- integrations: options.integrations,
- defaultIntegrations,
- }),
+ integrations,
  transport: options.transport || makeFetchTransport,
  };
 

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

@@ -37,24 +37,9 @@ describe('spanStreamingIntegration', () => {
  const integration = spanStreamingIntegration();
  expect(integration.name).toBe('SpanStreaming');
  // eslint-disable-next-line @typescript-eslint/unbound-method
- expect(integration.beforeSetup).toBeDefined();
- // eslint-disable-next-line @typescript-eslint/unbound-method
  expect(integration.setup).toBeDefined();
  });
 
- it('sets traceLifecycle to "stream" if not set', () => {
- const client = new BrowserClient({
- ...getDefaultBrowserClientOptions(),
- dsn: 'https://username@domain/123',
- integrations: [spanStreamingIntegration()],
- });
-
- SentryCore.setCurrentClient(client);
- client.init();
-
- expect(client.getOptions().traceLifecycle).toBe('stream');
- });
-
  it.each(['static', 'somethingElse'])(
  'logs a warning if traceLifecycle is not set to "stream" but to %s',
  traceLifecycle => {

packages/browser/test/sdk.test.ts

@@ -61,6 +61,32 @@ describe('init', () => {
  expect(optionsPassed?.integrations.length).toBeGreaterThan(0);
  });
 
+ it('installs spanStreamingIntegration by default', () => {
+ // @ts-expect-error this is fine for testing
+ const initAndBindSpy = vi.spyOn(SentryCore, 'initAndBind').mockImplementationOnce(() => {});
+ const options = getDefaultBrowserOptions({ dsn: PUBLIC_DSN, defaultIntegrations: undefined });
+
+ init(options);
+
+ const optionsPassed = initAndBindSpy.mock.calls[0]?.[1];
+ expect(optionsPassed?.integrations.some(integration => integration.name === 'SpanStreaming')).toBe(true);
+ });
+
+ it('does not install spanStreamingIntegration when traceLifecycle is static', () => {
+ // @ts-expect-error this is fine for testing
+ const initAndBindSpy = vi.spyOn(SentryCore, 'initAndBind').mockImplementationOnce(() => {});
+ const options = getDefaultBrowserOptions({
+ dsn: PUBLIC_DSN,
+ defaultIntegrations: undefined,
+ traceLifecycle: 'static',
+ });
+
+ init(options);
+
+ const optionsPassed = initAndBindSpy.mock.calls[0]?.[1];
+ expect(optionsPassed?.integrations.some(integration => integration.name === 'SpanStreaming')).toBe(false);
+ });
+
  test("doesn't install default integrations if told not to", () => {
  const DEFAULT_INTEGRATIONS: Integration[] = [
  new MockIntegration('MockIntegration 0.3'),
@@ -73,6 +99,17 @@ describe('init', () => {
  expect(DEFAULT_INTEGRATIONS[1]!.setupOnce as Mock).toHaveBeenCalledTimes(0);
  });
 
+ it('installs spanStreamingIntegration with defaultIntegrations disabled', () => {
+ // @ts-expect-error this is fine for testing
+ const initAndBindSpy = vi.spyOn(SentryCore, 'initAndBind').mockImplementationOnce(() => {});
+ const options = getDefaultBrowserOptions({ dsn: PUBLIC_DSN, defaultIntegrations: false });
+
+ init(options);
+
+ const optionsPassed = initAndBindSpy.mock.calls[0]?.[1];
+ expect(optionsPassed?.integrations.some(integration => integration.name === 'SpanStreaming')).toBe(true);
+ });
+
  it('installs merged default integrations, with overrides provided through options', () => {
  const DEFAULT_INTEGRATIONS = [
  new MockIntegration('MockIntegration 1.1'),

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

@@ -27,6 +27,7 @@ export function createSentryInstance(
  dsn: 'https://4c2bae7d9fbc413e8f7385f55c515d51@o1.ingest.sentry.io/6690737',
 
  tracesSampleRate: 1,
+ traceLifecycle: 'static',
  sampleRate: 1,
 
  release: LIB_VERSION,

packages/cloudflare/src/options.ts

@@ -70,6 +70,7 @@ export function getFinalOptions(userOptions: CloudflareOptions = {}, env: unknow
  tracesSampleRate: isFinite(tracesSampleRate) ? tracesSampleRate : undefined,
  debug: userOptions.debug ?? envToBool(getEnvVar(env, 'SENTRY_DEBUG')),
  tunnel: userOptions.tunnel ?? getEnvVar(env, 'SENTRY_TUNNEL'),
+ traceLifecycle: userOptions.traceLifecycle ?? getTraceLifecycleFromEnv(getEnvVar(env, 'SENTRY_TRACE_LIFECYCLE')),
  /*! rollup-include-development-only */
  spotlight,
  /*! rollup-include-development-only-end */
@@ -102,3 +103,7 @@ function getSpotlightFromEnv(
  ? (envUrl ?? true) // true: use env URL if present, otherwise true
  : (envBool ?? envUrl); // undefined: use env var (bool or URL)
 }
+
+function getTraceLifecycleFromEnv(envVar: string | undefined): 'static' | 'stream' | undefined {
+ return envVar === 'stream' || envVar === 'static' ? envVar : undefined;
+}

packages/cloudflare/test/sdk.test.ts

@@ -22,10 +22,9 @@ describe('init', () => {
  expect(client).toBeInstanceOf(CloudflareClient);
  });
 
- test('installs SpanStreaming integration when traceLifecycle is "stream"', () => {
+ test('installs SpanStreaming integration by default', () => {
  init({
  dsn: 'https://public@dsn.ingest.sentry.io/1337',
- traceLifecycle: 'stream',
  });
  const client = getClient();
 
@@ -36,8 +35,8 @@ describe('init', () => {
  );
  });
 
- test("does not install SpanStreaming integration when traceLifecycle is not 'stream'", () => {
- init({ dsn: 'https://public@dsn.ingest.sentry.io/1337' });
+ test("does not install SpanStreaming integration when traceLifecycle is 'static'", () => {
+ init({ dsn: 'https://public@dsn.ingest.sentry.io/1337', traceLifecycle: 'static' });
  const client = getClient();
 
  expect(client?.getOptions()).toEqual(

packages/core/src/client.ts

@@ -234,7 +234,7 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
  * @param options Options for the client.
  */
  protected constructor(options: O) {
- this._options = { attachStacktrace: true, ...options };
+ this._options = { attachStacktrace: true, traceLifecycle: 'stream', ...options };
  this._integrations = {};
  this._numProcessing = 0;
  this._outcomes = {};

packages/core/src/server-runtime-client.ts

@@ -40,6 +40,8 @@ export class ServerRuntimeClient<
  public constructor(options: O) {
  addUserAgentToTransportHeaders(options);
 
+ options.traceLifecycle ??= 'stream';
+
  // When span streaming is enabled (`traceLifecycle: 'stream'`), the `spanStreamingIntegration`
  // is required to flush spans. We add it here so the individual server SDKs don't have to.
  // A user-provided `spanStreamingIntegration` always takes precedence over the one we add.

packages/core/src/types/options.ts

@@ -543,7 +543,7 @@ export interface ClientOptions<TO extends BaseTransportOptions = BaseTransportOp
  * The trace lifecycle, determining whether spans are sent statically when the entire local span tree is complete,
  * or streamed in batches, following interval- and action-based triggers.
  *
- * @default 'static'
+ * @default 'stream'
  */
  traceLifecycle?: 'static' | 'stream';
 

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

@@ -103,7 +103,21 @@ describe('Client', () => {
  const options = getDefaultTestClientOptions({ dsn: PUBLIC_DSN, test: true });
  const client = new TestClient(options);
 
- expect(client.getOptions()).toEqual({ attachStacktrace: true, ...options });
+ expect(client.getOptions()).toEqual({ attachStacktrace: true, traceLifecycle: 'stream', ...options });
+ });
+
+ test('defaults traceLifecycle to stream', () => {
+ const options = getDefaultTestClientOptions();
+ delete options.traceLifecycle;
+ const client = new TestClient(options);
+
+ expect(client.getOptions().traceLifecycle).toBe('stream');
+ });
+
+ test('preserves an explicit static traceLifecycle', () => {
+ const client = new TestClient(getDefaultTestClientOptions({ traceLifecycle: 'static' }));
+
+ expect(client.getOptions().traceLifecycle).toBe('static');
  });
  });
 

packages/deno/test/sdk.test.ts

@@ -8,17 +8,17 @@ Deno.test('init() should return client', () => {
  assertNotEquals(init({}), undefined);
 });
 
-Deno.test('adds spanStreamingIntegration when traceLifecycle is "stream"', () => {
- const client = init({ traceLifecycle: 'stream' });
+Deno.test('adds spanStreamingIntegration by default', () => {
+ const client = init({});
  const integrations = client.getOptions().integrations;
  assertArrayIncludes(
  integrations.map(i => i.name),
  ['SpanStreaming'],
  );
 });
 
-Deno.test('doesn\'t add spanStreamingIntegration when traceLifecycle is not "stream"', () => {
- const client = init({});
+Deno.test('doesn\'t add spanStreamingIntegration when traceLifecycle is "static"', () => {
+ const client = init({ traceLifecycle: 'static' });
  const integrations = client.getOptions().integrations;
  assert(!integrations.some(i => i.name === 'SpanStreaming'));
 });

packages/node/src/sdk/index.ts

@@ -300,6 +300,7 @@ function getClientOptions(
  const spotlight = getSpotlightConfig(options.spotlight);
 
  const tracesSampleRate = getTracesSampleRate(options.tracesSampleRate);
+ const traceLifecycle = getTraceLifecycle(options.traceLifecycle);
 
  const mergedOptions = {
  ...options,
@@ -311,6 +312,7 @@ function getClientOptions(
  release,
  tracesSampleRate,
  spotlight,
+ traceLifecycle,
  debug: envToBool(options.debug ?? process.env.SENTRY_DEBUG),
  };
 
@@ -355,6 +357,20 @@ function getTracesSampleRate(tracesSampleRate: NodeOptions['tracesSampleRate']):
  return isFinite(parsed) ? parsed : undefined;
 }
 
+function getTraceLifecycle(traceLifecycle: NodeOptions['traceLifecycle']): 'stream' | 'static' {
+ if (traceLifecycle !== undefined) {
+ return traceLifecycle;
+ }
+
+ const lifecycleFromEnv = process.env.SENTRY_TRACE_LIFECYCLE;
+
+ if (lifecycleFromEnv === 'stream' || lifecycleFromEnv === 'static') {
+ return lifecycleFromEnv;
+ }
+
+ return 'stream';
+}
+
 /**
  * Update scope and propagation context based on environmental variables.
  *

packages/node/test/sdk/init.test.ts

@@ -59,16 +59,12 @@ describe('init()', () => {
  });
 
  describe('integrations', () => {
- it("doesn't install default integrations if told not to", () => {
+ it('only installs the required spanStreaming integration if default integrations are disabled', () => {
  init({ dsn: PUBLIC_DSN, defaultIntegrations: false });
 
  const client = getClient();
 
- expect(client?.getOptions()).toEqual(
- expect.objectContaining({
- integrations: [],
- }),
- );
+ expect(client?.getOptions().integrations.map(integration => integration.name)).toEqual(['SpanStreaming']);
 
  expect(mockAutoPerformanceIntegrations).toHaveBeenCalledTimes(0);
  });
@@ -169,8 +165,8 @@ describe('init()', () => {
  );
  });
 
- it('installs spanStreaming integration when traceLifecycle is "stream"', () => {
- init({ dsn: PUBLIC_DSN, traceLifecycle: 'stream' });
+ it('installs spanStreaming integration by default', () => {
+ init({ dsn: PUBLIC_DSN });
  const client = getClient();
 
  expect(client?.getOptions()).toEqual(
@@ -180,8 +176,8 @@ describe('init()', () => {
  );
  });
 
- it("doesn't install spanStreaming integration when traceLifecycle is not 'stream'", () => {
- init({ dsn: PUBLIC_DSN });
+ it("doesn't install spanStreaming integration when traceLifecycle is 'static'", () => {
+ init({ dsn: PUBLIC_DSN, traceLifecycle: 'static' });
 
  const client = getClient();
  expect(client?.getOptions()).toEqual(
@@ -192,7 +188,7 @@ describe('init()', () => {
  });
 
  it('installs spanStreaming integration even with custom defaultIntegrations', () => {
- init({ dsn: PUBLIC_DSN, traceLifecycle: 'stream', defaultIntegrations: [] });
+ init({ dsn: PUBLIC_DSN, defaultIntegrations: [] });
  const client = getClient();
 
  expect(client?.getOptions()).toEqual(

dev-packages/browser-integration-tests/loader-suites/loader/noOnLoad/pageloadTransaction/test.ts

@@ -1,27 +1,21 @@
 import { expect } from '@playwright/test';
 import { sentryTest } from '../../../../utils/fixtures';
-import {
- envelopeRequestParser,
- shouldSkipTracingTest,
- waitForTransactionRequestOnUrl,
-} from '../../../../utils/helpers';
+import { shouldSkipTracingTest } from '../../../../utils/helpers';
+import { getSpanOp, waitForStreamedSpan } from '../../../../utils/spanUtils';
 
-sentryTest('should create a pageload transaction', async ({ getLocalTestUrl, page }) => {
+sentryTest('should create a pageload span', async ({ getLocalTestUrl, page }) => {
  if (shouldSkipTracingTest()) {
  sentryTest.skip();
  }
 
+ const spanPromise = waitForStreamedSpan(page, s => getSpanOp(s) === 'pageload');
  const url = await getLocalTestUrl({ testDir: __dirname });
- const req = await waitForTransactionRequestOnUrl(page, url);
+ await page.goto(url);
+ const pageloadSpan = await spanPromise;
 
- const eventData = envelopeRequestParser(req);
  const timeOrigin = await page.evaluate<number>('window._testBaseTimestamp');
 
-const { start_timestamp: startTimestamp } = eventData;
+expect(pageloadSpan.start_timestamp).toBeCloseTo(timeOrigin, 1);
 
- expect(startTimestamp).toBeCloseTo(timeOrigin, 1);
-
- expect(eventData.contexts?.trace?.op).toBe('pageload');
- expect(eventData.spans?.length).toBeGreaterThan(0);
- expect(eventData.transaction_info?.source).toEqual('url');
+ expect(pageloadSpan.attributes?.['sentry.segment.name.source'].value).toEqual('url');
 });

dev-packages/e2e-tests/test-applications/astro-5-cf-workers/wrangler.jsonc

@@ -9,6 +9,7 @@
  "SENTRY_ENVIRONMENT": "qa",
  "SENTRY_TRACES_SAMPLE_RATE": "1.0",
  "SENTRY_TUNNEL": "http://localhost:3031/",
+ "SENTRY_TRACE_LIFECYCLE": "static",
  },
  "assets": {
  "binding": "ASSETS",

dev-packages/e2e-tests/test-applications/aws-serverless-layer/src/stack.ts

@@ -77,6 +77,7 @@ export class LocalLambdaStack extends Stack {
  Variables: {
  SENTRY_TRACES_SAMPLE_RATE: 1.0,
  SENTRY_DEBUG: true,
+ SENTRY_TRACE_LIFECYCLE: 'static',
  NODE_OPTIONS: `--import=@sentry/aws-serverless/awslambda-auto`,
  // We only set SENTRY_DSN if not running TunnelNoDsn, because there
  // we want to test that the extension tunnel forwards requests when SENTRY_DSN is missing.

dev-packages/e2e-tests/test-applications/aws-serverless/src/stack.ts

@@ -112,6 +112,7 @@ export class LocalLambdaStack extends Stack {
  SENTRY_DSN: dsn,
  SENTRY_TRACES_SAMPLE_RATE: 1.0,
  SENTRY_DEBUG: true,
+ SENTRY_TRACE_LIFECYCLE: 'static',
  NODE_OPTIONS: `--import=@sentry/aws-serverless/awslambda-auto`,
  },
  },

packages/browser/src/integrations/spanstreaming.ts

@@ -14,16 +14,6 @@ export const spanStreamingIntegration = defineIntegration(() => {
  return {
  name: 'SpanStreaming' as const,
 
- beforeSetup(client) {
- // If users only set spanStreamingIntegration, without traceLifecycle, we set it to "stream" for them.
- // This avoids the classic double-opt-in problem we'd otherwise have in the browser SDK.
- const clientOptions = client.getOptions();
- if (!clientOptions.traceLifecycle) {
- DEBUG_BUILD && debug.log('[SpanStreaming] setting `traceLifecycle` to "stream"');
- clientOptions.traceLifecycle = 'stream';
- }
- },
-
  setup(client) {
  const initialMessage = 'SpanStreaming integration requires';
  const fallbackMsg = 'Falling back to static trace lifecycle.';

packages/browser/src/sdk.ts

@@ -19,6 +19,7 @@ import { globalHandlersIntegration } from './integrations/globalhandlers';
 import { httpContextIntegration } from './integrations/httpcontext';
 import { linkedErrorsIntegration } from './integrations/linkederrors';
 import { spotlightBrowserIntegration } from './integrations/spotlight';
+import { spanStreamingIntegration } from './integrations/spanstreaming';
 import { defaultStackParser } from './stack-parsers';
 import { makeFetchTransport } from './transports/fetch';
 import { normalizeStringifyValue } from './normalizeStringifyValue';
@@ -110,14 +111,22 @@ export function init(options: BrowserOptions = {}): Client | undefined {
  }
  /*! rollup-include-development-only-end */
 
+ const integrations = getIntegrationsToSetup({
+ integrations: options.integrations,
+ defaultIntegrations,
+ });
+
+ options.traceLifecycle ??= 'stream';
+
+ if (options.traceLifecycle === 'stream' && !integrations.some(integration => integration.name === 'SpanStreaming')) {
+ integrations.push(spanStreamingIntegration());
+ }
+
  const clientOptions: BrowserClientOptions = {
  ...options,
  enabled: shouldDisableBecauseIsBrowserExtenstion ? false : options.enabled,
  stackParser: stackParserFromStackParserOptions(options.stackParser || defaultStackParser),
- integrations: getIntegrationsToSetup({
- integrations: options.integrations,
- defaultIntegrations,
- }),
+ integrations,
  transport: options.transport || makeFetchTransport,
  };
 

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

@@ -37,24 +37,9 @@ describe('spanStreamingIntegration', () => {
  const integration = spanStreamingIntegration();
  expect(integration.name).toBe('SpanStreaming');
  // eslint-disable-next-line @typescript-eslint/unbound-method
- expect(integration.beforeSetup).toBeDefined();
- // eslint-disable-next-line @typescript-eslint/unbound-method
  expect(integration.setup).toBeDefined();
  });
 
- it('sets traceLifecycle to "stream" if not set', () => {
- const client = new BrowserClient({
- ...getDefaultBrowserClientOptions(),
- dsn: 'https://username@domain/123',
- integrations: [spanStreamingIntegration()],
- });
-
- SentryCore.setCurrentClient(client);
- client.init();
-
- expect(client.getOptions().traceLifecycle).toBe('stream');
- });
-
  it.each(['static', 'somethingElse'])(
  'logs a warning if traceLifecycle is not set to "stream" but to %s',
  traceLifecycle => {

packages/browser/test/sdk.test.ts

@@ -61,6 +61,32 @@ describe('init', () => {
  expect(optionsPassed?.integrations.length).toBeGreaterThan(0);
  });
 
+ it('installs spanStreamingIntegration by default', () => {
+ // @ts-expect-error this is fine for testing
+ const initAndBindSpy = vi.spyOn(SentryCore, 'initAndBind').mockImplementationOnce(() => {});
+ const options = getDefaultBrowserOptions({ dsn: PUBLIC_DSN, defaultIntegrations: undefined });
+
+ init(options);
+
+ const optionsPassed = initAndBindSpy.mock.calls[0]?.[1];
+ expect(optionsPassed?.integrations.some(integration => integration.name === 'SpanStreaming')).toBe(true);
+ });
+
+ it('does not install spanStreamingIntegration when traceLifecycle is static', () => {
+ // @ts-expect-error this is fine for testing
+ const initAndBindSpy = vi.spyOn(SentryCore, 'initAndBind').mockImplementationOnce(() => {});
+ const options = getDefaultBrowserOptions({
+ dsn: PUBLIC_DSN,
+ defaultIntegrations: undefined,
+ traceLifecycle: 'static',
+ });
+
+ init(options);
+
+ const optionsPassed = initAndBindSpy.mock.calls[0]?.[1];
+ expect(optionsPassed?.integrations.some(integration => integration.name === 'SpanStreaming')).toBe(false);
+ });
+
  test("doesn't install default integrations if told not to", () => {
  const DEFAULT_INTEGRATIONS: Integration[] = [
  new MockIntegration('MockIntegration 0.3'),
@@ -73,6 +99,17 @@ describe('init', () => {
  expect(DEFAULT_INTEGRATIONS[1]!.setupOnce as Mock).toHaveBeenCalledTimes(0);
  });
 
+ it('installs spanStreamingIntegration with defaultIntegrations disabled', () => {
+ // @ts-expect-error this is fine for testing
+ const initAndBindSpy = vi.spyOn(SentryCore, 'initAndBind').mockImplementationOnce(() => {});
+ const options = getDefaultBrowserOptions({ dsn: PUBLIC_DSN, defaultIntegrations: false });
+
+ init(options);
+
+ const optionsPassed = initAndBindSpy.mock.calls[0]?.[1];
+ expect(optionsPassed?.integrations.some(integration => integration.name === 'SpanStreaming')).toBe(true);
+ });
+
  it('installs merged default integrations, with overrides provided through options', () => {
  const DEFAULT_INTEGRATIONS = [
  new MockIntegration('MockIntegration 1.1'),

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

@@ -27,6 +27,7 @@ export function createSentryInstance(
  dsn: 'https://4c2bae7d9fbc413e8f7385f55c515d51@o1.ingest.sentry.io/6690737',
 
  tracesSampleRate: 1,
+ traceLifecycle: 'static',
  sampleRate: 1,
 
  release: LIB_VERSION,

packages/cloudflare/src/options.ts

@@ -70,6 +70,7 @@ export function getFinalOptions(userOptions: CloudflareOptions = {}, env: unknow
  tracesSampleRate: isFinite(tracesSampleRate) ? tracesSampleRate : undefined,
  debug: userOptions.debug ?? envToBool(getEnvVar(env, 'SENTRY_DEBUG')),
  tunnel: userOptions.tunnel ?? getEnvVar(env, 'SENTRY_TUNNEL'),
+ traceLifecycle: userOptions.traceLifecycle ?? getTraceLifecycleFromEnv(getEnvVar(env, 'SENTRY_TRACE_LIFECYCLE')),
  /*! rollup-include-development-only */
  spotlight,
  /*! rollup-include-development-only-end */
@@ -102,3 +103,7 @@ function getSpotlightFromEnv(
  ? (envUrl ?? true) // true: use env URL if present, otherwise true
  : (envBool ?? envUrl); // undefined: use env var (bool or URL)
 }
+
+function getTraceLifecycleFromEnv(envVar: string | undefined): 'static' | 'stream' | undefined {
+ return envVar === 'stream' || envVar === 'static' ? envVar : undefined;
+}

packages/cloudflare/test/sdk.test.ts

@@ -22,10 +22,9 @@ describe('init', () => {
  expect(client).toBeInstanceOf(CloudflareClient);
  });
 
- test('installs SpanStreaming integration when traceLifecycle is "stream"', () => {
+ test('installs SpanStreaming integration by default', () => {
  init({
  dsn: 'https://public@dsn.ingest.sentry.io/1337',
- traceLifecycle: 'stream',
  });
  const client = getClient();
 
@@ -36,8 +35,8 @@ describe('init', () => {
  );
  });
 
- test("does not install SpanStreaming integration when traceLifecycle is not 'stream'", () => {
- init({ dsn: 'https://public@dsn.ingest.sentry.io/1337' });
+ test("does not install SpanStreaming integration when traceLifecycle is 'static'", () => {
+ init({ dsn: 'https://public@dsn.ingest.sentry.io/1337', traceLifecycle: 'static' });
  const client = getClient();
 
  expect(client?.getOptions()).toEqual(

packages/core/src/client.ts

@@ -234,7 +234,7 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
  * @param options Options for the client.
  */
  protected constructor(options: O) {
- this._options = { attachStacktrace: true, ...options };
+ this._options = { attachStacktrace: true, traceLifecycle: 'stream', ...options };
  this._integrations = {};
  this._numProcessing = 0;
  this._outcomes = {};

packages/core/src/server-runtime-client.ts

@@ -40,6 +40,8 @@ export class ServerRuntimeClient<
  public constructor(options: O) {
  addUserAgentToTransportHeaders(options);
 
+ options.traceLifecycle ??= 'stream';
+
  // When span streaming is enabled (`traceLifecycle: 'stream'`), the `spanStreamingIntegration`
  // is required to flush spans. We add it here so the individual server SDKs don't have to.
  // A user-provided `spanStreamingIntegration` always takes precedence over the one we add.

packages/core/src/types/options.ts

@@ -543,7 +543,7 @@ export interface ClientOptions<TO extends BaseTransportOptions = BaseTransportOp
  * The trace lifecycle, determining whether spans are sent statically when the entire local span tree is complete,
  * or streamed in batches, following interval- and action-based triggers.
  *
- * @default 'static'
+ * @default 'stream'
  */
  traceLifecycle?: 'static' | 'stream';
 

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

@@ -103,7 +103,21 @@ describe('Client', () => {
  const options = getDefaultTestClientOptions({ dsn: PUBLIC_DSN, test: true });
  const client = new TestClient(options);
 
- expect(client.getOptions()).toEqual({ attachStacktrace: true, ...options });
+ expect(client.getOptions()).toEqual({ attachStacktrace: true, traceLifecycle: 'stream', ...options });
+ });
+
+ test('defaults traceLifecycle to stream', () => {
+ const options = getDefaultTestClientOptions();
+ delete options.traceLifecycle;
+ const client = new TestClient(options);
+
+ expect(client.getOptions().traceLifecycle).toBe('stream');
+ });
+
+ test('preserves an explicit static traceLifecycle', () => {
+ const client = new TestClient(getDefaultTestClientOptions({ traceLifecycle: 'static' }));
+
+ expect(client.getOptions().traceLifecycle).toBe('static');
  });
  });
 

packages/deno/test/sdk.test.ts

@@ -8,17 +8,17 @@ Deno.test('init() should return client', () => {
  assertNotEquals(init({}), undefined);
 });
 
-Deno.test('adds spanStreamingIntegration when traceLifecycle is "stream"', () => {
- const client = init({ traceLifecycle: 'stream' });
+Deno.test('adds spanStreamingIntegration by default', () => {
+ const client = init({});
  const integrations = client.getOptions().integrations;
  assertArrayIncludes(
  integrations.map(i => i.name),
  ['SpanStreaming'],
  );
 });
 
-Deno.test('doesn\'t add spanStreamingIntegration when traceLifecycle is not "stream"', () => {
- const client = init({});
+Deno.test('doesn\'t add spanStreamingIntegration when traceLifecycle is "static"', () => {
+ const client = init({ traceLifecycle: 'static' });
  const integrations = client.getOptions().integrations;
  assert(!integrations.some(i => i.name === 'SpanStreaming'));
 });

packages/node/src/sdk/index.ts

@@ -300,6 +300,7 @@ function getClientOptions(
  const spotlight = getSpotlightConfig(options.spotlight);
 
  const tracesSampleRate = getTracesSampleRate(options.tracesSampleRate);
+ const traceLifecycle = getTraceLifecycle(options.traceLifecycle);
 
  const mergedOptions = {
  ...options,
@@ -311,6 +312,7 @@ function getClientOptions(
  release,
  tracesSampleRate,
  spotlight,
+ traceLifecycle,
  debug: envToBool(options.debug ?? process.env.SENTRY_DEBUG),
  };
 
@@ -355,6 +357,20 @@ function getTracesSampleRate(tracesSampleRate: NodeOptions['tracesSampleRate']):
  return isFinite(parsed) ? parsed : undefined;
 }
 
+function getTraceLifecycle(traceLifecycle: NodeOptions['traceLifecycle']): 'stream' | 'static' {
+ if (traceLifecycle !== undefined) {
+ return traceLifecycle;
+ }
+
+ const lifecycleFromEnv = process.env.SENTRY_TRACE_LIFECYCLE;
+
+ if (lifecycleFromEnv === 'stream' || lifecycleFromEnv === 'static') {
+ return lifecycleFromEnv;
+ }
+
+ return 'stream';
+}
+
 /**
  * Update scope and propagation context based on environmental variables.
  *

packages/node/test/sdk/init.test.ts

@@ -59,16 +59,12 @@ describe('init()', () => {
  });
 
  describe('integrations', () => {
- it("doesn't install default integrations if told not to", () => {
+ it('only installs the required spanStreaming integration if default integrations are disabled', () => {
  init({ dsn: PUBLIC_DSN, defaultIntegrations: false });
 
  const client = getClient();
 
- expect(client?.getOptions()).toEqual(
- expect.objectContaining({
- integrations: [],
- }),
- );
+ expect(client?.getOptions().integrations.map(integration => integration.name)).toEqual(['SpanStreaming']);
 
  expect(mockAutoPerformanceIntegrations).toHaveBeenCalledTimes(0);
  });
@@ -169,8 +165,8 @@ describe('init()', () => {
  );
  });
 
- it('installs spanStreaming integration when traceLifecycle is "stream"', () => {
- init({ dsn: PUBLIC_DSN, traceLifecycle: 'stream' });
+ it('installs spanStreaming integration by default', () => {
+ init({ dsn: PUBLIC_DSN });
  const client = getClient();
 
  expect(client?.getOptions()).toEqual(
@@ -180,8 +176,8 @@ describe('init()', () => {
  );
  });
 
- it("doesn't install spanStreaming integration when traceLifecycle is not 'stream'", () => {
- init({ dsn: PUBLIC_DSN });
+ it("doesn't install spanStreaming integration when traceLifecycle is 'static'", () => {
+ init({ dsn: PUBLIC_DSN, traceLifecycle: 'static' });
 
  const client = getClient();
  expect(client?.getOptions()).toEqual(
@@ -192,7 +188,7 @@ describe('init()', () => {
  });
 
  it('installs spanStreaming integration even with custom defaultIntegrations', () => {
- init({ dsn: PUBLIC_DSN, traceLifecycle: 'stream', defaultIntegrations: [] });
+ init({ dsn: PUBLIC_DSN, defaultIntegrations: [] });
  const client = getClient();
 
  expect(client?.getOptions()).toEqual(

dev-packages/browser-integration-tests/loader-suites/loader/noOnLoad/pageloadTransaction/test.ts

@@ -1,27 +1,21 @@
 import { expect } from '@playwright/test';
 import { sentryTest } from '../../../../utils/fixtures';
-import {
- envelopeRequestParser,
- shouldSkipTracingTest,
- waitForTransactionRequestOnUrl,
-} from '../../../../utils/helpers';
+import { shouldSkipTracingTest } from '../../../../utils/helpers';
+import { getSpanOp, waitForStreamedSpan } from '../../../../utils/spanUtils';
 
-sentryTest('should create a pageload transaction', async ({ getLocalTestUrl, page }) => {
+sentryTest('should create a pageload span', async ({ getLocalTestUrl, page }) => {
  if (shouldSkipTracingTest()) {
  sentryTest.skip();
  }
 
+ const spanPromise = waitForStreamedSpan(page, s => getSpanOp(s) === 'pageload');
  const url = await getLocalTestUrl({ testDir: __dirname });
- const req = await waitForTransactionRequestOnUrl(page, url);
+ await page.goto(url);
+ const pageloadSpan = await spanPromise;
 
- const eventData = envelopeRequestParser(req);
  const timeOrigin = await page.evaluate<number>('window._testBaseTimestamp');
 
-const { start_timestamp: startTimestamp } = eventData;
+expect(pageloadSpan.start_timestamp).toBeCloseTo(timeOrigin, 1);
 
- expect(startTimestamp).toBeCloseTo(timeOrigin, 1);
-
- expect(eventData.contexts?.trace?.op).toBe('pageload');
- expect(eventData.spans?.length).toBeGreaterThan(0);
- expect(eventData.transaction_info?.source).toEqual('url');
+ expect(pageloadSpan.attributes?.['sentry.segment.name.source'].value).toEqual('url');
 });

dev-packages/e2e-tests/test-applications/astro-5-cf-workers/wrangler.jsonc

@@ -9,6 +9,7 @@
  "SENTRY_ENVIRONMENT": "qa",
  "SENTRY_TRACES_SAMPLE_RATE": "1.0",
  "SENTRY_TUNNEL": "http://localhost:3031/",
+ "SENTRY_TRACE_LIFECYCLE": "static",
  },
  "assets": {
  "binding": "ASSETS",

dev-packages/e2e-tests/test-applications/aws-serverless-layer/src/stack.ts

@@ -77,6 +77,7 @@ export class LocalLambdaStack extends Stack {
  Variables: {
  SENTRY_TRACES_SAMPLE_RATE: 1.0,
  SENTRY_DEBUG: true,
+ SENTRY_TRACE_LIFECYCLE: 'static',
  NODE_OPTIONS: `--import=@sentry/aws-serverless/awslambda-auto`,
  // We only set SENTRY_DSN if not running TunnelNoDsn, because there
  // we want to test that the extension tunnel forwards requests when SENTRY_DSN is missing.

dev-packages/e2e-tests/test-applications/aws-serverless/src/stack.ts

@@ -112,6 +112,7 @@ export class LocalLambdaStack extends Stack {
  SENTRY_DSN: dsn,
  SENTRY_TRACES_SAMPLE_RATE: 1.0,
  SENTRY_DEBUG: true,
+ SENTRY_TRACE_LIFECYCLE: 'static',
  NODE_OPTIONS: `--import=@sentry/aws-serverless/awslambda-auto`,
  },
  },

packages/browser/src/integrations/spanstreaming.ts

@@ -14,16 +14,6 @@ export const spanStreamingIntegration = defineIntegration(() => {
  return {
  name: 'SpanStreaming' as const,
 
- beforeSetup(client) {
- // If users only set spanStreamingIntegration, without traceLifecycle, we set it to "stream" for them.
- // This avoids the classic double-opt-in problem we'd otherwise have in the browser SDK.
- const clientOptions = client.getOptions();
- if (!clientOptions.traceLifecycle) {
- DEBUG_BUILD && debug.log('[SpanStreaming] setting `traceLifecycle` to "stream"');
- clientOptions.traceLifecycle = 'stream';
- }
- },
-
  setup(client) {
  const initialMessage = 'SpanStreaming integration requires';
  const fallbackMsg = 'Falling back to static trace lifecycle.';

packages/browser/src/sdk.ts

@@ -19,6 +19,7 @@ import { globalHandlersIntegration } from './integrations/globalhandlers';
 import { httpContextIntegration } from './integrations/httpcontext';
 import { linkedErrorsIntegration } from './integrations/linkederrors';
 import { spotlightBrowserIntegration } from './integrations/spotlight';
+import { spanStreamingIntegration } from './integrations/spanstreaming';
 import { defaultStackParser } from './stack-parsers';
 import { makeFetchTransport } from './transports/fetch';
 import { normalizeStringifyValue } from './normalizeStringifyValue';
@@ -110,14 +111,22 @@ export function init(options: BrowserOptions = {}): Client | undefined {
  }
  /*! rollup-include-development-only-end */
 
+ const integrations = getIntegrationsToSetup({
+ integrations: options.integrations,
+ defaultIntegrations,
+ });
+
+ options.traceLifecycle ??= 'stream';
+
+ if (options.traceLifecycle === 'stream' && !integrations.some(integration => integration.name === 'SpanStreaming')) {
+ integrations.push(spanStreamingIntegration());
+ }
+
  const clientOptions: BrowserClientOptions = {
  ...options,
  enabled: shouldDisableBecauseIsBrowserExtenstion ? false : options.enabled,
  stackParser: stackParserFromStackParserOptions(options.stackParser || defaultStackParser),
- integrations: getIntegrationsToSetup({
- integrations: options.integrations,
- defaultIntegrations,
- }),
+ integrations,
  transport: options.transport || makeFetchTransport,
  };
 

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

@@ -37,24 +37,9 @@ describe('spanStreamingIntegration', () => {
  const integration = spanStreamingIntegration();
  expect(integration.name).toBe('SpanStreaming');
  // eslint-disable-next-line @typescript-eslint/unbound-method
- expect(integration.beforeSetup).toBeDefined();
- // eslint-disable-next-line @typescript-eslint/unbound-method
  expect(integration.setup).toBeDefined();
  });
 
- it('sets traceLifecycle to "stream" if not set', () => {
- const client = new BrowserClient({
- ...getDefaultBrowserClientOptions(),
- dsn: 'https://username@domain/123',
- integrations: [spanStreamingIntegration()],
- });
-
- SentryCore.setCurrentClient(client);
- client.init();
-
- expect(client.getOptions().traceLifecycle).toBe('stream');
- });
-
  it.each(['static', 'somethingElse'])(
  'logs a warning if traceLifecycle is not set to "stream" but to %s',
  traceLifecycle => {

packages/browser/test/sdk.test.ts

@@ -61,6 +61,32 @@ describe('init', () => {
  expect(optionsPassed?.integrations.length).toBeGreaterThan(0);
  });
 
+ it('installs spanStreamingIntegration by default', () => {
+ // @ts-expect-error this is fine for testing
+ const initAndBindSpy = vi.spyOn(SentryCore, 'initAndBind').mockImplementationOnce(() => {});
+ const options = getDefaultBrowserOptions({ dsn: PUBLIC_DSN, defaultIntegrations: undefined });
+
+ init(options);
+
+ const optionsPassed = initAndBindSpy.mock.calls[0]?.[1];
+ expect(optionsPassed?.integrations.some(integration => integration.name === 'SpanStreaming')).toBe(true);
+ });
+
+ it('does not install spanStreamingIntegration when traceLifecycle is static', () => {
+ // @ts-expect-error this is fine for testing
+ const initAndBindSpy = vi.spyOn(SentryCore, 'initAndBind').mockImplementationOnce(() => {});
+ const options = getDefaultBrowserOptions({
+ dsn: PUBLIC_DSN,
+ defaultIntegrations: undefined,
+ traceLifecycle: 'static',
+ });
+
+ init(options);
+
+ const optionsPassed = initAndBindSpy.mock.calls[0]?.[1];
+ expect(optionsPassed?.integrations.some(integration => integration.name === 'SpanStreaming')).toBe(false);
+ });
+
  test("doesn't install default integrations if told not to", () => {
  const DEFAULT_INTEGRATIONS: Integration[] = [
  new MockIntegration('MockIntegration 0.3'),
@@ -73,6 +99,17 @@ describe('init', () => {
  expect(DEFAULT_INTEGRATIONS[1]!.setupOnce as Mock).toHaveBeenCalledTimes(0);
  });
 
+ it('installs spanStreamingIntegration with defaultIntegrations disabled', () => {
+ // @ts-expect-error this is fine for testing
+ const initAndBindSpy = vi.spyOn(SentryCore, 'initAndBind').mockImplementationOnce(() => {});
+ const options = getDefaultBrowserOptions({ dsn: PUBLIC_DSN, defaultIntegrations: false });
+
+ init(options);
+
+ const optionsPassed = initAndBindSpy.mock.calls[0]?.[1];
+ expect(optionsPassed?.integrations.some(integration => integration.name === 'SpanStreaming')).toBe(true);
+ });
+
  it('installs merged default integrations, with overrides provided through options', () => {
  const DEFAULT_INTEGRATIONS = [
  new MockIntegration('MockIntegration 1.1'),

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

@@ -27,6 +27,7 @@ export function createSentryInstance(
  dsn: 'https://4c2bae7d9fbc413e8f7385f55c515d51@o1.ingest.sentry.io/6690737',
 
  tracesSampleRate: 1,
+ traceLifecycle: 'static',
  sampleRate: 1,
 
  release: LIB_VERSION,

packages/cloudflare/src/options.ts

@@ -70,6 +70,7 @@ export function getFinalOptions(userOptions: CloudflareOptions = {}, env: unknow
  tracesSampleRate: isFinite(tracesSampleRate) ? tracesSampleRate : undefined,
  debug: userOptions.debug ?? envToBool(getEnvVar(env, 'SENTRY_DEBUG')),
  tunnel: userOptions.tunnel ?? getEnvVar(env, 'SENTRY_TUNNEL'),
+ traceLifecycle: userOptions.traceLifecycle ?? getTraceLifecycleFromEnv(getEnvVar(env, 'SENTRY_TRACE_LIFECYCLE')),
  /*! rollup-include-development-only */
  spotlight,
  /*! rollup-include-development-only-end */
@@ -102,3 +103,7 @@ function getSpotlightFromEnv(
  ? (envUrl ?? true) // true: use env URL if present, otherwise true
  : (envBool ?? envUrl); // undefined: use env var (bool or URL)
 }
+
+function getTraceLifecycleFromEnv(envVar: string | undefined): 'static' | 'stream' | undefined {
+ return envVar === 'stream' || envVar === 'static' ? envVar : undefined;
+}

packages/cloudflare/test/sdk.test.ts

@@ -22,10 +22,9 @@ describe('init', () => {
  expect(client).toBeInstanceOf(CloudflareClient);
  });
 
- test('installs SpanStreaming integration when traceLifecycle is "stream"', () => {
+ test('installs SpanStreaming integration by default', () => {
  init({
  dsn: 'https://public@dsn.ingest.sentry.io/1337',
- traceLifecycle: 'stream',
  });
  const client = getClient();
 
@@ -36,8 +35,8 @@ describe('init', () => {
  );
  });
 
- test("does not install SpanStreaming integration when traceLifecycle is not 'stream'", () => {
- init({ dsn: 'https://public@dsn.ingest.sentry.io/1337' });
+ test("does not install SpanStreaming integration when traceLifecycle is 'static'", () => {
+ init({ dsn: 'https://public@dsn.ingest.sentry.io/1337', traceLifecycle: 'static' });
  const client = getClient();
 
  expect(client?.getOptions()).toEqual(

packages/core/src/client.ts

@@ -234,7 +234,7 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
  * @param options Options for the client.
  */
  protected constructor(options: O) {
- this._options = { attachStacktrace: true, ...options };
+ this._options = { attachStacktrace: true, traceLifecycle: 'stream', ...options };
  this._integrations = {};
  this._numProcessing = 0;
  this._outcomes = {};

packages/core/src/server-runtime-client.ts

@@ -40,6 +40,8 @@ export class ServerRuntimeClient<
  public constructor(options: O) {
  addUserAgentToTransportHeaders(options);
 
+ options.traceLifecycle ??= 'stream';
+
  // When span streaming is enabled (`traceLifecycle: 'stream'`), the `spanStreamingIntegration`
  // is required to flush spans. We add it here so the individual server SDKs don't have to.
  // A user-provided `spanStreamingIntegration` always takes precedence over the one we add.

packages/core/src/types/options.ts

@@ -543,7 +543,7 @@ export interface ClientOptions<TO extends BaseTransportOptions = BaseTransportOp
  * The trace lifecycle, determining whether spans are sent statically when the entire local span tree is complete,
  * or streamed in batches, following interval- and action-based triggers.
  *
- * @default 'static'
+ * @default 'stream'
  */
  traceLifecycle?: 'static' | 'stream';
 

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

@@ -103,7 +103,21 @@ describe('Client', () => {
  const options = getDefaultTestClientOptions({ dsn: PUBLIC_DSN, test: true });
  const client = new TestClient(options);
 
- expect(client.getOptions()).toEqual({ attachStacktrace: true, ...options });
+ expect(client.getOptions()).toEqual({ attachStacktrace: true, traceLifecycle: 'stream', ...options });
+ });
+
+ test('defaults traceLifecycle to stream', () => {
+ const options = getDefaultTestClientOptions();
+ delete options.traceLifecycle;
+ const client = new TestClient(options);
+
+ expect(client.getOptions().traceLifecycle).toBe('stream');
+ });
+
+ test('preserves an explicit static traceLifecycle', () => {
+ const client = new TestClient(getDefaultTestClientOptions({ traceLifecycle: 'static' }));
+
+ expect(client.getOptions().traceLifecycle).toBe('static');
  });
  });
 

packages/deno/test/sdk.test.ts

@@ -8,17 +8,17 @@ Deno.test('init() should return client', () => {
  assertNotEquals(init({}), undefined);
 });
 
-Deno.test('adds spanStreamingIntegration when traceLifecycle is "stream"', () => {
- const client = init({ traceLifecycle: 'stream' });
+Deno.test('adds spanStreamingIntegration by default', () => {
+ const client = init({});
  const integrations = client.getOptions().integrations;
  assertArrayIncludes(
  integrations.map(i => i.name),
  ['SpanStreaming'],
  );
 });
 
-Deno.test('doesn\'t add spanStreamingIntegration when traceLifecycle is not "stream"', () => {
- const client = init({});
+Deno.test('doesn\'t add spanStreamingIntegration when traceLifecycle is "static"', () => {
+ const client = init({ traceLifecycle: 'static' });
  const integrations = client.getOptions().integrations;
  assert(!integrations.some(i => i.name === 'SpanStreaming'));
 });

packages/node/src/sdk/index.ts

@@ -300,6 +300,7 @@ function getClientOptions(
  const spotlight = getSpotlightConfig(options.spotlight);
 
  const tracesSampleRate = getTracesSampleRate(options.tracesSampleRate);
+ const traceLifecycle = getTraceLifecycle(options.traceLifecycle);
 
  const mergedOptions = {
  ...options,
@@ -311,6 +312,7 @@ function getClientOptions(
  release,
  tracesSampleRate,
  spotlight,
+ traceLifecycle,
  debug: envToBool(options.debug ?? process.env.SENTRY_DEBUG),
  };
 
@@ -355,6 +357,20 @@ function getTracesSampleRate(tracesSampleRate: NodeOptions['tracesSampleRate']):
  return isFinite(parsed) ? parsed : undefined;
 }
 
+function getTraceLifecycle(traceLifecycle: NodeOptions['traceLifecycle']): 'stream' | 'static' {
+ if (traceLifecycle !== undefined) {
+ return traceLifecycle;
+ }
+
+ const lifecycleFromEnv = process.env.SENTRY_TRACE_LIFECYCLE;
+
+ if (lifecycleFromEnv === 'stream' || lifecycleFromEnv === 'static') {
+ return lifecycleFromEnv;
+ }
+
+ return 'stream';
+}
+
 /**
  * Update scope and propagation context based on environmental variables.
  *

packages/node/test/sdk/init.test.ts

@@ -59,16 +59,12 @@ describe('init()', () => {
  });
 
  describe('integrations', () => {
- it("doesn't install default integrations if told not to", () => {
+ it('only installs the required spanStreaming integration if default integrations are disabled', () => {
  init({ dsn: PUBLIC_DSN, defaultIntegrations: false });
 
  const client = getClient();
 
- expect(client?.getOptions()).toEqual(
- expect.objectContaining({
- integrations: [],
- }),
- );
+ expect(client?.getOptions().integrations.map(integration => integration.name)).toEqual(['SpanStreaming']);
 
  expect(mockAutoPerformanceIntegrations).toHaveBeenCalledTimes(0);
  });
@@ -169,8 +165,8 @@ describe('init()', () => {
  );
  });
 
- it('installs spanStreaming integration when traceLifecycle is "stream"', () => {
- init({ dsn: PUBLIC_DSN, traceLifecycle: 'stream' });
+ it('installs spanStreaming integration by default', () => {
+ init({ dsn: PUBLIC_DSN });
  const client = getClient();
 
  expect(client?.getOptions()).toEqual(
@@ -180,8 +176,8 @@ describe('init()', () => {
  );
  });
 
- it("doesn't install spanStreaming integration when traceLifecycle is not 'stream'", () => {
- init({ dsn: PUBLIC_DSN });
+ it("doesn't install spanStreaming integration when traceLifecycle is 'static'", () => {
+ init({ dsn: PUBLIC_DSN, traceLifecycle: 'static' });
 
  const client = getClient();
  expect(client?.getOptions()).toEqual(
@@ -192,7 +188,7 @@ describe('init()', () => {
  });
 
  it('installs spanStreaming integration even with custom defaultIntegrations', () => {
- init({ dsn: PUBLIC_DSN, traceLifecycle: 'stream', defaultIntegrations: [] });
+ init({ dsn: PUBLIC_DSN, defaultIntegrations: [] });
  const client = getClient();
 
  expect(client?.getOptions()).toEqual(

dev-packages/browser-integration-tests/loader-suites/loader/noOnLoad/pageloadTransaction/test.ts

@@ -1,27 +1,21 @@
 import { expect } from '@playwright/test';
 import { sentryTest } from '../../../../utils/fixtures';
-import {
- envelopeRequestParser,
- shouldSkipTracingTest,
- waitForTransactionRequestOnUrl,
-} from '../../../../utils/helpers';
+import { shouldSkipTracingTest } from '../../../../utils/helpers';
+import { getSpanOp, waitForStreamedSpan } from '../../../../utils/spanUtils';
 
-sentryTest('should create a pageload transaction', async ({ getLocalTestUrl, page }) => {
+sentryTest('should create a pageload span', async ({ getLocalTestUrl, page }) => {
  if (shouldSkipTracingTest()) {
  sentryTest.skip();
  }
 
+ const spanPromise = waitForStreamedSpan(page, s => getSpanOp(s) === 'pageload');
  const url = await getLocalTestUrl({ testDir: __dirname });
- const req = await waitForTransactionRequestOnUrl(page, url);
+ await page.goto(url);
+ const pageloadSpan = await spanPromise;
 
- const eventData = envelopeRequestParser(req);
  const timeOrigin = await page.evaluate<number>('window._testBaseTimestamp');
 
-const { start_timestamp: startTimestamp } = eventData;
+expect(pageloadSpan.start_timestamp).toBeCloseTo(timeOrigin, 1);
 
- expect(startTimestamp).toBeCloseTo(timeOrigin, 1);
-
- expect(eventData.contexts?.trace?.op).toBe('pageload');
- expect(eventData.spans?.length).toBeGreaterThan(0);
- expect(eventData.transaction_info?.source).toEqual('url');
+ expect(pageloadSpan.attributes?.['sentry.segment.name.source'].value).toEqual('url');
 });

dev-packages/e2e-tests/test-applications/astro-5-cf-workers/wrangler.jsonc

@@ -9,6 +9,7 @@
  "SENTRY_ENVIRONMENT": "qa",
  "SENTRY_TRACES_SAMPLE_RATE": "1.0",
  "SENTRY_TUNNEL": "http://localhost:3031/",
+ "SENTRY_TRACE_LIFECYCLE": "static",
  },
  "assets": {
  "binding": "ASSETS",

dev-packages/e2e-tests/test-applications/aws-serverless-layer/src/stack.ts

@@ -77,6 +77,7 @@ export class LocalLambdaStack extends Stack {
  Variables: {
  SENTRY_TRACES_SAMPLE_RATE: 1.0,
  SENTRY_DEBUG: true,
+ SENTRY_TRACE_LIFECYCLE: 'static',
  NODE_OPTIONS: `--import=@sentry/aws-serverless/awslambda-auto`,
  // We only set SENTRY_DSN if not running TunnelNoDsn, because there
  // we want to test that the extension tunnel forwards requests when SENTRY_DSN is missing.

dev-packages/e2e-tests/test-applications/aws-serverless/src/stack.ts

@@ -112,6 +112,7 @@ export class LocalLambdaStack extends Stack {
  SENTRY_DSN: dsn,
  SENTRY_TRACES_SAMPLE_RATE: 1.0,
  SENTRY_DEBUG: true,
+ SENTRY_TRACE_LIFECYCLE: 'static',
  NODE_OPTIONS: `--import=@sentry/aws-serverless/awslambda-auto`,
  },
  },

packages/browser/src/integrations/spanstreaming.ts

@@ -14,16 +14,6 @@ export const spanStreamingIntegration = defineIntegration(() => {
  return {
  name: 'SpanStreaming' as const,
 
- beforeSetup(client) {
- // If users only set spanStreamingIntegration, without traceLifecycle, we set it to "stream" for them.
- // This avoids the classic double-opt-in problem we'd otherwise have in the browser SDK.
- const clientOptions = client.getOptions();
- if (!clientOptions.traceLifecycle) {
- DEBUG_BUILD && debug.log('[SpanStreaming] setting `traceLifecycle` to "stream"');
- clientOptions.traceLifecycle = 'stream';
- }
- },
-
  setup(client) {
  const initialMessage = 'SpanStreaming integration requires';
  const fallbackMsg = 'Falling back to static trace lifecycle.';

packages/browser/src/sdk.ts

@@ -19,6 +19,7 @@ import { globalHandlersIntegration } from './integrations/globalhandlers';
 import { httpContextIntegration } from './integrations/httpcontext';
 import { linkedErrorsIntegration } from './integrations/linkederrors';
 import { spotlightBrowserIntegration } from './integrations/spotlight';
+import { spanStreamingIntegration } from './integrations/spanstreaming';
 import { defaultStackParser } from './stack-parsers';
 import { makeFetchTransport } from './transports/fetch';
 import { normalizeStringifyValue } from './normalizeStringifyValue';
@@ -110,14 +111,22 @@ export function init(options: BrowserOptions = {}): Client | undefined {
  }
  /*! rollup-include-development-only-end */
 
+ const integrations = getIntegrationsToSetup({
+ integrations: options.integrations,
+ defaultIntegrations,
+ });
+
+ options.traceLifecycle ??= 'stream';
+
+ if (options.traceLifecycle === 'stream' && !integrations.some(integration => integration.name === 'SpanStreaming')) {
+ integrations.push(spanStreamingIntegration());
+ }
+
  const clientOptions: BrowserClientOptions = {
  ...options,
  enabled: shouldDisableBecauseIsBrowserExtenstion ? false : options.enabled,
  stackParser: stackParserFromStackParserOptions(options.stackParser || defaultStackParser),
- integrations: getIntegrationsToSetup({
- integrations: options.integrations,
- defaultIntegrations,
- }),
+ integrations,
  transport: options.transport || makeFetchTransport,
  };
 

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

@@ -37,24 +37,9 @@ describe('spanStreamingIntegration', () => {
  const integration = spanStreamingIntegration();
  expect(integration.name).toBe('SpanStreaming');
  // eslint-disable-next-line @typescript-eslint/unbound-method
- expect(integration.beforeSetup).toBeDefined();
- // eslint-disable-next-line @typescript-eslint/unbound-method
  expect(integration.setup).toBeDefined();
  });
 
- it('sets traceLifecycle to "stream" if not set', () => {
- const client = new BrowserClient({
- ...getDefaultBrowserClientOptions(),
- dsn: 'https://username@domain/123',
- integrations: [spanStreamingIntegration()],
- });
-
- SentryCore.setCurrentClient(client);
- client.init();
-
- expect(client.getOptions().traceLifecycle).toBe('stream');
- });
-
  it.each(['static', 'somethingElse'])(
  'logs a warning if traceLifecycle is not set to "stream" but to %s',
  traceLifecycle => {

packages/browser/test/sdk.test.ts

@@ -61,6 +61,32 @@ describe('init', () => {
  expect(optionsPassed?.integrations.length).toBeGreaterThan(0);
  });
 
+ it('installs spanStreamingIntegration by default', () => {
+ // @ts-expect-error this is fine for testing
+ const initAndBindSpy = vi.spyOn(SentryCore, 'initAndBind').mockImplementationOnce(() => {});
+ const options = getDefaultBrowserOptions({ dsn: PUBLIC_DSN, defaultIntegrations: undefined });
+
+ init(options);
+
+ const optionsPassed = initAndBindSpy.mock.calls[0]?.[1];
+ expect(optionsPassed?.integrations.some(integration => integration.name === 'SpanStreaming')).toBe(true);
+ });
+
+ it('does not install spanStreamingIntegration when traceLifecycle is static', () => {
+ // @ts-expect-error this is fine for testing
+ const initAndBindSpy = vi.spyOn(SentryCore, 'initAndBind').mockImplementationOnce(() => {});
+ const options = getDefaultBrowserOptions({
+ dsn: PUBLIC_DSN,
+ defaultIntegrations: undefined,
+ traceLifecycle: 'static',
+ });
+
+ init(options);
+
+ const optionsPassed = initAndBindSpy.mock.calls[0]?.[1];
+ expect(optionsPassed?.integrations.some(integration => integration.name === 'SpanStreaming')).toBe(false);
+ });
+
  test("doesn't install default integrations if told not to", () => {
  const DEFAULT_INTEGRATIONS: Integration[] = [
  new MockIntegration('MockIntegration 0.3'),
@@ -73,6 +99,17 @@ describe('init', () => {
  expect(DEFAULT_INTEGRATIONS[1]!.setupOnce as Mock).toHaveBeenCalledTimes(0);
  });
 
+ it('installs spanStreamingIntegration with defaultIntegrations disabled', () => {
+ // @ts-expect-error this is fine for testing
+ const initAndBindSpy = vi.spyOn(SentryCore, 'initAndBind').mockImplementationOnce(() => {});
+ const options = getDefaultBrowserOptions({ dsn: PUBLIC_DSN, defaultIntegrations: false });
+
+ init(options);
+
+ const optionsPassed = initAndBindSpy.mock.calls[0]?.[1];
+ expect(optionsPassed?.integrations.some(integration => integration.name === 'SpanStreaming')).toBe(true);
+ });
+
  it('installs merged default integrations, with overrides provided through options', () => {
  const DEFAULT_INTEGRATIONS = [
  new MockIntegration('MockIntegration 1.1'),

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

@@ -27,6 +27,7 @@ export function createSentryInstance(
  dsn: 'https://4c2bae7d9fbc413e8f7385f55c515d51@o1.ingest.sentry.io/6690737',
 
  tracesSampleRate: 1,
+ traceLifecycle: 'static',
  sampleRate: 1,
 
  release: LIB_VERSION,

packages/cloudflare/src/options.ts

@@ -70,6 +70,7 @@ export function getFinalOptions(userOptions: CloudflareOptions = {}, env: unknow
  tracesSampleRate: isFinite(tracesSampleRate) ? tracesSampleRate : undefined,
  debug: userOptions.debug ?? envToBool(getEnvVar(env, 'SENTRY_DEBUG')),
  tunnel: userOptions.tunnel ?? getEnvVar(env, 'SENTRY_TUNNEL'),
+ traceLifecycle: userOptions.traceLifecycle ?? getTraceLifecycleFromEnv(getEnvVar(env, 'SENTRY_TRACE_LIFECYCLE')),
  /*! rollup-include-development-only */
  spotlight,
  /*! rollup-include-development-only-end */
@@ -102,3 +103,7 @@ function getSpotlightFromEnv(
  ? (envUrl ?? true) // true: use env URL if present, otherwise true
  : (envBool ?? envUrl); // undefined: use env var (bool or URL)
 }
+
+function getTraceLifecycleFromEnv(envVar: string | undefined): 'static' | 'stream' | undefined {
+ return envVar === 'stream' || envVar === 'static' ? envVar : undefined;
+}

packages/cloudflare/test/sdk.test.ts

@@ -22,10 +22,9 @@ describe('init', () => {
  expect(client).toBeInstanceOf(CloudflareClient);
  });
 
- test('installs SpanStreaming integration when traceLifecycle is "stream"', () => {
+ test('installs SpanStreaming integration by default', () => {
  init({
  dsn: 'https://public@dsn.ingest.sentry.io/1337',
- traceLifecycle: 'stream',
  });
  const client = getClient();
 
@@ -36,8 +35,8 @@ describe('init', () => {
  );
  });
 
- test("does not install SpanStreaming integration when traceLifecycle is not 'stream'", () => {
- init({ dsn: 'https://public@dsn.ingest.sentry.io/1337' });
+ test("does not install SpanStreaming integration when traceLifecycle is 'static'", () => {
+ init({ dsn: 'https://public@dsn.ingest.sentry.io/1337', traceLifecycle: 'static' });
  const client = getClient();
 
  expect(client?.getOptions()).toEqual(

packages/core/src/client.ts

@@ -234,7 +234,7 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
  * @param options Options for the client.
  */
  protected constructor(options: O) {
- this._options = { attachStacktrace: true, ...options };
+ this._options = { attachStacktrace: true, traceLifecycle: 'stream', ...options };
  this._integrations = {};
  this._numProcessing = 0;
  this._outcomes = {};

packages/core/src/server-runtime-client.ts

@@ -40,6 +40,8 @@ export class ServerRuntimeClient<
  public constructor(options: O) {
  addUserAgentToTransportHeaders(options);
 
+ options.traceLifecycle ??= 'stream';
+
  // When span streaming is enabled (`traceLifecycle: 'stream'`), the `spanStreamingIntegration`
  // is required to flush spans. We add it here so the individual server SDKs don't have to.
  // A user-provided `spanStreamingIntegration` always takes precedence over the one we add.

packages/core/src/types/options.ts

@@ -543,7 +543,7 @@ export interface ClientOptions<TO extends BaseTransportOptions = BaseTransportOp
  * The trace lifecycle, determining whether spans are sent statically when the entire local span tree is complete,
  * or streamed in batches, following interval- and action-based triggers.
  *
- * @default 'static'
+ * @default 'stream'
  */
  traceLifecycle?: 'static' | 'stream';
 

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

@@ -103,7 +103,21 @@ describe('Client', () => {
  const options = getDefaultTestClientOptions({ dsn: PUBLIC_DSN, test: true });
  const client = new TestClient(options);
 
- expect(client.getOptions()).toEqual({ attachStacktrace: true, ...options });
+ expect(client.getOptions()).toEqual({ attachStacktrace: true, traceLifecycle: 'stream', ...options });
+ });
+
+ test('defaults traceLifecycle to stream', () => {
+ const options = getDefaultTestClientOptions();
+ delete options.traceLifecycle;
+ const client = new TestClient(options);
+
+ expect(client.getOptions().traceLifecycle).toBe('stream');
+ });
+
+ test('preserves an explicit static traceLifecycle', () => {
+ const client = new TestClient(getDefaultTestClientOptions({ traceLifecycle: 'static' }));
+
+ expect(client.getOptions().traceLifecycle).toBe('static');
  });
  });
 

packages/deno/test/sdk.test.ts

@@ -8,17 +8,17 @@ Deno.test('init() should return client', () => {
  assertNotEquals(init({}), undefined);
 });
 
-Deno.test('adds spanStreamingIntegration when traceLifecycle is "stream"', () => {
- const client = init({ traceLifecycle: 'stream' });
+Deno.test('adds spanStreamingIntegration by default', () => {
+ const client = init({});
  const integrations = client.getOptions().integrations;
  assertArrayIncludes(
  integrations.map(i => i.name),
  ['SpanStreaming'],
  );
 });
 
-Deno.test('doesn\'t add spanStreamingIntegration when traceLifecycle is not "stream"', () => {
- const client = init({});
+Deno.test('doesn\'t add spanStreamingIntegration when traceLifecycle is "static"', () => {
+ const client = init({ traceLifecycle: 'static' });
  const integrations = client.getOptions().integrations;
  assert(!integrations.some(i => i.name === 'SpanStreaming'));
 });

packages/node/src/sdk/index.ts

@@ -300,6 +300,7 @@ function getClientOptions(
  const spotlight = getSpotlightConfig(options.spotlight);
 
  const tracesSampleRate = getTracesSampleRate(options.tracesSampleRate);
+ const traceLifecycle = getTraceLifecycle(options.traceLifecycle);
 
  const mergedOptions = {
  ...options,
@@ -311,6 +312,7 @@ function getClientOptions(
  release,
  tracesSampleRate,
  spotlight,
+ traceLifecycle,
  debug: envToBool(options.debug ?? process.env.SENTRY_DEBUG),
  };
 
@@ -355,6 +357,20 @@ function getTracesSampleRate(tracesSampleRate: NodeOptions['tracesSampleRate']):
  return isFinite(parsed) ? parsed : undefined;
 }
 
+function getTraceLifecycle(traceLifecycle: NodeOptions['traceLifecycle']): 'stream' | 'static' {
+ if (traceLifecycle !== undefined) {
+ return traceLifecycle;
+ }
+
+ const lifecycleFromEnv = process.env.SENTRY_TRACE_LIFECYCLE;
+
+ if (lifecycleFromEnv === 'stream' || lifecycleFromEnv === 'static') {
+ return lifecycleFromEnv;
+ }
+
+ return 'stream';
+}
+
 /**
  * Update scope and propagation context based on environmental variables.
  *

packages/node/test/sdk/init.test.ts

@@ -59,16 +59,12 @@ describe('init()', () => {
  });
 
  describe('integrations', () => {
- it("doesn't install default integrations if told not to", () => {
+ it('only installs the required spanStreaming integration if default integrations are disabled', () => {
  init({ dsn: PUBLIC_DSN, defaultIntegrations: false });
 
  const client = getClient();
 
- expect(client?.getOptions()).toEqual(
- expect.objectContaining({
- integrations: [],
- }),
- );
+ expect(client?.getOptions().integrations.map(integration => integration.name)).toEqual(['SpanStreaming']);
 
  expect(mockAutoPerformanceIntegrations).toHaveBeenCalledTimes(0);
  });
@@ -169,8 +165,8 @@ describe('init()', () => {
  );
  });
 
- it('installs spanStreaming integration when traceLifecycle is "stream"', () => {
- init({ dsn: PUBLIC_DSN, traceLifecycle: 'stream' });
+ it('installs spanStreaming integration by default', () => {
+ init({ dsn: PUBLIC_DSN });
  const client = getClient();
 
  expect(client?.getOptions()).toEqual(
@@ -180,8 +176,8 @@ describe('init()', () => {
  );
  });
 
- it("doesn't install spanStreaming integration when traceLifecycle is not 'stream'", () => {
- init({ dsn: PUBLIC_DSN });
+ it("doesn't install spanStreaming integration when traceLifecycle is 'static'", () => {
+ init({ dsn: PUBLIC_DSN, traceLifecycle: 'static' });
 
  const client = getClient();
  expect(client?.getOptions()).toEqual(
@@ -192,7 +188,7 @@ describe('init()', () => {
  });
 
  it('installs spanStreaming integration even with custom defaultIntegrations', () => {
- init({ dsn: PUBLIC_DSN, traceLifecycle: 'stream', defaultIntegrations: [] });
+ init({ dsn: PUBLIC_DSN, defaultIntegrations: [] });
  const client = getClient();
 
  expect(client?.getOptions()).toEqual(