feat(browser): Add setSpanActive to create an active root span in the browser

Lms24 · Lms24 · commit 410ca15c3f88 · 2025-09-22T17:19:50.000+02:00
diff --git a/dev-packages/browser-integration-tests/suites/tracing/setSpanActive/default/init.js b/dev-packages/browser-integration-tests/suites/tracing/setSpanActive/default/init.js
@@ -0,0 +1,8 @@
+import * as Sentry from '@sentry/browser';
+
+window.Sentry = Sentry;
+
+Sentry.init({
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  tracesSampleRate: 1,
+});
diff --git a/dev-packages/browser-integration-tests/suites/tracing/setSpanActive/default/subject.js b/dev-packages/browser-integration-tests/suites/tracing/setSpanActive/default/subject.js
@@ -0,0 +1,14 @@
+const checkoutSpan = Sentry.startInactiveSpan({ name: 'checkout-flow' });
+Sentry.setSpanActive(checkoutSpan);
+
+Sentry.startSpan({ name: 'checkout-step-1' }, () => {
+  Sentry.startSpan({ name: 'checkout-step-1-1' }, () => {
+    // ... `
+  });
+});
+
+Sentry.startSpan({ name: 'checkout-step-2' }, () => {
+  // ... `
+});
+
+checkoutSpan.end();
diff --git a/dev-packages/browser-integration-tests/suites/tracing/setSpanActive/default/test.ts b/dev-packages/browser-integration-tests/suites/tracing/setSpanActive/default/test.ts
@@ -0,0 +1,35 @@
+import { expect } from '@playwright/test';
+import { sentryTest } from '../../../../utils/fixtures';
+import { envelopeRequestParser, shouldSkipTracingTest, waitForTransactionRequest } from '../../../../utils/helpers';
+
+sentryTest('sets an inactive span active and adds child spans to it', async ({ getLocalTestUrl, page }) => {
+  if (shouldSkipTracingTest()) {
+    sentryTest.skip();
+  }
+
+  const req = waitForTransactionRequest(page, e => e.transaction === 'checkout-flow');
+
+  const url = await getLocalTestUrl({ testDir: __dirname });
+  await page.goto(url);
+
+  const checkoutEvent = envelopeRequestParser(await req);
+  const checkoutSpanId = checkoutEvent.contexts?.trace?.span_id;
+  expect(checkoutSpanId).toMatch(/[a-f0-9]{16}/);
+
+  expect(checkoutEvent.spans).toHaveLength(3);
+
+  const checkoutStep1 = checkoutEvent.spans?.find(s => s.description === 'checkout-step-1');
+  const checkoutStep11 = checkoutEvent.spans?.find(s => s.description === 'checkout-step-1-1');
+  const checkoutStep2 = checkoutEvent.spans?.find(s => s.description === 'checkout-step-2');
+
+  expect(checkoutStep1).toBeDefined();
+  expect(checkoutStep11).toBeDefined();
+  expect(checkoutStep2).toBeDefined();
+
+  expect(checkoutStep1?.parent_span_id).toBe(checkoutSpanId);
+  expect(checkoutStep2?.parent_span_id).toBe(checkoutSpanId);
+
+  // despite 1-1 being called within 1, it's still parented to the root span
+  // due to this being default behaviour in browser environments
+  expect(checkoutStep11?.parent_span_id).toBe(checkoutSpanId);
+});
diff --git a/dev-packages/browser-integration-tests/suites/tracing/setSpanActive/nested-parentAlwaysRoot/init.js b/dev-packages/browser-integration-tests/suites/tracing/setSpanActive/nested-parentAlwaysRoot/init.js
@@ -0,0 +1,9 @@
+import * as Sentry from '@sentry/browser';
+
+window.Sentry = Sentry;
+
+Sentry.init({
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  tracesSampleRate: 1,
+  parentSpanIsAlwaysRootSpan: false,
+});
diff --git a/dev-packages/browser-integration-tests/suites/tracing/setSpanActive/nested-parentAlwaysRoot/subject.js b/dev-packages/browser-integration-tests/suites/tracing/setSpanActive/nested-parentAlwaysRoot/subject.js
@@ -0,0 +1,22 @@
+const checkoutSpan = Sentry.startInactiveSpan({ name: 'checkout-flow' });
+Sentry.setSpanActive(checkoutSpan);
+
+Sentry.startSpan({ name: 'checkout-step-1' }, () => {});
+
+const checkoutStep2 = Sentry.startInactiveSpan({ name: 'checkout-step-2' });
+Sentry.setSpanActive(checkoutStep2);
+
+Sentry.startSpan({ name: 'checkout-step-2-1' }, () => {
+  // ... `
+});
+checkoutStep2.end();
+
+Sentry.startSpan({ name: 'checkout-step-3' }, () => {});
+
+checkoutSpan.end();
+
+Sentry.startSpan({ name: 'post-checkout' }, () => {
+  Sentry.startSpan({ name: 'post-checkout-1' }, () => {
+    // ... `
+  });
+});
diff --git a/dev-packages/browser-integration-tests/suites/tracing/setSpanActive/nested-parentAlwaysRoot/test.ts b/dev-packages/browser-integration-tests/suites/tracing/setSpanActive/nested-parentAlwaysRoot/test.ts
@@ -0,0 +1,57 @@
+import { expect } from '@playwright/test';
+import { sentryTest } from '../../../../utils/fixtures';
+import { envelopeRequestParser, shouldSkipTracingTest, waitForTransactionRequest } from '../../../../utils/helpers';
+
+sentryTest(
+  'nested calls to setSpanActive with parentSpanIsAlwaysRootSpan=false result in correct parenting',
+  async ({ getLocalTestUrl, page }) => {
+    if (shouldSkipTracingTest()) {
+      sentryTest.skip();
+    }
+
+    const req = waitForTransactionRequest(page, e => e.transaction === 'checkout-flow');
+    const postCheckoutReq = waitForTransactionRequest(page, e => e.transaction === 'post-checkout');
+
+    const url = await getLocalTestUrl({ testDir: __dirname });
+    await page.goto(url);
+
+    const checkoutEvent = envelopeRequestParser(await req);
+    const postCheckoutEvent = envelopeRequestParser(await postCheckoutReq);
+
+    const checkoutSpanId = checkoutEvent.contexts?.trace?.span_id;
+    const postCheckoutSpanId = postCheckoutEvent.contexts?.trace?.span_id;
+
+    expect(checkoutSpanId).toMatch(/[a-f0-9]{16}/);
+    expect(postCheckoutSpanId).toMatch(/[a-f0-9]{16}/);
+
+    expect(checkoutEvent.spans).toHaveLength(4);
+    expect(postCheckoutEvent.spans).toHaveLength(1);
+
+    const checkoutStep1 = checkoutEvent.spans?.find(s => s.description === 'checkout-step-1');
+    const checkoutStep2 = checkoutEvent.spans?.find(s => s.description === 'checkout-step-2');
+    const checkoutStep21 = checkoutEvent.spans?.find(s => s.description === 'checkout-step-2-1');
+    const checkoutStep3 = checkoutEvent.spans?.find(s => s.description === 'checkout-step-3');
+
+    expect(checkoutStep1).toBeDefined();
+    expect(checkoutStep2).toBeDefined();
+    expect(checkoutStep21).toBeDefined();
+    expect(checkoutStep3).toBeDefined();
+
+    expect(checkoutStep1?.parent_span_id).toBe(checkoutSpanId);
+    expect(checkoutStep2?.parent_span_id).toBe(checkoutSpanId);
+
+    // with parentSpanIsAlwaysRootSpan=false, 2-1 is parented to 2 because
+    // 2 was the active span when 2-1 was started
+    expect(checkoutStep21?.parent_span_id).toBe(checkoutStep2?.span_id);
+
+    // since the parent of three is `checkoutSpan`, we correctly reset
+    // the active span to `checkoutSpan` after 2 ended
+    expect(checkoutStep3?.parent_span_id).toBe(checkoutSpanId);
+
+    // post-checkout trace is started as a new trace because ending checkoutSpan removes the active
+    // span on the scope
+    const postCheckoutStep1 = postCheckoutEvent.spans?.find(s => s.description === 'post-checkout-1');
+    expect(postCheckoutStep1).toBeDefined();
+    expect(postCheckoutStep1?.parent_span_id).toBe(postCheckoutSpanId);
+  },
+);
diff --git a/dev-packages/browser-integration-tests/suites/tracing/setSpanActive/nested/init.js b/dev-packages/browser-integration-tests/suites/tracing/setSpanActive/nested/init.js
@@ -0,0 +1,8 @@
+import * as Sentry from '@sentry/browser';
+
+window.Sentry = Sentry;
+
+Sentry.init({
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  tracesSampleRate: 1,
+});
diff --git a/dev-packages/browser-integration-tests/suites/tracing/setSpanActive/nested/subject.js b/dev-packages/browser-integration-tests/suites/tracing/setSpanActive/nested/subject.js
@@ -0,0 +1,22 @@
+const checkoutSpan = Sentry.startInactiveSpan({ name: 'checkout-flow' });
+Sentry.setSpanActive(checkoutSpan);
+
+Sentry.startSpan({ name: 'checkout-step-1' }, () => {});
+
+const checkoutStep2 = Sentry.startInactiveSpan({ name: 'checkout-step-2' });
+Sentry.setSpanActive(checkoutStep2);
+
+Sentry.startSpan({ name: 'checkout-step-2-1' }, () => {
+  // ... `
+});
+checkoutStep2.end();
+
+Sentry.startSpan({ name: 'checkout-step-3' }, () => {});
+
+checkoutSpan.end();
+
+Sentry.startSpan({ name: 'post-checkout' }, () => {
+  Sentry.startSpan({ name: 'post-checkout-1' }, () => {
+    // ... `
+  });
+});
diff --git a/dev-packages/browser-integration-tests/suites/tracing/setSpanActive/nested/test.ts b/dev-packages/browser-integration-tests/suites/tracing/setSpanActive/nested/test.ts
@@ -0,0 +1,49 @@
+import { expect } from '@playwright/test';
+import { sentryTest } from '../../../../utils/fixtures';
+import { envelopeRequestParser, shouldSkipTracingTest, waitForTransactionRequest } from '../../../../utils/helpers';
+
+sentryTest('nested calls to setSpanActive still parent to root span by default', async ({ getLocalTestUrl, page }) => {
+  if (shouldSkipTracingTest()) {
+    sentryTest.skip();
+  }
+
+  const req = waitForTransactionRequest(page, e => e.transaction === 'checkout-flow');
+  const postCheckoutReq = waitForTransactionRequest(page, e => e.transaction === 'post-checkout');
+
+  const url = await getLocalTestUrl({ testDir: __dirname });
+  await page.goto(url);
+
+  const checkoutEvent = envelopeRequestParser(await req);
+  const postCheckoutEvent = envelopeRequestParser(await postCheckoutReq);
+
+  const checkoutSpanId = checkoutEvent.contexts?.trace?.span_id;
+  const postCheckoutSpanId = postCheckoutEvent.contexts?.trace?.span_id;
+
+  expect(checkoutSpanId).toMatch(/[a-f0-9]{16}/);
+  expect(postCheckoutSpanId).toMatch(/[a-f0-9]{16}/);
+
+  expect(checkoutEvent.spans).toHaveLength(4);
+  expect(postCheckoutEvent.spans).toHaveLength(1);
+
+  const checkoutStep1 = checkoutEvent.spans?.find(s => s.description === 'checkout-step-1');
+  const checkoutStep2 = checkoutEvent.spans?.find(s => s.description === 'checkout-step-2');
+  const checkoutStep21 = checkoutEvent.spans?.find(s => s.description === 'checkout-step-2-1');
+  const checkoutStep3 = checkoutEvent.spans?.find(s => s.description === 'checkout-step-3');
+
+  expect(checkoutStep1).toBeDefined();
+  expect(checkoutStep2).toBeDefined();
+  expect(checkoutStep21).toBeDefined();
+  expect(checkoutStep3).toBeDefined();
+
+  expect(checkoutStep1?.parent_span_id).toBe(checkoutSpanId);
+  expect(checkoutStep2?.parent_span_id).toBe(checkoutSpanId);
+  expect(checkoutStep3?.parent_span_id).toBe(checkoutSpanId);
+
+  // despite 2-1 being called within 2 AND setting 2 as active span, it's still parented to the
+  // root span due to this being default behaviour in browser environments
+  expect(checkoutStep21?.parent_span_id).toBe(checkoutSpanId);
+
+  const postCheckoutStep1 = postCheckoutEvent.spans?.find(s => s.description === 'post-checkout-1');
+  expect(postCheckoutStep1).toBeDefined();
+  expect(postCheckoutStep1?.parent_span_id).toBe(postCheckoutSpanId);
+});
diff --git a/packages/browser/src/index.bundle.tracing.replay.feedback.ts b/packages/browser/src/index.bundle.tracing.replay.feedback.ts
@@ -22,6 +22,7 @@ export {
   startBrowserTracingNavigationSpan,
   startBrowserTracingPageLoadSpan,
 } from './tracing/browserTracingIntegration';
