fix(browser): Defer browser session envelope until browser is idle

Lms24 · Lms24 · commit 8b3ae386a574 · 2026-06-29T14:12:50.000+02:00
diff --git a/dev-packages/browser-integration-tests/suites/sessions/user/subject.js b/dev-packages/browser-integration-tests/suites/sessions/user/subject.js
@@ -1,5 +1,7 @@
-Sentry.setUser({
-  id: '1337',
-  email: 'user@name.com',
-  username: 'user1337',
+document.getElementById('set-user').addEventListener('click', () => {
+  Sentry.setUser({
+    id: '1337',
+    email: 'user@name.com',
+    username: 'user1337',
+  });
 });
diff --git a/dev-packages/browser-integration-tests/suites/sessions/user/template.html b/dev-packages/browser-integration-tests/suites/sessions/user/template.html
@@ -5,5 +5,6 @@
   </head>
   <body>
     <a id="navigate" href="#foo">Navigate</a>
+    <button id="set-user">Set user</button>
   </body>
 </html>
diff --git a/dev-packages/browser-integration-tests/suites/sessions/user/test.ts b/dev-packages/browser-integration-tests/suites/sessions/user/test.ts
@@ -2,15 +2,15 @@ import { expect } from '@playwright/test';
 import { sentryTest } from '../../../utils/fixtures';
 import { waitForSession } from '../../../utils/helpers';
 
-sentryTest('updates the session when setting the user', async ({ getLocalTestUrl, page }) => {
+sentryTest('updates the session when the user is set after the initial session', async ({ getLocalTestUrl, page }) => {
   const initialSessionPromise = waitForSession(page, s => !!s.init && s.status === 'ok');
-  const updatedSessionPromise = waitForSession(page, s => !s.init && s.status === 'ok');
 
   const url = await getLocalTestUrl({ testDir: __dirname });
   await page.goto(url);
 
+  // The initial session envelope is deferred (sent once the browser is idle). At this point
+  // no user has been set yet, so it carries no `did`.
   const initialSession = await initialSessionPromise;
-  const updatedSession = await updatedSessionPromise;
 
   expect(initialSession).toEqual({
     attrs: {
@@ -26,6 +26,12 @@ sentryTest('updates the session when setting the user', async ({ getLocalTestUrl
     timestamp: expect.any(String),
   });
 
+  // Setting the user _after_ the initial session was sent must still be captured as a
+  // dedicated session update carrying the `did`.
+  const updatedSessionPromise = waitForSession(page, s => !s.init && s.status === 'ok');
+  await page.locator('#set-user').click();
+  const updatedSession = await updatedSessionPromise;
+
   expect(updatedSession).toEqual({
     ...initialSession,
     init: false,
@@ -42,6 +48,10 @@ sentryTest('includes the user id in the exited session', async ({ getLocalTestUr
 
   const initialSession = await initialSessionPromise;
 
+  // Set the user after the initial session was sent, then navigate so the (now exited)
+  // initial session carries the `did`.
+  await page.locator('#set-user').click();
+
   const exitedInitialSessionPromise = waitForSession(page, s => !s.init && s.status === 'exited');
 
   await page.locator('#navigate').click();
@@ -79,6 +89,10 @@ sentryTest('includes the user id in the subsequent session', async ({ getLocalTe
     timestamp: expect.any(String),
   });
 
+  // Set the user after the initial session was sent, then navigate so the subsequent
+  // session inherits the `did`.
+  await page.locator('#set-user').click();
+
   const secondSessionPromise = waitForSession(page, s => !!s.init && s.status === 'ok' && s.sid !== initialSession.sid);
 
   await page.locator('#navigate').click();
diff --git a/packages/browser-utils/src/index.ts b/packages/browser-utils/src/index.ts
@@ -25,6 +25,8 @@ export { extractNetworkProtocol } from './metrics/utils';
 
 export { trackClsAsSpan, trackInpAsSpan, trackLcpAsSpan } from './metrics/webVitalSpans';
 
+export { whenIdleOrHidden } from './metrics/web-vitals/lib/whenIdleOrHidden';
+
 export { addClickKeypressInstrumentationHandler } from './instrument/dom';
 
 export { addHistoryInstrumentationHandler } from './instrument/history';
diff --git a/packages/browser/src/integrations/browsersession.ts b/packages/browser/src/integrations/browsersession.ts
@@ -1,5 +1,5 @@
 import { captureSession, debug, defineIntegration, getIsolationScope, startSession } from '@sentry/core/browser';
-import { addHistoryInstrumentationHandler } from '@sentry/browser-utils';
+import { addHistoryInstrumentationHandler, whenIdleOrHidden } from '@sentry/browser-utils';
 import { DEBUG_BUILD } from '../debug-build';
 import { WINDOW } from '../helpers';
 
@@ -41,7 +41,17 @@ export const browserSessionIntegration = defineIntegration((options: BrowserSess
       // Automatically captured sessions are akin to page views, and thus we
       // discard their duration.
       startSession({ ignoreDuration: true });
-      captureSession();
+
+      // Sending the session envelope synchronously in `init()` runs the full send
+      // pipeline during page load, competing with critical resources for the network and
+      // adding overhead that measurably hurts LCP. We defer the initial send until the
+      // browser is idle; `whenIdleOrHidden` flushes it on page-hide so we don't lose short
+      // (page-view-like) sessions.
+      let initialSessionSent = false;
+      whenIdleOrHidden(() => {
+        captureSession();
+        initialSessionSent = true;
+      });
 
       // User data can be set at any time, for example async after Sentry.init has run and the initial session
       // envelope was already sent, but still on the initial page.
@@ -58,9 +68,15 @@ export const browserSessionIntegration = defineIntegration((options: BrowserSess
         const maybeNewUser = scope.getUser();
         // sessions only care about user id and ip address, so we only need to capture the session if the user has changed
         if (previousUser?.id !== maybeNewUser?.id || previousUser?.ip_address !== maybeNewUser?.ip_address) {
-          // the scope class already writes the user to its session, so we only need to capture the session here
-          captureSession();
           previousUser = maybeNewUser;
+          // Only emit a dedicated update envelope for user data that arrives _after_ the
+          // deferred initial session was sent. User data set during page load is already
+          // reflected in that session (the scope writes it onto the session), so capturing
+          // here would send a redundant envelope - and do so during page load, which is
+          // exactly the overhead we're deferring away from.
+          if (initialSessionSent) {
+            captureSession();
+          }
         }
       });
 
