@dash0/sdk-web 0.25.0 → 0.26.0

package/dist/modules/api/session-recording.js

@@ -9,6 +9,11 @@ import { GLOBAL_RECORDER_KEY, registerSessionRecorder, stopSessionRecording as s
  * Recording only starts once `init()` has run with a sampled session. It is safe to call this before `init()`;
  * the recorder is kept and recording starts as soon as the SDK is initialized. The recording is transmitted
  * as `browser.session_recording` log records that share one trace ID, which embeds the session ID.
+ *
+ * Only the visible document is recorded. A tab that is hidden — switched away from, or opened in the
+ * background — stops recording and flushes what it buffered, and starts a fresh recording when it is shown
+ * again. So a session is a sequence of recordings that do not overlap in time, which is what lets the whole
+ * session, tab switches included, be replayed as one.
  */
 export function startSessionRecording(recorder) {
     // The script entrypoint forwards dash0("startSessionRecording", ...) arguments without type checking,
@@ -24,6 +29,9 @@ export function startSessionRecording(recorder) {
 /**
  * Stops the running session recording and transmits any buffered events. Calling this when no recording is
  * running is a no-op.
+ *
+ * Unlike the automatic pause while a tab is hidden, this is final: recording does not resume when the tab
+ * becomes visible again. Call `startSessionRecording()` to record again.
  */
 export function stopSessionRecording() {
     stopRecording();

package/dist/modules/instrumentations/session-recording/index.js

@@ -1,9 +1,10 @@
 import { vars } from "../../vars";
 import { sessionId } from "../../api/session";
-import { debug, generateUniqueId, isSessionSampledIn, TRACE_ID_BYTES, warn, win } from "../../utils";
+import { debug, doc, generateUniqueId, isSessionSampledIn, TRACE_ID_BYTES, warn, win } from "../../utils";
 import { generateTraceId } from "../../utils/trace-id";
 import { generateSpanId } from "../../utils/span-id";
 import { isUrlIgnored } from "../../utils/ignore-rules";
+import { addEventListener } from "../../utils/listeners";
 import { onLastChance } from "../../utils/on-last-chance";
 import { sendSessionRecordingChunk } from "../../transport";
 import { newChunker } from "./chunker";
@@ -18,9 +19,14 @@ let armed = false;
 let stopRecorder;
 let chunker;
 let lastChanceRegistered = false;
-// True while the last-chance handler flushes. The chunk emitted then must be sent uncompressed: gzip is
-// asynchronous, and a document that is being unloaded may never get to the `fetch()` behind the await.
-let flushingOnLastChance = false;
+let visibilityRegistered = false;
+// Set by the public `stopSessionRecording()`, so a visibility change does not resurrect a recording the
+// consumer deliberately ended. Cleared by an explicit start: registering a recorder or arming.
+let stoppedByConsumer = false;
+// True while flushing a document that may not live much longer. The chunk emitted then must be sent
+// uncompressed: gzip is asynchronous, and a document that is being unloaded — or that has just been hidden,
+// and may be unloaded or throttled at any moment — may never get to the `fetch()` behind the await.
+let flushingWhileDocumentMayEnd = false;
 /**
  * Makes a recorder available. Called from the public `startSessionRecording` API, which the
  * `dash0-session-recording.iife.js` script and npm consumers use. Recording starts as soon as both a recorder
@@ -28,6 +34,7 @@ let flushingOnLastChance = false;
  */
 export function registerSessionRecorder(r) {
     recorder = r;
+    stoppedByConsumer = false;
     if (armed) {
         start();
     }
@@ -42,6 +49,7 @@ export function registerSessionRecorder(r) {
  */
 export function armSessionRecording() {
     armed = true;
+    stoppedByConsumer = false;
     if (vars.sessionRecording.recorder) {
         recorder = vars.sessionRecording.recorder;
     }
@@ -56,6 +64,17 @@ export function armSessionRecording() {
     }
 }
 export function stopSessionRecording() {
+    stoppedByConsumer = true;
+    teardown();
+}
+export function isSessionRecording() {
+    return stopRecorder != null;
+}
+/**
+ * Stops the recorder and flushes what it buffered. Shared by the public stop and by the visibility handler,
+ * which differ only in whether the consumer asked for it.
+ */
+function teardown() {
     if (stopRecorder) {
         try {
             stopRecorder();
@@ -68,8 +87,50 @@ export function stopSessionRecording() {
     chunker?.flush();
     chunker = undefined;
 }
-export function isSessionRecording() {
-    return stopRecorder != null;
+/**
+ * Whether the document is not on screen. Treats an absent `visibilityState` as visible, so an environment
+ * without the API records exactly as it did before rather than never recording at all.
+ *
+ * `prerender` counts as hidden: nobody is looking at a prerendered page.
+ */
+function isDocumentHidden() {
+    const state = doc?.visibilityState;
+    return state != null && state !== "visible";
+}
+/**
+ * Recording follows visibility: a hidden tab is torn down and a shown tab starts a new recorder run.
+ *
+ * This is what lets one replayer play a whole session. rrweb's Replayer rebuilds from any full snapshot it
+ * plays through, but each rebuild resets its node-id mirror, so events from a document other than the one
+ * that produced the newest snapshot would address the wrong nodes. Recording only the visible document keeps
+ * the runs of a session from overlapping, so they concatenate into a single coherent stream. `record()` takes
+ * a full snapshot when it starts, so every run opens with one and needs no separate snapshot call.
+ *
+ * Not recording hidden tabs is also why a session stays small: a background tab left open for hours used to
+ * record mutations nobody ever saw.
+ */
+function registerVisibilityHandling() {
+    if (visibilityRegistered || !doc) {
+        return;
+    }
+    visibilityRegistered = true;
+    addEventListener(doc, "visibilitychange", () => {
+        if (isDocumentHidden()) {
+            // Flushed the same way as an unload: a hidden document can be discarded or throttled before an
+            // asynchronous gzip completes.
+            flushingWhileDocumentMayEnd = true;
+            try {
+                teardown();
+            }
+            finally {
+                flushingWhileDocumentMayEnd = false;
+            }
+            return;
+        }
+        if (!stoppedByConsumer) {
+            start();
+        }
+    });
 }
 function start() {
     if (stopRecorder) {
@@ -91,6 +152,13 @@ function start() {
         debug("Page URL is ignored. Session recording will not start.");
         return;
     }
+    registerVisibilityHandling();
+    if (isDocumentHidden()) {
+        // A tab opened in the background — ctrl+click, `target=_blank`, a restored session — must not record
+        // until it is first shown. The listener above starts it then.
+        debug("Document is hidden. Session recording will start once it becomes visible.");
+        return;
+    }
     const traceId = generateTraceId(sessionId);
     const stream = {
         recordingId: generateUniqueId(TRACE_ID_BYTES),
@@ -102,7 +170,9 @@ function start() {
         maxMillis: settings.chunkMaxMillis ?? 5000,
         onChunk: (chunk) => {
             try {
-                sendSessionRecordingChunk(buildSessionRecordingLog(stream, chunk), { compress: !flushingOnLastChance });
+                sendSessionRecordingChunk(buildSessionRecordingLog(stream, chunk), {
+                    compress: !flushingWhileDocumentMayEnd,
+                });
             }
             catch (e) {
                 warn("Failed to transmit session recording chunk", e);
@@ -144,12 +214,12 @@ function start() {
     if (!lastChanceRegistered) {
         lastChanceRegistered = true;
         onLastChance(() => {
-            flushingOnLastChance = true;
+            flushingWhileDocumentMayEnd = true;
             try {
                 chunker?.flush();
             }
             finally {
-                flushingOnLastChance = false;
+                flushingWhileDocumentMayEnd = false;
             }
         });
     }

package/dist/modules/instrumentations/session-recording/index_test.js

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { win } from "../../utils";
+import { doc, win } from "../../utils";
 vi.mock("../../transport", () => ({
     sendSessionRecordingChunk: vi.fn(),
     sendLog: vi.fn(),
@@ -227,4 +227,67 @@ describe("session recording lifecycle", () => {
         expect(sendSessionRecordingChunk).toHaveBeenCalledTimes(1);
         expect(mod.isSessionRecording()).toBe(false);
     });
+    describe("visibility", () => {
+        /**
+         * jsdom's `visibilityState` is a getter on the Document prototype, so it can only be changed by
+         * redefining it. Restored by the `afterEach` below.
+         */
+        function setVisibilityState(state) {
+            Object.defineProperty(doc, "visibilityState", { value: state, configurable: true });
+        }
+        function setVisibility(state) {
+            setVisibilityState(state);
+            doc.dispatchEvent(new Event("visibilitychange"));
+        }
+        afterEach(() => {
+            setVisibilityState("visible");
+        });
+        it("defers the start of a tab that is hidden when recording is armed", () => {
+            setVisibilityState("hidden");
+            mod.armSessionRecording();
+            mod.registerSessionRecorder(recorder);
+            expect(recorder).not.toHaveBeenCalled();
+            expect(mod.isSessionRecording()).toBe(false);
+            setVisibility("visible");
+            expect(recorder).toHaveBeenCalledTimes(1);
+            expect(mod.isSessionRecording()).toBe(true);
+        });
+        it("stops recording while hidden and starts a new run, with a new recording id, when shown again", () => {
+            mod.armSessionRecording();
+            mod.registerSessionRecorder(recorder);
+            capturedOptions.emit({ type: 3, timestamp: 1, data: {} });
+            setVisibility("hidden");
+            expect(stopFn).toHaveBeenCalledTimes(1);
+            expect(mod.isSessionRecording()).toBe(false);
+            // Buffered events are flushed uncompressed: a hidden document may be discarded before an
+            // asynchronous gzip completes.
+            expect(sendSessionRecordingChunk).toHaveBeenCalledTimes(1);
+            expect(sendSessionRecordingChunk.mock.calls[0][1]).toEqual({ compress: false });
+            setVisibility("visible");
+            expect(recorder).toHaveBeenCalledTimes(2);
+            capturedOptions.emit({ type: 3, timestamp: 2, data: {} });
+            vi.advanceTimersByTime(5000);
+            expect(sendSessionRecordingChunk).toHaveBeenCalledTimes(2);
+            // A separate run, so the replay rebuilds from the full snapshot rrweb takes when it starts.
+            const recordingIds = sendSessionRecordingChunk.mock.calls.map((c) => c[0].attributes.find((a) => a.key === "dash0.session_recording.id").value.stringValue);
+            expect(recordingIds[0]).not.toBe(recordingIds[1]);
+        });
+        it("does not resurrect a recording the consumer stopped", () => {
+            mod.armSessionRecording();
+            mod.registerSessionRecorder(recorder);
+            mod.stopSessionRecording();
+            setVisibility("hidden");
+            setVisibility("visible");
+            expect(recorder).toHaveBeenCalledTimes(1);
+            expect(mod.isSessionRecording()).toBe(false);
+        });
+        it("records again after an explicit restart that follows a consumer stop", () => {
+            mod.armSessionRecording();
+            mod.registerSessionRecorder(recorder);
+            mod.stopSessionRecording();
+            mod.registerSessionRecorder(recorder);
+            expect(recorder).toHaveBeenCalledTimes(2);
+            expect(mod.isSessionRecording()).toBe(true);
+        });
+    });
 });