+export { setSpanActive } from './tracing/setSpanActive';
 
 export { reportPageLoaded } from './tracing/reportPageLoaded';
 
diff --git a/packages/browser/src/index.bundle.tracing.replay.ts b/packages/browser/src/index.bundle.tracing.replay.ts
@@ -22,8 +22,8 @@ export {
   startBrowserTracingNavigationSpan,
   startBrowserTracingPageLoadSpan,
 } from './tracing/browserTracingIntegration';
-
 export { reportPageLoaded } from './tracing/reportPageLoaded';
+export { setSpanActive } from './tracing/setSpanActive';
 
 export { feedbackIntegrationShim as feedbackAsyncIntegration, feedbackIntegrationShim as feedbackIntegration };
 
diff --git a/packages/browser/src/index.bundle.tracing.ts b/packages/browser/src/index.bundle.tracing.ts
@@ -22,6 +22,7 @@ export {
   startBrowserTracingNavigationSpan,
   startBrowserTracingPageLoadSpan,
 } from './tracing/browserTracingIntegration';
+export { setSpanActive } from './tracing/setSpanActive';
 
 export { reportPageLoaded } from './tracing/reportPageLoaded';
 
diff --git a/packages/browser/src/index.ts b/packages/browser/src/index.ts
@@ -40,6 +40,8 @@ export {
   startBrowserTracingPageLoadSpan,
 } from './tracing/browserTracingIntegration';
 export { reportPageLoaded } from './tracing/reportPageLoaded';
