feat(browser): Add setActiveSpanInBrowser to set an active span in the browser (#17714)

This PR adds a long-requested feature to the browser SDKs (only!):
Making an inactive span active. We do this to enable use cases where
having a span only being active in the callback is not practical (see
#13495 for
examples).

There are a couple of caveats to this feature:
- This on purpose is only exported from the browser SDKs. We cannot
support this in Node, due to OTel not allowing for a similar hack.
Frankly, it also makes no sense in Node-based SDKs.
- Calling `setActiveSpanInBrowser ` on a nested child span, will make
that child span the active span as long as it is active. However, due to
`parentSpanIsAlwaysRootSpan` defaulting to `true` any child span of the
active child span, will still be parented to the root span. By setting
`parentSpanIsAlwaysRootSpan: false`, the span hierarchy is respected and
child spans are correctly parented to the active span. Note that this
cannot be guaranteed to work perfectly, due to missing async context in
the browser. See tests for the `parentSpanIsAlwaysRootSpan` behaviour.
- A span once set active, cannot be set as inactive again. It will
remain active until it is ended or until another span is set active. In
the latter case, once that span ends, the initial span will be set as
active again until it ends. This is reflected in the types where we by
design only allow `Span` to be passed to `setActiveSpanInBrowser `.

Technically, `setActiveSpanInBrowser` uses `_setSpanForScope` which I
decided to re-export from core as `_INTERNAL_setSpanForScope`, similarly
to how we do it with logs APIs.

### Usage

This example shows one of the most frequent use cases where having an
active, callback-unbound span is useful:

```js
function instrumentMyRouter() {
  let routeSpan;
  
  on('routeStart', (from, to) => {
    routeSpan = Sentry.startInactiveSpan({name: `/${from} -> /${to}`});
    Sentry. setActiveSpanInBrowser(rootSpan);
  });


  // any span started in the meantime (e.g. fetch requests) will be
  // automatically parented to `routeSpan`
  
  on('routeEnd', () => {
    // automatically removes the span from the scope
    routeSpan.end();
  })
}
```

closes #13495

Author: Lms24

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://[email protected]/1337',
+  tracesSampleRate: 1,
+});

dev-packages/browser-integration-tests/suites/tracing/setSpanActive/default/subject.js

@@ -0,0 +1,14 @@
+const checkoutSpan = Sentry.startInactiveSpan({ name: 'checkout-flow' });
+Sentry.setActiveSpanInBrowser(checkoutSpan);
+
+Sentry.startSpan({ name: 'checkout-step-1' }, () => {
+  Sentry.startSpan({ name: 'checkout-step-1-1' }, () => {
+    // ... `
+  });
+});
+
+Sentry.startSpan({ name: 'checkout-step-2' }, () => {
+  // ... `
+});
+
+checkoutSpan.end();

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);
+});

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://[email protected]/1337',
+  tracesSampleRate: 1,
+  parentSpanIsAlwaysRootSpan: false,
+});

dev-packages/browser-integration-tests/suites/tracing/setSpanActive/nested-parentAlwaysRoot/subject.js

@@ -0,0 +1,22 @@
+const checkoutSpan = Sentry.startInactiveSpan({ name: 'checkout-flow' });
+Sentry.setActiveSpanInBrowser(checkoutSpan);
+
+Sentry.startSpan({ name: 'checkout-step-1' }, () => {});
+
+const checkoutStep2 = Sentry.startInactiveSpan({ name: 'checkout-step-2' });
+Sentry.setActiveSpanInBrowser(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' }, () => {
+    // ... `
+  });
+});

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 setActiveSpanInBrowser 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);
+  },
+);

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://[email protected]/1337',
+  tracesSampleRate: 1,
+});

dev-packages/browser-integration-tests/suites/tracing/setSpanActive/nested/subject.js

@@ -0,0 +1,22 @@
+const checkoutSpan = Sentry.startInactiveSpan({ name: 'checkout-flow' });
+Sentry.setActiveSpanInBrowser(checkoutSpan);
+
+Sentry.startSpan({ name: 'checkout-step-1' }, () => {});
+
+const checkoutStep2 = Sentry.startInactiveSpan({ name: 'checkout-step-2' });
+Sentry.setActiveSpanInBrowser(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' }, () => {
+    // ... `
+  });
+});

dev-packages/browser-integration-tests/suites/tracing/setSpanActive/nested/test.ts

@@ -0,0 +1,52 @@
+import { expect } from '@playwright/test';
+import { sentryTest } from '../../../../utils/fixtures';
+import { envelopeRequestParser, shouldSkipTracingTest, waitForTransactionRequest } from '../../../../utils/helpers';
+
+sentryTest(
+  'nested calls to setActiveSpanInBrowser 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);
+  },
+);

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

@@ -22,6 +22,7 @@ export {
   startBrowserTracingNavigationSpan,
   startBrowserTracingPageLoadSpan,
 } from './tracing/browserTracingIntegration';
+export { setActiveSpanInBrowser } from './tracing/setActiveSpan';
 
 export { reportPageLoaded } from './tracing/reportPageLoaded';