feat(browser): Add option to explicitly end pageload span via reportPageLoaded()

dev-packages/browser-integration-tests/suites/tracing/browserTracingIntegration/reportPageLoaded/default/init.js

@@ -0,0 +1,15 @@
+import * as Sentry from '@sentry/browser';
+
+window.Sentry = Sentry;
+window._testBaseTimestamp = performance.timeOrigin / 1000;
+
+Sentry.init({
+  dsn: 'https://[email protected]/1337',
+  integrations: [Sentry.browserTracingIntegration({ explicitPageloadEnd: true })],
+  tracesSampleRate: 1,
+  debug: true,
+});
+
+setTimeout(() => {
+  Sentry.reportPageLoaded();
+}, 2500);

dev-packages/browser-integration-tests/suites/tracing/browserTracingIntegration/reportPageLoaded/default/test.ts

@@ -0,0 +1,42 @@
+import { expect } from '@playwright/test';
+import {
+  SEMANTIC_ATTRIBUTE_SENTRY_OP,
+  SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
+  SEMANTIC_ATTRIBUTE_SENTRY_SAMPLE_RATE,
+  SEMANTIC_ATTRIBUTE_SENTRY_SOURCE,
+} from '@sentry/browser';
+import { sentryTest } from '../../../../../utils/fixtures';
+import { envelopeRequestParser, shouldSkipTracingTest, waitForTransactionRequest } from '../../../../../utils/helpers';
+
+sentryTest(
+  'waits for Sentry.reportPageLoaded() to be called when `explicitPageloadEnd` is true',
+  async ({ getLocalTestUrl, page }) => {
+    if (shouldSkipTracingTest()) {
+      sentryTest.skip();
+    }
+
+    const pageloadEventPromise = waitForTransactionRequest(page, event => event.contexts?.trace?.op === 'pageload');
+
+    const url = await getLocalTestUrl({ testDir: __dirname });
+
+    await page.goto(url);
+
+    const eventData = envelopeRequestParser(await pageloadEventPromise);
+
+    const traceContextData = eventData.contexts?.trace?.data;
+    const spanDurationSeconds = eventData.timestamp! - eventData.start_timestamp!;
+
+    expect(traceContextData).toMatchObject({
+      [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.pageload.browser',
+      [SEMANTIC_ATTRIBUTE_SENTRY_SAMPLE_RATE]: 1,
+      [SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: 'url',
+      [SEMANTIC_ATTRIBUTE_SENTRY_OP]: 'pageload',
+      ['sentry.idle_span_finish_reason']: 'reportPageLoaded',
+    });
+
+    // We wait for 2.5 seconds before calling Sentry.reportPageLoaded()
+    // the margins are to account for timing weirdness in CI to avoid flakes
+    expect(spanDurationSeconds).toBeGreaterThan(2);
+    expect(spanDurationSeconds).toBeLessThan(3);
+  },
+);

dev-packages/browser-integration-tests/suites/tracing/browserTracingIntegration/reportPageLoaded/finalTimeout/init.js

@@ -0,0 +1,13 @@
+import * as Sentry from '@sentry/browser';
+
+window.Sentry = Sentry;
+window._testBaseTimestamp = performance.timeOrigin / 1000;
+
+Sentry.init({
+  dsn: 'https://[email protected]/1337',
+  integrations: [Sentry.browserTracingIntegration({ explicitPageloadEnd: true, finalTimeout: 3000 })],
+  tracesSampleRate: 1,
+  debug: true,
+});
+
+// not calling Sentry.reportPageLoaded() on purpose!

dev-packages/browser-integration-tests/suites/tracing/browserTracingIntegration/reportPageLoaded/finalTimeout/test.ts

@@ -0,0 +1,42 @@
+import { expect } from '@playwright/test';
+import {
+  SEMANTIC_ATTRIBUTE_SENTRY_OP,
+  SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
+  SEMANTIC_ATTRIBUTE_SENTRY_SAMPLE_RATE,
+  SEMANTIC_ATTRIBUTE_SENTRY_SOURCE,
+} from '@sentry/browser';
+import { sentryTest } from '../../../../../utils/fixtures';
+import { envelopeRequestParser, shouldSkipTracingTest, waitForTransactionRequest } from '../../../../../utils/helpers';
+
+sentryTest(
+  'final timeout cancels the pageload span even if `explicitPageloadEnd` is true',
+  async ({ getLocalTestUrl, page }) => {
+    if (shouldSkipTracingTest()) {
+      sentryTest.skip();
+    }
+
+    const pageloadEventPromise = waitForTransactionRequest(page, event => event.contexts?.trace?.op === 'pageload');
+
+    const url = await getLocalTestUrl({ testDir: __dirname });
+
+    await page.goto(url);
+
+    const eventData = envelopeRequestParser(await pageloadEventPromise);
+
+    const traceContextData = eventData.contexts?.trace?.data;
+    const spanDurationSeconds = eventData.timestamp! - eventData.start_timestamp!;
+
+    expect(traceContextData).toMatchObject({
+      [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.pageload.browser',
+      [SEMANTIC_ATTRIBUTE_SENTRY_SAMPLE_RATE]: 1,
+      [SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: 'url',
+      [SEMANTIC_ATTRIBUTE_SENTRY_OP]: 'pageload',
+      ['sentry.idle_span_finish_reason']: 'finalTimeout',
+    });
+
+    // We wait for 3 seconds before calling Sentry.reportPageLoaded()
+    // the margins are to account for timing weirdness in CI to avoid flakes
+    expect(spanDurationSeconds).toBeGreaterThan(2.5);
+    expect(spanDurationSeconds).toBeLessThan(3.5);
+  },
+);

dev-packages/browser-integration-tests/suites/tracing/browserTracingIntegration/reportPageLoaded/navigation/init.js

@@ -0,0 +1,19 @@
+import * as Sentry from '@sentry/browser';
+
+window.Sentry = Sentry;
+window._testBaseTimestamp = performance.timeOrigin / 1000;
+
+Sentry.init({
+  dsn: 'https://[email protected]/1337',
+  integrations: [Sentry.browserTracingIntegration({ explicitPageloadEnd: true, instrumentNavigation: false })],
+  tracesSampleRate: 1,
+  debug: true,
+});
+
+setTimeout(() => {
+  Sentry.startBrowserTracingNavigationSpan(Sentry.getClient(), { name: 'custom_navigation' });
+}, 1000);
+
+setTimeout(() => {
+  Sentry.reportPageLoaded();
+}, 2500);

dev-packages/browser-integration-tests/suites/tracing/browserTracingIntegration/reportPageLoaded/navigation/test.ts

@@ -0,0 +1,40 @@
+import { expect } from '@playwright/test';
+import {
+  SEMANTIC_ATTRIBUTE_SENTRY_OP,
+  SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
+  SEMANTIC_ATTRIBUTE_SENTRY_SAMPLE_RATE,
+  SEMANTIC_ATTRIBUTE_SENTRY_SOURCE,
+} from '@sentry/browser';
+import { sentryTest } from '../../../../../utils/fixtures';
+import { envelopeRequestParser, shouldSkipTracingTest, waitForTransactionRequest } from '../../../../../utils/helpers';
+
+sentryTest(
+  'starting a navigation span cancels the pageload span even if `explicitPageloadEnd` is true',
+  async ({ getLocalTestUrl, page }) => {
+    if (shouldSkipTracingTest()) {
+      sentryTest.skip();
+    }
+
+    const pageloadEventPromise = waitForTransactionRequest(page, event => event.contexts?.trace?.op === 'pageload');
+
+    const url = await getLocalTestUrl({ testDir: __dirname });
+
+    await page.goto(url);
+
+    const eventData = envelopeRequestParser(await pageloadEventPromise);
+
+    const traceContextData = eventData.contexts?.trace?.data;
+    const spanDurationSeconds = eventData.timestamp! - eventData.start_timestamp!;
+
+    expect(traceContextData).toMatchObject({
+      [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.pageload.browser',
+      [SEMANTIC_ATTRIBUTE_SENTRY_SAMPLE_RATE]: 1,
+      [SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: 'url',
+      [SEMANTIC_ATTRIBUTE_SENTRY_OP]: 'pageload',
+      ['sentry.idle_span_finish_reason']: 'cancelled',
+    });
+
+    // ending span after 1s but adding a margin of 0.5s to account for timing weirdness in CI to avoid flakes
+    expect(spanDurationSeconds).toBeLessThan(1.5);
+  },
+);

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

@@ -21,6 +21,7 @@ export {
   browserTracingIntegration,
   startBrowserTracingNavigationSpan,
   startBrowserTracingPageLoadSpan,
+  reportPageLoaded,
 } from './tracing/browserTracingIntegration';
 
 export { getFeedback, sendFeedback } from '@sentry-internal/feedback';

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

@@ -21,6 +21,7 @@ export {
   browserTracingIntegration,
   startBrowserTracingNavigationSpan,
   startBrowserTracingPageLoadSpan,
+  reportPageLoaded,
 } from './tracing/browserTracingIntegration';
 export { feedbackIntegrationShim as feedbackAsyncIntegration, feedbackIntegrationShim as feedbackIntegration };
 

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

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

packages/browser/src/index.ts

@@ -41,6 +41,7 @@ export {
   browserTracingIntegration,
   startBrowserTracingNavigationSpan,
   startBrowserTracingPageLoadSpan,
+  reportPageLoaded,
 } from './tracing/browserTracingIntegration';
 export type { RequestInstrumentationOptions } from './tracing/request';
 export {

packages/browser/src/tracing/browserTracingIntegration.ts

@@ -250,6 +250,23 @@ export interface BrowserTracingOptions {
    */
   consistentTraceSampling: boolean;
 
+  /**
+   * If set to `true`, the pageload span will not end itself automatically, unless it
+   * runs until the {@link BrowserTracingOptions.finalTimeout} (30 seconds by default) is reached.
+   *
+   * Set this option to `true`, if you want full control over the pageload span duration.
+   * You can use `Sentry.reportPageLoaded()` to manually end the pageload span whenever convenient.
+   * Be aware that you have to ensure that this is always called, regardless of the chosen route
+   * or path in the application.
+   *
+   * @default `false`. By default, the pageload span will end itself automatically, based on
+   * the {@link BrowserTracingOptions.finalTimeout}, {@link BrowserTracingOptions.idleTimeout}
+   * and {@link BrowserTracingOptions.childSpanTimeout}. This is more convenient to use but means
+   * that the pageload duration can be arbitrary and might not be fully representative of a perceived
+   * page load time.
+   */
+  explicitPageloadEnd: boolean;
+
   /**
    * _experiments allows the user to send options to define how this integration works.
    *
@@ -297,6 +314,7 @@ const DEFAULT_BROWSER_TRACING_OPTIONS: BrowserTracingOptions = {
   detectRedirects: true,
   linkPreviousTrace: 'in-memory',
   consistentTraceSampling: false,
+  explicitPageloadEnd: false,
   _experiments: {},
   ...defaultRequestInstrumentationOptions,
 };
@@ -310,7 +328,7 @@ const DEFAULT_BROWSER_TRACING_OPTIONS: BrowserTracingOptions = {
  *
  * We explicitly export the proper type here, as this has to be extended in some cases.
  */
-export const browserTracingIntegration = ((_options: Partial<BrowserTracingOptions> = {}) => {
+export const browserTracingIntegration = ((options: Partial<BrowserTracingOptions> = {}) => {
   const latestRoute: RouteInfo = {
     name: undefined,
     source: undefined,
@@ -345,18 +363,21 @@ export const browserTracingIntegration = ((_options: Partial<BrowserTracingOptio
     detectRedirects,
     linkPreviousTrace,
     consistentTraceSampling,
+    explicitPageloadEnd,
     onRequestSpanStart,
   } = {
     ...DEFAULT_BROWSER_TRACING_OPTIONS,
-    ..._options,
+    ...options,
   };
 
   let _collectWebVitals: undefined | (() => void);
   let lastInteractionTimestamp: number | undefined;
 
+  let _pageloadSpan: Span | undefined;
+
   /** Create routing idle transaction. */
   function _createRouteSpan(client: Client, startSpanOptions: StartSpanOptions, makeActive = true): void {
-    const isPageloadTransaction = startSpanOptions.op === 'pageload';
+    const isPageloadSpan = startSpanOptions.op === 'pageload';
 
     const initialSpanName = startSpanOptions.name;
     const finalStartSpanOptions: StartSpanOptions = beforeStartSpan
@@ -390,7 +411,7 @@ export const browserTracingIntegration = ((_options: Partial<BrowserTracingOptio
       finalTimeout,
       childSpanTimeout,
       // should wait for finish signal if it's a pageload transaction
-      disableAutoFinish: isPageloadTransaction,
+      disableAutoFinish: isPageloadSpan,
       beforeSpanEnd: span => {
         // This will generally always be defined here, because it is set in `setup()` of the integration
         // but technically, it is optional, so we guard here to be extra safe
@@ -415,9 +436,19 @@ export const browserTracingIntegration = ((_options: Partial<BrowserTracingOptio
           sampled: spanIsSampled(idleSpan),
           dsc: getDynamicSamplingContextFromSpan(span),
         });
+
+        if (isPageloadSpan) {
+          // clean up the stored pageload span on the intergration.
+          _pageloadSpan = undefined;
+        }
       },
+      trimIdleSpanEndTimestamp: !explicitPageloadEnd,
     });
 
+    if (isPageloadSpan && explicitPageloadEnd) {
+      _pageloadSpan = idleSpan;
+    }
+
     setActiveIdleSpan(client, idleSpan);
 
     function emitFinish(): void {
@@ -426,7 +457,8 @@ export const browserTracingIntegration = ((_options: Partial<BrowserTracingOptio
       }
     }
 
-    if (isPageloadTransaction && optionalWindowDocument) {
+    // Enable auto finish of the pageload span if users are not explicitly ending it
+    if (isPageloadSpan && !explicitPageloadEnd && optionalWindowDocument) {
       optionalWindowDocument.addEventListener('readystatechange', () => {
         emitFinish();
       });
@@ -573,7 +605,15 @@ export const browserTracingIntegration = ((_options: Partial<BrowserTracingOptio
           ...startSpanOptions,
         });
       });
+
+      client.on('endPageloadSpan', () => {
+        if (explicitPageloadEnd && _pageloadSpan) {
+          _pageloadSpan.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_IDLE_SPAN_FINISH_REASON, 'reportPageLoaded');
+          _pageloadSpan.end();
+        }
+      });
     },
+
     afterAllSetup(client) {
       let startingUrl: string | undefined = getLocationHref();
 
@@ -723,6 +763,21 @@ export function getMetaContent(metaName: string): string | undefined {
   return metaTag?.getAttribute('content') || undefined;
 }
 
+/**
+ * Manually report the end of the page load, resulting in the SDK ending the pageload span.
+ * This only works if {@link BrowserTracingOptions.explicitPageloadEnd} is set to `true`.
+ * Otherwise, the pageload span will end itself based on the {@link BrowserTracingOptions.finalTimeout},
+ * {@link BrowserTracingOptions.idleTimeout} and {@link BrowserTracingOptions.childSpanTimeout}.
+ *
+ * @param client - The client to use. If not provided, the global client will be used.
+ */
+export function reportPageLoaded(client?: Client): void {
+  const clientToUse = client ?? getClient();
+  if (clientToUse) {
+    clientToUse.emit('endPageloadSpan');
+  }
+}
+
 /** Start listener for interaction transactions */
 function registerInteractionListener(
   client: Client,

packages/core/src/client.ts

@@ -606,6 +606,12 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
     ) => void,
   ): () => void;
 
+  /**
+   * A hook for the browser tracing integrations to trigger the end of a page load span.
+   * @returns {() => void} A function that, when executed, removes the registered callback.
+   */
+  public on(hook: 'endPageloadSpan', callback: () => void): () => void;
+
   /**
    * A hook for the browser tracing integrations to trigger after the pageload span was started.
    * @returns {() => void} A function that, when executed, removes the registered callback.
@@ -800,6 +806,11 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
     traceOptions?: { sentryTrace?: string | undefined; baggage?: string | undefined },
   ): void;
 
+  /**
+   * Emit a hook event for browser tracing integrations to trigger the end of a page load span.
+   */
+  public emit(hook: 'endPageloadSpan'): void;
+
   /**
    * Emit a hook event for browser tracing integrations to trigger aafter the pageload span was started.
    */