From a79d6f6d20219d15653a82540c196cd5c1153380 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Mon, 22 Sep 2025 16:46:41 +0200 Subject: [PATCH 1/5] feat(js): Add documentation for `setSpanActive(span: Span)` --- docs/platforms/javascript/common/apis.mdx | 45 +++++++++++++++++++ .../common/tracing/instrumentation/index.mdx | 25 +++++++++++ 2 files changed, 70 insertions(+) diff --git a/docs/platforms/javascript/common/apis.mdx b/docs/platforms/javascript/common/apis.mdx index 1358e506b0023..251220535d341 100644 --- a/docs/platforms/javascript/common/apis.mdx +++ b/docs/platforms/javascript/common/apis.mdx @@ -636,6 +636,51 @@ See Tracing Instrumentation + + Sets the passed span as the active span on the current scope. + You most likely don't need this functionality but should [use `startActiveSpan`](#startActiveSpan) + instead. + However, in some situations, you might prefer a span being active outside of a callback. + In this case, the combination of [`startInactiveSpan`](#startInactiveSpan) with this function + allows you to start a span, hold a reference to it and keep it active until you end it, without + the active duration being bound to the callback (as opposed to [`startSpanManual`](#startSpanManual)). + + + + ```javascript + let checkoutSpan; + + on('startCheckout', () => { + checkoutSpan = Sentry.startInactiveSpan({name: 'checkout-flow'}); + Sentry.setSpanActive(checkoutSpan); + }) + + doSomeWork(); + + on('endCheckout', () => { + // Ending the span automatically removes it as the active span on the scope + checkoutSpan.end(); + }) + ``` + + +See Tracing Instrumentation for more information on how to work with spans. + + + + + + In some cases, you may need to start an inactive span and make it the active span. + In contrast to [startSpanManual](#starting-an-active-span-with-manual-end-startspanmanual), the period for which + the span is active is not bound to the callback. Instead, it will remain active until you manually end the span. + + ```javascript + let checkoutSpan; + + on('startCheckout', () => { + checkoutSpan = Sentry.startInactiveSpan({name: 'checkout-flow'}); + Sentry.setSpanActive(checkoutSpan); + }) + + doSomeWork(); + + on('endCheckout', () => { + // Ending the span automatically removes it as the active span on the scope + checkoutSpan.end(); + }) + ``` + + + ## Starting Spans as Children of a Specific Span By default, any span that is started will be the child of the currently active span. If you want to have a different behavior, you can force spans to be the children of a specific span with the `parentSpan` option: From 983a17a0391bedcca7f57a73c8dee90481ae4e12 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Mon, 22 Sep 2025 17:51:11 +0200 Subject: [PATCH 2/5] rename and reword --- docs/platforms/javascript/common/apis.mdx | 6 +++--- .../common/tracing/instrumentation/index.mdx | 21 ++++++++++++++----- 2 files changed, 19 insertions(+), 8 deletions(-) diff --git a/docs/platforms/javascript/common/apis.mdx b/docs/platforms/javascript/common/apis.mdx index 251220535d341..2444753ddc1df 100644 --- a/docs/platforms/javascript/common/apis.mdx +++ b/docs/platforms/javascript/common/apis.mdx @@ -637,8 +637,8 @@ See Tracing Instrumentation Tracing Instrumentation { checkoutSpan = Sentry.startInactiveSpan({name: 'checkout-flow'}); - Sentry.setSpanActive(checkoutSpan); + Sentry.setActiveSpanInBrowser(checkoutSpan); }) doSomeWork(); diff --git a/docs/platforms/javascript/common/tracing/instrumentation/index.mdx b/docs/platforms/javascript/common/tracing/instrumentation/index.mdx index 4bc2a49b4fdd9..7825d68acefe1 100644 --- a/docs/platforms/javascript/common/tracing/instrumentation/index.mdx +++ b/docs/platforms/javascript/common/tracing/instrumentation/index.mdx @@ -107,25 +107,36 @@ To add spans that aren't active, you can create independent spans. This is usefu - In some cases, you may need to start an inactive span and make it the active span. - In contrast to [startSpanManual](#starting-an-active-span-with-manual-end-startspanmanual), the period for which - the span is active is not bound to the callback. Instead, it will remain active until you manually end the span. + ### Setting an inactive span active (browser only) + + In browser environments, you might run into use cases, where the callback-based span APIs are not sufficient. + In such cases (see example below), you can use `startInactiveSpan` to start an initially inactive span and then + set it active until you manually end the span. ```javascript let checkoutSpan; on('startCheckout', () => { checkoutSpan = Sentry.startInactiveSpan({name: 'checkout-flow'}); - Sentry.setSpanActive(checkoutSpan); + Sentry.setActiveSpanInBrowser(checkoutSpan); }) doSomeWork(); on('endCheckout', () => { - // Ending the span automatically removes it as the active span on the scope + // Ending the span automatically removes it as the active span checkoutSpan.end(); }) ``` + + Using `startInactiveSpan` in combination with `setActiveSpanInBrowser` allows you to create an inactive span that can be made active until you manually end it. In contrast, [`startSpanManual`](#starting-an-active-span-with-manual-end-startspanmanual) allows you to end the span manually at any point, but it only remains active within the callback. + + + + Note that `setActiveSpanInBrowser` is only available in browser environments! If you're running code in the server + (for example for server-side rendering), make sure to guard this call to only run in the browser. + + From 8ab155cccf9d828ab897f749459feb61b52652f3 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Tue, 23 Sep 2025 11:05:39 +0200 Subject: [PATCH 3/5] Apply suggestions from code review --- docs/platforms/javascript/common/apis.mdx | 2 +- .../javascript/common/tracing/instrumentation/index.mdx | 4 +++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/platforms/javascript/common/apis.mdx b/docs/platforms/javascript/common/apis.mdx index 2444753ddc1df..e951d7f212f33 100644 --- a/docs/platforms/javascript/common/apis.mdx +++ b/docs/platforms/javascript/common/apis.mdx @@ -639,7 +639,7 @@ See Tracing Instrumentation ### Setting an inactive span active (browser only) - + + _Available Since: `10.15.0`_ + In browser environments, you might run into use cases, where the callback-based span APIs are not sufficient. In such cases (see example below), you can use `startInactiveSpan` to start an initially inactive span and then set it active until you manually end the span. From 88d5fa53a8532a8a72860713dd677739ce6b8746 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Wed, 24 Sep 2025 13:01:57 +0200 Subject: [PATCH 4/5] Update docs/platforms/javascript/common/apis.mdx Co-authored-by: Shannon Anahata --- docs/platforms/javascript/common/apis.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/javascript/common/apis.mdx b/docs/platforms/javascript/common/apis.mdx index e951d7f212f33..4a17aa0b61e66 100644 --- a/docs/platforms/javascript/common/apis.mdx +++ b/docs/platforms/javascript/common/apis.mdx @@ -651,7 +651,7 @@ See Tracing Instrumentation Sets the passed span as the active span on the current scope. - You most likely don't need this functionality but should [use `startActiveSpan`](#startActiveSpan) + You most likely don't need this functionality and should [use `startActiveSpan`](#startActiveSpan) instead. However, in some situations, you might prefer a span being active outside of a callback. In this case, the combination of [`startInactiveSpan`](#startInactiveSpan) with this function From e0167110cfbde8fbf37c11ec75e003676ba1b1f4 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Wed, 24 Sep 2025 13:05:19 +0200 Subject: [PATCH 5/5] startActiveSpan is not a thing --- docs/platforms/javascript/common/apis.mdx | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/docs/platforms/javascript/common/apis.mdx b/docs/platforms/javascript/common/apis.mdx index 4a17aa0b61e66..0c22a8482fc8b 100644 --- a/docs/platforms/javascript/common/apis.mdx +++ b/docs/platforms/javascript/common/apis.mdx @@ -641,17 +641,9 @@ See Tracing Instrumentation Sets the passed span as the active span on the current scope. - You most likely don't need this functionality and should [use `startActiveSpan`](#startActiveSpan) + You most likely don't need this functionality and should [use `startSpan`](#startSpan) instead. However, in some situations, you might prefer a span being active outside of a callback. In this case, the combination of [`startInactiveSpan`](#startInactiveSpan) with this function