+export { setSpanActive } from './tracing/setSpanActive';
+
 export type { RequestInstrumentationOptions } from './tracing/request';
 export {
   registerSpanErrorInstrumentation,
diff --git a/packages/browser/src/tracing/setSpanActive.ts b/packages/browser/src/tracing/setSpanActive.ts
@@ -0,0 +1,56 @@
+import type { Span } from '@sentry/core';
+import { _INTERNAL_setSpanForScope, getActiveSpan, getCurrentScope } from '@sentry/core';
+
+/**
+ * Sets an inactive span active on the current scope.
+ *
+ * This is useful in browser applications, if you want to create a span that cannot be finished
+ * within its callback. Any spans started while the given span is active, will be children of the span.
+ *
+ * If there already was an active span on the scope prior to calling this function, it is replaced
+ * with the given span and restored after the span ended. Otherwise, the span will simply be
+ * removed, resulting in no active span on the scope.
+ *
+ * IMPORTANT: This function can ONLY be used in the browser! Calling this function in a server
+ * environment (for example in a server-side rendered component) will result in undefined behaviour
+ * and is not supported.
+ * You MUST call `span.end()` manually, otherwise the span will never be finished.
+ *
+ * @example
+ * ```js
+ * let checkoutSpan;
+ *
+ * on('checkoutStarted', () => {
+ *  checkoutSpan = Sentry.startInactiveSpan({ name: 'checkout-flow' });
+ *  Sentry.setSpanActive(checkoutSpan);
+ * })
+ *
+ * // during this time, any spans started will be children of `checkoutSpan`:
+ * Sentry.startSpan({ name: 'checkout-step-1' }, () => {
+ *  // ... `
+ * })
+ *
+ * on('checkoutCompleted', () => {
+ *  checkoutSpan?.end();
+ * })
+ * ```
+ *
+ * @param span - the span to set active
+ */
+export function setSpanActive(span: Span): void {
+  const maybePreviousActiveSpan = getActiveSpan();
+
+  const scope = getCurrentScope();
+
+  // Putting a small patch onto the span.end method to ensure we
+  // remove the span from the scope when it ends.
+  // eslint-disable-next-line @typescript-eslint/unbound-method
+  span.end = new Proxy(span.end, {
+    apply(target, thisArg, args: Parameters<Span['end']>) {
+      _INTERNAL_setSpanForScope(scope, maybePreviousActiveSpan);
+      return Reflect.apply(target, thisArg, args);
+    },
+  });
+
+  _INTERNAL_setSpanForScope(scope, span);
+}
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
@@ -81,6 +81,7 @@ export {
   spanTimeInputToSeconds,
   updateSpanName,
 } from './utils/spanUtils';
+export { _setSpanForScope as _INTERNAL_setSpanForScope } from './utils/spanOnScope';
 export { parseSampleRate } from './utils/parseSampleRate';
 export { applySdkMetadata } from './utils/sdkMetadata';
 export { getTraceData } from './utils/traceData';
