From 92a176a34feb90680520bd567ce0137ed277185a Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Mon, 22 Sep 2025 16:07:35 +0200 Subject: [PATCH 1/3] feat(js): Add `reportPageLoaded()` documentation --- docs/platforms/javascript/common/apis.mdx | 33 +++++++++++++++++++ .../automatic-instrumentation.mdx | 7 ++++ src/components/sdkApi.tsx | 10 ++++-- 3 files changed, 47 insertions(+), 3 deletions(-) diff --git a/docs/platforms/javascript/common/apis.mdx b/docs/platforms/javascript/common/apis.mdx index 2aab62f2e5b69..dc94a3e46383e 100644 --- a/docs/platforms/javascript/common/apis.mdx +++ b/docs/platforms/javascript/common/apis.mdx @@ -712,6 +712,39 @@ See Tracing Instrumentation + + + Signals to the Sentry SDK that the initial page was fully loaded. + Requires the `enableReportPageLoaded` option in `browserTracingIntegration` to + be set to `true`. Once called, the SDK ends the pageload span explicitly. + By default, the SDK takes care of ending the pageload span automatically, based on + a period of inactivity where no new child spans are added to the pageload trace. + + You can use explicit pageload reporting if the inactivity heuristics of + `browserTracingIntegration` don't work well for your use case. + However, you must ensure that you call `reportPageLoaded` in every situation. + If `reportPageLoaded` is not called, the pageload span will be ended after 30 seconds + or whatever custom value is set on the `finalTimeout` option. + + + + ```javascript + Sentry.init({ + // 1. Enable manual page load reporting: + integrations: [browserTracingIntegration({ enableReportPageLoaded: true })] + }) + + // 2. Whenever you consider the page loaded: + Sentry.reportPageLoaded(); + ``` + + + ## Tracing Utilities These utilities can be used for more advanced tracing use cases. diff --git a/docs/platforms/javascript/common/tracing/instrumentation/automatic-instrumentation.mdx b/docs/platforms/javascript/common/tracing/instrumentation/automatic-instrumentation.mdx index 1b19f192405b1..e5d20bb23f4f4 100644 --- a/docs/platforms/javascript/common/tracing/instrumentation/automatic-instrumentation.mdx +++ b/docs/platforms/javascript/common/tracing/instrumentation/automatic-instrumentation.mdx @@ -131,6 +131,13 @@ This flag enables or disables creation of `pageload` span on first pageload. + + + +This option determines whether the `Sentry.reportPageLoaded()` function is enabled. + + + This option flags pageload/navigation spans when tabs are moved to the background with "cancelled". Because browser background tab timing is not suited for precise measurements of operations and can affect your statistics in nondeterministic ways, we recommend that this option be enabled. diff --git a/src/components/sdkApi.tsx b/src/components/sdkApi.tsx index 9272dd71e4a22..761bd78214465 100644 --- a/src/components/sdkApi.tsx +++ b/src/components/sdkApi.tsx @@ -26,6 +26,7 @@ type Props = { name: string; parameters: ParameterDef[]; signature: string; + availableSince?: string; categorySupported?: PlatformCategory[]; children?: React.ReactNode; language?: string; @@ -35,6 +36,7 @@ export function SdkApi({ name, children, signature, + availableSince, parameters = [], language, categorySupported = [], @@ -51,9 +53,12 @@ export function SdkApi({ {showServerLikeOnly && (
Only available on Server
)} - 
{codeToJsx(signature, lang)}
- + {availableSince && ( +

+ Available Since: {availableSince} +

+ )} {parameters.length ? (
@@ -63,7 +68,6 @@ export function SdkApi({
) : null} - {children} ); From 1c458c886e849a13da3f42de8a81baf81fcd266e Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Wed, 24 Sep 2025 13:09:06 +0200 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Alex Krawiec --- 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 dc94a3e46383e..58d1df2915ed3 100644 --- a/docs/platforms/javascript/common/apis.mdx +++ b/docs/platforms/javascript/common/apis.mdx @@ -721,7 +721,7 @@ See Tracing Instrumentation`enableReportPageLoaded` option in `browserTracingIntegration` to - be set to `true`. Once called, the SDK ends the pageload span explicitly. + be set to `true`. Once called, the SDK ends the pageload span automatically, By default, the SDK takes care of ending the pageload span automatically, based on a period of inactivity where no new child spans are added to the pageload trace. From 299f0481d9e5f9c406e886a8d8143610c32f43e0 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Wed, 24 Sep 2025 13:10:32 +0200 Subject: [PATCH 3/3] Update docs/platforms/javascript/common/apis.mdx --- docs/platforms/javascript/common/apis.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/platforms/javascript/common/apis.mdx b/docs/platforms/javascript/common/apis.mdx index 58d1df2915ed3..1358e506b0023 100644 --- a/docs/platforms/javascript/common/apis.mdx +++ b/docs/platforms/javascript/common/apis.mdx @@ -722,10 +722,10 @@ See Tracing Instrumentation`enableReportPageLoaded` option in `browserTracingIntegration` to be set to `true`. Once called, the SDK ends the pageload span automatically, + By default, the SDK takes care of ending the pageload span automatically, based on a period of inactivity where no new child spans are added to the pageload trace. - - You can use explicit pageload reporting if the inactivity heuristics of + You can alternatively use explicit pageload reporting if the inactivity heuristics of `browserTracingIntegration` don't work well for your use case. However, you must ensure that you call `reportPageLoaded` in every situation. If `reportPageLoaded` is not called, the pageload span will be ended after 30 seconds