ref(core): Export browser-specific span start APIs

packages/astro/src/index.types.ts

@@ -21,6 +21,9 @@ export declare function init(options: Options | clientSdk.BrowserOptions | NodeO
 export declare const linkedErrorsIntegration: typeof clientSdk.linkedErrorsIntegration;
 export declare const contextLinesIntegration: typeof clientSdk.contextLinesIntegration;
 export declare const spanStreamingIntegration: typeof clientSdk.spanStreamingIntegration;
+export declare const startSpan: typeof clientSdk.startSpan;
+export declare const startSpanManual: typeof clientSdk.startSpanManual;
+export declare const startInactiveSpan: typeof clientSdk.startInactiveSpan;
 export declare const withStaticSpan: typeof clientSdk.withStaticSpan;
 // oxlint-disable-next-line typescript/no-deprecated
 export declare const withStreamedSpan: typeof clientSdk.withStreamedSpan;

packages/browser/src/index.bundle.tracing.logs.metrics.ts

@@ -29,7 +29,7 @@ export { elementTimingIntegration } from '@sentry/browser-utils';
 export { reportPageLoaded } from './tracing/reportPageLoaded';
 export { setActiveSpanInBrowser } from './tracing/setActiveSpan';
 
-export { spanStreamingIntegration } from './integrations/spanstreaming';
+export { spanStreamingIntegration } from '@sentry/core/browser';
 export { fetchStreamPerformanceIntegration } from './integrations/fetchStreamPerformance';
 export { webVitalsIntegration } from './integrations/webVitals';
 

packages/browser/src/index.bundle.tracing.replay.feedback.logs.metrics.ts

@@ -30,7 +30,7 @@ export { elementTimingIntegration } from '@sentry/browser-utils';
 export { reportPageLoaded } from './tracing/reportPageLoaded';
 export { setActiveSpanInBrowser } from './tracing/setActiveSpan';
 
-export { spanStreamingIntegration } from './integrations/spanstreaming';
+export { spanStreamingIntegration } from '@sentry/core/browser';
 export { fetchStreamPerformanceIntegration } from './integrations/fetchStreamPerformance';
 export { webVitalsIntegration } from './integrations/webVitals';
 

packages/browser/src/index.bundle.tracing.replay.feedback.ts

@@ -36,7 +36,7 @@ export { setActiveSpanInBrowser } from './tracing/setActiveSpan';
 
 export { reportPageLoaded } from './tracing/reportPageLoaded';
 
-export { spanStreamingIntegration } from './integrations/spanstreaming';
+export { spanStreamingIntegration } from '@sentry/core/browser';
 export { fetchStreamPerformanceIntegration } from './integrations/fetchStreamPerformance';
 export { webVitalsIntegration } from './integrations/webVitals';
 

packages/browser/src/index.bundle.tracing.replay.logs.metrics.ts

@@ -29,7 +29,7 @@ export { elementTimingIntegration } from '@sentry/browser-utils';
 export { reportPageLoaded } from './tracing/reportPageLoaded';
 export { setActiveSpanInBrowser } from './tracing/setActiveSpan';
 
-export { spanStreamingIntegration } from './integrations/spanstreaming';
+export { spanStreamingIntegration } from '@sentry/core/browser';
 export { fetchStreamPerformanceIntegration } from './integrations/fetchStreamPerformance';
 export { webVitalsIntegration } from './integrations/webVitals';
 

packages/browser/src/index.bundle.tracing.replay.ts

@@ -35,7 +35,7 @@ export { elementTimingIntegrationShim as elementTimingIntegration };
 export { reportPageLoaded } from './tracing/reportPageLoaded';
 export { setActiveSpanInBrowser } from './tracing/setActiveSpan';
 
-export { spanStreamingIntegration } from './integrations/spanstreaming';
+export { spanStreamingIntegration } from '@sentry/core/browser';
 export { fetchStreamPerformanceIntegration } from './integrations/fetchStreamPerformance';
 export { webVitalsIntegration } from './integrations/webVitals';
 

packages/browser/src/index.bundle.tracing.ts

@@ -37,7 +37,7 @@ export { setActiveSpanInBrowser } from './tracing/setActiveSpan';
 
 export { reportPageLoaded } from './tracing/reportPageLoaded';
 
-export { spanStreamingIntegration } from './integrations/spanstreaming';
+export { spanStreamingIntegration } from '@sentry/core/browser';
 export { fetchStreamPerformanceIntegration } from './integrations/fetchStreamPerformance';
 export { webVitalsIntegration } from './integrations/webVitals';
 

packages/browser/src/index.ts

@@ -37,7 +37,7 @@ export { elementTimingIntegration, getAbsoluteUrl } from '@sentry/browser-utils'
 export { normalizeStringifyValue } from './normalizeStringifyValue';
 export { reportPageLoaded } from './tracing/reportPageLoaded';
 export { setActiveSpanInBrowser } from './tracing/setActiveSpan';
-export { spanStreamingIntegration } from './integrations/spanstreaming';
+export { spanStreamingIntegration } from '@sentry/core/browser';
 export { fetchStreamPerformanceIntegration } from './integrations/fetchStreamPerformance';
 export { webVitalsIntegration } from './integrations/webVitals';
 export { userTimingIntegration } from './integrations/usertiming';

packages/browser/src/sdk.ts

@@ -7,6 +7,7 @@ import {
   getIntegrationsToSetup,
   initAndBind,
   setNormalizeStringifier,
+  spanStreamingIntegration,
   stackParserFromStackParserOptions,
 } from '@sentry/core/browser';
 import type { BrowserClientOptions, BrowserOptions } from './client';
@@ -19,10 +20,6 @@ import { globalHandlersIntegration } from './integrations/globalhandlers';
 import { httpContextIntegration } from './integrations/httpcontext';
 import { linkedErrorsIntegration } from './integrations/linkederrors';
 import { spotlightBrowserIntegration } from './integrations/spotlight';
-import {
-  spanStreamingIntegration,
-  INTEGRATION_NAME as SPAN_STREAMING_INTEGRATION_NAME,
-} from './integrations/spanstreaming';
 import { defaultStackParser } from './stack-parsers';
 import { makeFetchTransport } from './transports/fetch';
 import { normalizeStringifyValue } from './normalizeStringifyValue';
@@ -122,7 +119,7 @@ export function init(options: BrowserOptions = {}): Client | undefined {
   if (
     (typeof __SENTRY_TRACING__ === 'undefined' || __SENTRY_TRACING__) &&
     options.traceLifecycle !== 'static' &&
-    !integrations.some(integration => integration.name === SPAN_STREAMING_INTEGRATION_NAME)
+    !integrations.some(integration => integration.name === 'SpanStreaming')
   ) {
     integrations.push(spanStreamingIntegration());
   }

packages/core/src/browser-exports.ts

@@ -3,6 +3,17 @@
  *
  * @module
  */
+
+export {
+  startSpan,
+  startInactiveSpan,
+  startSpanManual,
+  startIdleSpan,
+  _INTERNAL_ensureBrowserSpanStreaming,
+} from './tracing/browserSpanApi';
+
+export { spanStreamingIntegration } from './integrations/browserSpanStreaming';
+
 export {
   getComponentName,
   getLocationHref,

packages/core/src/fetch.ts

@@ -3,7 +3,8 @@ import { HTTP_METHOD, SERVER_ADDRESS, URL_FRAGMENT, URL_FULL, URL_QUERY } from '
 import type { Client } from './client';
 import { getClient } from './currentScopes';
 import { SEMANTIC_ATTRIBUTE_SENTRY_OP, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN } from './semanticAttributes';
-import { setHttpStatus, SPAN_STATUS_ERROR, spanIsIgnored, startInactiveSpan } from './tracing';
+import { setHttpStatus, SPAN_STATUS_ERROR, spanIsIgnored } from './tracing';
+import { startInactiveSpan } from './tracing/trace';
 import { SentryNonRecordingSpan } from './tracing/sentryNonRecordingSpan';
 import { hasSpanStreamingEnabled } from './tracing/spans/hasSpanStreamingEnabled';
 import type { FetchBreadcrumbHint } from './types/breadcrumb';

packages/core/src/index.ts

@@ -6,3 +6,10 @@ export * from './shared-exports';
 export { warnOnRemovedBuildOptions } from './build-time-plugins/warnOnRemovedBuildOptions';
 export * from './server-exports';
 export * from './browser-exports';
+
+// `server-exports` and `browser-exports` both export these APIs.
+// We need to re-export them here to disambiguate the exports for anyone importing
+// from `@sentry/core`. Server exports win over browser exports.
+export { startSpan, startInactiveSpan, startSpanManual } from './tracing/trace';
+export { startIdleSpan } from './tracing/idleSpan';
+export { spanStreamingIntegration } from './integrations/spanStreaming';

packages/browser/src/integrations/spanstreaming.ts → packages/core/src/integrations/browserSpanStreaming.ts

@@ -1,13 +1,11 @@
-import type { IntegrationFn } from '@sentry/core/browser';
-import {
-  captureSpan,
-  debug,
-  defineIntegration,
-  hasSpanStreamingEnabled,
-  SpanBuffer,
-  spanIsSampled,
-} from '@sentry/core/browser';
+import type { IntegrationFn } from '../types/integration';
 import { DEBUG_BUILD } from '../debug-build';
+import { defineIntegration } from '../integration';
+import { captureSpan } from '../tracing/spans/captureSpan';
+import { hasSpanStreamingEnabled } from '../tracing/spans/hasSpanStreamingEnabled';
+import { SpanBuffer } from '../tracing/spans/spanBuffer';
+import { debug } from '../utils/debug-logger';
+import { spanIsSampled } from '../utils/spanUtils';
 
 export const INTEGRATION_NAME = 'SpanStreaming' as const;
 

packages/core/src/integrations/express/patch-layer.ts

@@ -31,7 +31,8 @@ import { SENTRY_OP } from '@sentry/conventions/attributes';
 import { WEB_SERVER_MIDDLEWARE_SPAN_OP } from '@sentry/conventions/op';
 import { DEBUG_BUILD } from '../../debug-build';
 import { SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN } from '../../semanticAttributes';
-import { SPAN_STATUS_ERROR, startSpanManual, withActiveSpan } from '../../tracing';
+import { SPAN_STATUS_ERROR, withActiveSpan } from '../../tracing';
+import { startSpanManual } from '../../tracing/trace';
 import { debug } from '../../utils/debug-logger';
 import type { SpanAttributes } from '../../types/span';
 import { getActiveSpan } from '../../utils/spanUtils';

packages/core/src/integrations/http/client-subscriptions.ts

@@ -21,9 +21,9 @@ import {
   isTracingSuppressed,
   SPAN_STATUS_ERROR,
   SPAN_STATUS_UNSET,
-  startInactiveSpan,
   withActiveSpan,
 } from '../../tracing';
+import { startInactiveSpan } from '../../tracing/trace';
 import { debug } from '../../utils/debug-logger';
 import { LRUMap } from '../../utils/lru';
 import { getOutgoingRequestSpanData, setIncomingResponseSpanData } from './get-outgoing-span-data';

packages/core/src/integrations/http/server-subscription.ts

@@ -31,7 +31,8 @@ import { parseStringToURLObject, stripUrlQueryAndFragment } from '../../utils/ur
 import { recordRequestSession } from './record-request-session';
 import { generateSpanId, generateTraceId } from '../../utils/propagationContext';
 import { continueTrace } from '../../tracing/trace';
-import { getSpanStatusFromHttpCode, SPAN_STATUS_ERROR, startSpanManual } from '../../tracing';
+import { getSpanStatusFromHttpCode, SPAN_STATUS_ERROR } from '../../tracing';
+import { startSpanManual } from '../../tracing/trace';
 import {
   SEMANTIC_ATTRIBUTE_SENTRY_OP,
   SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,

packages/core/src/integrations/mcp-server/spans.ts

@@ -11,7 +11,7 @@ import {
   SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
   SEMANTIC_ATTRIBUTE_SENTRY_SOURCE,
 } from '../../semanticAttributes';
-import { startSpan } from '../../tracing';
+import { startSpan } from '../../tracing/trace';
 import { buildTransportAttributes, buildTypeSpecificAttributes } from './attributeExtraction';
 import {
   MCP_FUNCTION_ORIGIN_VALUE,

packages/core/src/integrations/mcp-server/transport.ts

@@ -6,7 +6,8 @@
  */
 
 import { getIsolationScope, withIsolationScope } from '../../currentScopes';
-import { startInactiveSpan, withActiveSpan } from '../../tracing';
+import { withActiveSpan } from '../../tracing';
+import { startInactiveSpan } from '../../tracing/trace';
 import { isObjectLike } from '../../utils/is';
 import { fill } from '../../utils/object';
 import { MCP_PROTOCOL_VERSION_ATTRIBUTE } from './attributes';

packages/core/src/integrations/postgresjs.ts

@@ -4,7 +4,8 @@
 
 import { DEBUG_BUILD } from '../debug-build';
 import { SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN } from '../semanticAttributes';
-import { SPAN_STATUS_ERROR, startSpanManual } from '../tracing';
+import { SPAN_STATUS_ERROR } from '../tracing';
+import { startSpanManual } from '../tracing/trace';
 import type { Span } from '../types/span';
 import { debug } from '../utils/debug-logger';
 import { isObjectLike } from '../utils/is';

packages/core/src/integrations/supabase.ts

@@ -10,7 +10,8 @@ import { DEBUG_BUILD } from '../debug-build';
 import { captureException } from '../exports';
 import { defineIntegration } from '../integration';
 import { SEMANTIC_ATTRIBUTE_SENTRY_OP, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN } from '../semanticAttributes';
-import { setHttpStatus, SPAN_STATUS_ERROR, SPAN_STATUS_OK, startSpan } from '../tracing';
+import { setHttpStatus, SPAN_STATUS_ERROR, SPAN_STATUS_OK } from '../tracing';
+import { startSpan } from '../tracing/trace';
 import type { IntegrationFn } from '../types/integration';
 import type { WebFetchHeaders } from '../types/webfetchapi';
 import { debug } from '../utils/debug-logger';

packages/core/src/server-exports.ts

@@ -4,6 +4,10 @@
  * @module
  */
 
+export { startSpan, startInactiveSpan, startSpanManual } from './tracing/trace';
+export { startIdleSpan } from './tracing/idleSpan';
+export { spanStreamingIntegration } from './integrations/spanStreaming';
+
 export type { ServerRuntimeClientOptions } from './server-runtime-client';
 export { ServerRuntimeClient } from './server-runtime-client';
 export type { ServerRuntimeOptions } from './types/options';

packages/core/src/shared-exports.ts

@@ -177,7 +177,6 @@ export type { MetricOptions } from './metrics/public-api';
 export { createConsolaReporter } from './integrations/consola';
 export { SpanBuffer } from './tracing/spans/spanBuffer';
 export { hasSpanStreamingEnabled } from './tracing/spans/hasSpanStreamingEnabled';
-export { spanStreamingIntegration } from './integrations/spanStreaming';
 export type { FeatureFlag } from './utils/featureFlags';
 export {
   _INTERNAL_copyFlagsFromScopeToEvent,

packages/core/src/tracing/browserSpanApi.ts

@@ -0,0 +1,85 @@
+import type { Client } from '../client';
+import { getClient } from '../currentScopes';
+import { spanStreamingIntegration } from '../integrations/browserSpanStreaming';
+import type { Span } from '../types/span';
+import type { StartSpanOptions } from '../types/startSpanOptions';
+import { startIdleSpan as coreStartIdleSpan } from './idleSpan';
+import { hasSpanStreamingEnabled } from './spans/hasSpanStreamingEnabled';
+import {
+  startInactiveSpan as coreStartInactiveSpan,
+  startSpan as coreStartSpan,
+  startSpanManual as coreStartSpanManual,
+} from './trace';
+
+/**
+ * Browser variants of the span-start APIs.
+ *
+ * These exist purely so that the span streaming integration is only reachable from code that can
+ * actually start a span. `@sentry/browser`'s `init()` deliberately doesn't reference spanStreamingIntegration,
+ * so error-only apps tree-shake the entire span streaming graph away without needing
+ * the `__SENTRY_TRACING__` flag.
+ */
+
+const clientsWithIntegration = new WeakSet<Client>();
+
+/**
+ * Lazily install the browser span streaming integration.
+ *
+ * Defaults to the current client; pass one explicitly from integration hooks, where the client being
+ * set up isn't necessarily the current one.
+ *
+ * @internal
+ */
+export function _INTERNAL_ensureBrowserSpanStreaming(client: Client | undefined = getClient()): void {
+  // The `WeakSet` is an allocation optimization, not a semantic gate — `addIntegration()` is already
+  // idempotent by integration name, including against a user-supplied instance.
+  if (!client || clientsWithIntegration.has(client) || !hasSpanStreamingEnabled(client)) {
+    return;
+  }
+
+  clientsWithIntegration.add(client);
+  client.addIntegration(spanStreamingIntegration());
+}
+
+/**
+ * Wraps a function with a span and finishes the span after the function is done.
+ *
+ * See {@link startSpan} in `@sentry/core` for details.
+ */
+export function startSpan<T>(options: StartSpanOptions, callback: (span: Span) => T): T {
+  _INTERNAL_ensureBrowserSpanStreaming();
+  return coreStartSpan(options, callback);
+}
+
+/**
+ * Similar to `startSpan`, but forces the span to be ended manually.
+ *
+ * See {@link startSpanManual} in `@sentry/core` for details.
+ */
+export function startSpanManual<T>(options: StartSpanOptions, callback: (span: Span, finish: () => void) => T): T {
+  _INTERNAL_ensureBrowserSpanStreaming();
+  return coreStartSpanManual(options, callback);
+}
+
+/**
+ * Creates a span that is not set as active.
+ *
+ * See {@link startInactiveSpan} in `@sentry/core` for details.
+ */
+export function startInactiveSpan(options: StartSpanOptions): Span {
+  _INTERNAL_ensureBrowserSpanStreaming();
+  return coreStartInactiveSpan(options);
+}
+
+/**
+ * Starts an idle span that automatically ends once no activity happens for a while.
+ *
+ * See {@link startIdleSpan} in `@sentry/core` for details.
+ *
+ * Typed via `typeof` because `IdleSpanOptions` is intentionally not part of the public type surface,
+ * and re-declaring the signature here would have to widen it.
+ */
+export const startIdleSpan: typeof coreStartIdleSpan = (startSpanOptions, options) => {
+  _INTERNAL_ensureBrowserSpanStreaming();
+  return coreStartIdleSpan(startSpanOptions, options);
+};

packages/core/src/tracing/index.ts

@@ -5,7 +5,7 @@ export {
   markSpanAsTracerProviderSpan,
   spanIsTracerProviderSpan,
 } from './utils';
-export { startIdleSpan, TRACING_DEFAULTS } from './idleSpan';
+export { TRACING_DEFAULTS } from './idleSpan';
 export { SentrySpan } from './sentrySpan';
 export { _INTERNAL_setDeferSegmentSpanCapture } from './deferSegmentSpanCapture';
 export { SentryNonRecordingSpan } from './sentryNonRecordingSpan';

packages/core/src/trpc.ts

@@ -9,7 +9,7 @@ import { WEB_SERVER_RPC_SPAN_OP } from '@sentry/conventions/op';
 import { getClient, withIsolationScope } from './currentScopes';
 import { captureException } from './exports';
 import { SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, SEMANTIC_ATTRIBUTE_SENTRY_SOURCE } from './semanticAttributes';
-import { startSpanManual } from './tracing';
+import { startSpanManual } from './tracing/trace';
 import { normalize } from './utils/normalize';
 import { setNormalizationDepthOverrideHint } from './utils/normalizationHints';
 

packages/core/test/exports.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+import * as browserEntry from '../src/browser';
+import * as rootEntry from '../src/index';
+import { spanStreamingIntegration as browserSpanStreamingIntegration } from '../src/integrations/browserSpanStreaming';
+import { spanStreamingIntegration as plainSpanStreamingIntegration } from '../src/integrations/spanStreaming';
+import * as serverEntry from '../src/server';
+import * as browserSpanApi from '../src/tracing/browserSpanApi';
+import { startIdleSpan as plainStartIdleSpan } from '../src/tracing/idleSpan';
+import {
+  startInactiveSpan as plainStartInactiveSpan,
+  startSpan as plainStartSpan,
+  startSpanManual as plainStartSpanManual,
+} from '../src/tracing/trace';
+
+// `server-exports` and `browser-exports` export these names with different implementations, which
+// makes them ambiguous star exports at the root entry. `index.ts` disambiguates them with explicit
+// re-exports — if someone adds another `export *` that also carries one of these names, or drops the
+// explicit re-export, the root entry silently flips to the wrong variant (or fails to link).
+describe('entry point resolution', () => {
+  const cases = [
+    ['startSpan', plainStartSpan, browserSpanApi.startSpan],
+    ['startInactiveSpan', plainStartInactiveSpan, browserSpanApi.startInactiveSpan],
+    ['startSpanManual', plainStartSpanManual, browserSpanApi.startSpanManual],
+    ['startIdleSpan', plainStartIdleSpan, browserSpanApi.startIdleSpan],
+    ['spanStreamingIntegration', plainSpanStreamingIntegration, browserSpanStreamingIntegration],
+  ] as const;
+
+  it.each(cases)('`%s`: the root entry serves the plain variant', (name, plain) => {
+    expect(rootEntry[name]).toBe(plain);
+  });
+
+  it.each(cases)('`%s`: the server entry serves the plain variant', (name, plain) => {
+    expect(serverEntry[name]).toBe(plain);
+  });
+
+  it.each(cases)('`%s`: the browser entry serves the browser variant', (name, plain, browser) => {
+    expect(browserEntry[name]).toBe(browser);
+    expect(browserEntry[name]).not.toBe(plain);
+  });
+});