feat(browser): Add persisted session lifecycle to browserSessionIntegration

Adds `lifecycle: 'session'`, under which one session spans the user's whole
visit: it is persisted in `sessionStorage`, resumed on the next page load, and
rotated once it idles out (30 min) or hits its max duration (8 h). Both bounds
are configurable via `idleTimeout` and `maxDuration`.

`'page'` and `'route'` keep their existing behaviour and `'page'` stays the
default, so nothing changes unless the new lifecycle is opted into.

Author: logaretm

packages/browser/src/integrations/browsersession.ts

@@ -6,9 +6,22 @@ import {
   SEMANTIC_ATTRIBUTE_SESSION_ID,
   startSession,
 } from '@sentry/core/browser';
-import { addHistoryInstrumentationHandler, whenIdleOrHidden } from '@sentry/browser-utils';
+import {
+  addClickKeypressInstrumentationHandler,
+  addHistoryInstrumentationHandler,
+  whenIdleOrHidden,
+} from '@sentry/browser-utils';
 import { DEBUG_BUILD } from '../debug-build';
 import { WINDOW } from '../helpers';
+import type { PersistedSession, SessionExpiryOptions } from '../session/persistence';
+import { getPersistedSession, isSessionExpired, persistSession } from '../session/persistence';
+
+const DEFAULT_IDLE_TIMEOUT = 30 * 60_000;
+const DEFAULT_MAX_DURATION = 8 * 60 * 60_000;
+
+// Writing to sessionStorage on every interaction is wasteful, and a few seconds of
+// staleness is immaterial against timeouts measured in minutes.
+const PERSIST_THROTTLE = 5_000;
 
 interface BrowserSessionOptions {
   /**
@@ -17,10 +30,59 @@ interface BrowserSessionOptions {
    * - `'page'`: A session is created once when the page is loaded. Session is not
    *   updated on navigation. This is the default behavior.
    * - `'route'`: A session is created on page load and on every navigation.
+   * - `'session'`: One session spans the user's whole visit to the site. It is persisted in
+   *   `sessionStorage` and resumed across reloads and navigations until it expires
+   *   (see `idleTimeout` and `maxDuration`).
    *
    * @default 'page'
    */
-  lifecycle?: 'route' | 'page';
+  lifecycle?: 'route' | 'page' | 'session';
+
+  /**
+   * How long the user can be inactive, in milliseconds, before the next interaction starts
+   * a new session. Only applies to the `'session'` lifecycle.
+   *
+   * Activity means the user did something (a click, a key press, a scroll, a navigation).
+   * Telemetry the app emits on its own does not keep a session alive, otherwise a tab left
+   * open in the background would hold one open indefinitely.
+   *
+   * @default 1_800_000 (30 minutes)
+   */
+  idleTimeout?: number;
+
+  /**
+   * The maximum lifetime of a session in milliseconds, regardless of activity. Only applies
+   * to the `'session'` lifecycle.
+   *
+   * @default 28_800_000 (8 hours)
+   */
+  maxDuration?: number;
+}
+
+/**
+ * Starts a session, resuming @param resume if one was handed over from a previous page load,
+ * and writes it back to `sessionStorage`.
+ */
+function startAndPersistSession(resume?: PersistedSession): PersistedSession {
+  const now = Date.now();
+
+  // `ignoreDuration` stays on: a session now has a meaningful duration, but reporting it would
+  // change what release health's session duration distribution measures, which is out of scope here.
+  const session = startSession(
+    resume
+      ? // `init: false` marks this as an update to an already-counted session rather than a new
+        // one, so resuming across a page load does not inflate release health session counts.
+        { sid: resume.sid, started: resume.started / 1000, init: false, ignoreDuration: true }
+      : { ignoreDuration: true },
+  );
+
+  // The persisted record is kept on the `Date` clock throughout. Session timestamps come from
+  // `performance.timeOrigin`, which is reset for every document, so they are not comparable
+  // across the page loads this record has to survive.
+  const persisted = { sid: session.sid, started: resume ? resume.started : now, lastActivity: now };
+  persistSession(persisted);
+
+  return persisted;
 }
 
 /**
@@ -31,6 +93,10 @@ interface BrowserSessionOptions {
  */
 export const browserSessionIntegration = defineIntegration((options: BrowserSessionOptions = {}) => {
   const lifecycle = options.lifecycle ?? 'page';
+  const expiry: SessionExpiryOptions = {
+    idleTimeout: options.idleTimeout ?? DEFAULT_IDLE_TIMEOUT,
+    maxDuration: options.maxDuration ?? DEFAULT_MAX_DURATION,
+  };
 
   return {
     name: 'BrowserSession' as const,
@@ -41,18 +107,55 @@ export const browserSessionIntegration = defineIntegration((options: BrowserSess
         return;
       }
 
-      // The session duration for browser sessions does not track a meaningful
-      // concept that can be used as a metric.
-      // Automatically captured sessions are akin to page views, and thus we
-      // discard their duration.
-      startSession({ ignoreDuration: true });
-
       // 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;
+
+      if (lifecycle === 'session') {
+        const persisted = getPersistedSession();
+        const now = Date.now();
+        let current = startAndPersistSession(
+          persisted && !isSessionExpired(persisted, expiry, now) ? persisted : undefined,
+        );
+        let lastPersistedAt = current.lastActivity;
+
+        const onActivity = (): void => {
+          const activityAt = Date.now();
+
+          if (isSessionExpired(current, expiry, activityAt)) {
+            current = startAndPersistSession();
+            lastPersistedAt = current.lastActivity;
+            captureSession();
+            // A session has now been sent, so the deferred initial capture (if still pending)
+            // must not re-send this session.
+            initialSessionSent = true;
+            return;
+          }
+
+          current.lastActivity = activityAt;
+          if (activityAt - lastPersistedAt > PERSIST_THROTTLE) {
+            persistSession(current);
+            lastPersistedAt = activityAt;
+          }
+        };
+
+        // Clicks and key presses are already instrumented for breadcrumbs, so subscribing here
+        // adds no additional listeners in the common case.
+        addClickKeypressInstrumentationHandler(onActivity);
+        addHistoryInstrumentationHandler(onActivity);
+        // Scroll does not bubble, so it has to be caught on the way down.
+        WINDOW.document.addEventListener('scroll', onActivity, { capture: true, passive: true });
+      } else {
+        // The session duration for browser sessions does not track a meaningful
+        // concept that can be used as a metric.
+        // Automatically captured sessions are akin to page views, and thus we
+        // discard their duration.
+        startSession({ ignoreDuration: true });
+      }
+
       whenIdleOrHidden(() => {
         // A navigation (in `'route'` lifecycle) may start and send a new session before this
         // deferred callback fires. In that case the current session was already sent, so

packages/browser/src/session/persistence.ts

@@ -0,0 +1,58 @@
+import { debug } from '@sentry/core/browser';
+import { DEBUG_BUILD } from '../debug-build';
+import { WINDOW } from '../helpers';
+
+export const SESSION_STORAGE_KEY = 'sentry_session';
+
+/**
+ * The subset of a session we need to resume it on a later page load. Timestamps are
+ * in milliseconds, unlike the seconds-based timestamps on the session itself.
+ */
+export interface PersistedSession {
+  sid: string;
+  started: number;
+  lastActivity: number;
+}
+
+export interface SessionExpiryOptions {
+  idleTimeout: number;
+  maxDuration: number;
+}
+
+/**
+ * Reads the persisted session of the current browsing context, if there is one.
+ */
+export function getPersistedSession(): PersistedSession | undefined {
+  try {
+    const persisted = WINDOW.sessionStorage?.getItem(SESSION_STORAGE_KEY);
+    // @ts-expect-error - intentionally risking JSON.parse throwing when persisted is null to save bundle size
+    const session = JSON.parse(persisted) as PersistedSession;
+    return session.sid ? session : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Persists @param session so that the next page load in this browsing context can resume it.
+ */
+export function persistSession(session: PersistedSession): void {
+  try {
+    WINDOW.sessionStorage.setItem(SESSION_STORAGE_KEY, JSON.stringify(session));
+  } catch (e) {
+    // Ignore potential errors (e.g. if sessionStorage is not available)
+    DEBUG_BUILD && debug.warn('Could not persist session in sessionStorage', e);
+  }
+}
+
+/**
+ * Whether @param session has run past either of its lifetime bounds and a new session
+ * should be started in its place.
+ */
+export function isSessionExpired(
+  session: PersistedSession,
+  { idleTimeout, maxDuration }: SessionExpiryOptions,
+  now: number,
+): boolean {
+  return now - session.lastActivity > idleTimeout || now - session.started > maxDuration;
+}