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

[Lms24]

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:

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

[github-actions]

size-limit report 📦

Path	Size	% Change	Change
@sentry/browser	24.26 kB	-	-
@sentry/browser - with treeshaking flags	22.77 kB	-	-
@sentry/browser (incl. Tracing)	40.4 kB	-	-
@sentry/browser (incl. Tracing, Replay)	78.78 kB	-	-
@sentry/browser (incl. Tracing, Replay) - with treeshaking flags	68.44 kB	-	-
@sentry/browser (incl. Tracing, Replay with Canvas)	83.44 kB	-	-
@sentry/browser (incl. Tracing, Replay, Feedback)	95.66 kB	-	-
@sentry/browser (incl. Feedback)	40.97 kB	-	-
@sentry/browser (incl. sendFeedback)	28.91 kB	-	-
@sentry/browser (incl. FeedbackAsync)	33.84 kB	-	-
@sentry/react	25.98 kB	-	-
@sentry/react (incl. Tracing)	42.38 kB	-	-
@sentry/vue	28.78 kB	-	-
@sentry/vue (incl. Tracing)	42.21 kB	-	-
@sentry/svelte	24.29 kB	-	-
CDN Bundle	25.77 kB	-	-
CDN Bundle (incl. Tracing)	40.3 kB	+0.15%	+58 B 🔺
CDN Bundle (incl. Tracing, Replay)	76.52 kB	+0.09%	+65 B 🔺
CDN Bundle (incl. Tracing, Replay, Feedback)	82.02 kB	+0.08%	+62 B 🔺
CDN Bundle - uncompressed	75.37 kB	-	-
CDN Bundle (incl. Tracing) - uncompressed	119.29 kB	+0.14%	+159 B 🔺
CDN Bundle (incl. Tracing, Replay) - uncompressed	234.41 kB	+0.07%	+159 B 🔺
CDN Bundle (incl. Tracing, Replay, Feedback) - uncompressed	247.18 kB	+0.07%	+159 B 🔺
@sentry/nextjs (client)	44.4 kB	-	-
@sentry/sveltekit (client)	40.82 kB	-	-
@sentry/node-core	50.02 kB	-	-
@sentry/node	152.25 kB	-0.01%	-1 B 🔽
@sentry/node - without tracing	91.94 kB	-	-
@sentry/aws-serverless	105.39 kB	-0.01%	-1 B 🔽

View base workflow run

[github-actions]

node-overhead report 🧳

Note: This is a synthetic benchmark with a minimal express app and does not necessarily reflect the real-world performance impact in an application.

Scenario	Requests/s	% of Baseline	Prev. Requests/s	Change %
GET Baseline	9,038	-	9,160	-1%
GET With Sentry	1,425	16%	1,394	+2%
GET With Sentry (error only)	6,096	67%	6,067	+0%
POST Baseline	1,211	-	1,195	+1%
POST With Sentry	528	44%	519	+2%
POST With Sentry (error only)	1,064	88%	1,055	+1%
MYSQL Baseline	3,370	-	3,268	+3%
MYSQL With Sentry	488	14%	454	+7%
MYSQL With Sentry (error only)	2,725	81%	2,645	+3%

View base workflow run

[mydea]

I like it! Only one thing, the name - would it make sense to use a browser-specific naming to make it clearer this only exists there? not 100% sure, but something like:

• Sentry.makeActiveSpanInBrowser(span)
• Sentry.browserSetActiveSpan(span)

or something in this direction? Just wondering because I can see folks writing in "why is this not exported in node" etc 😅

[Lms24]

I like it! Only one thing, the name - would it make sense to use a browser-specific naming to make it clearer this only exists there? not 100% sure, but something like:

• Sentry.makeActiveSpanInBrowser(span)
• Sentry.browserSetActiveSpan(span)

Yeah I get the point. I tried to come up with a name that's less "unergonomic" but it always sounds complicated. But maybe that's a good thing with this API though 😅 . Let's go with Sentry.setActiveSpanInBrowser(span).