@dash0/sdk-web 0.25.0 → 0.26.0

package/src/instrumentations/session-recording/index.ts

@@ -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 { SessionRecorder, SessionRecordingEvent } from "../../types/session-recording";
@@ -21,9 +22,14 @@ let armed = false;
 let stopRecorder: (() => void) | undefined;
 let chunker: Chunker | undefined;
 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
@@ -32,6 +38,7 @@ let flushingOnLastChance = false;
  */
 export function registerSessionRecorder(r: SessionRecorder): void {
   recorder = r;
+  stoppedByConsumer = false;
   if (armed) {
     start();
   }
@@ -47,6 +54,7 @@ export function registerSessionRecorder(r: SessionRecorder): void {
  */
 export function armSessionRecording(): void {
   armed = true;
+  stoppedByConsumer = false;
   if (vars.sessionRecording.recorder) {
     recorder = vars.sessionRecording.recorder;
   } else if (!recorder) {
@@ -61,6 +69,19 @@ export function armSessionRecording(): void {
 }
 
 export function stopSessionRecording(): void {
+  stoppedByConsumer = true;
+  teardown();
+}
+
+export function isSessionRecording(): boolean {
+  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(): void {
   if (stopRecorder) {
     try {
       stopRecorder();
@@ -73,8 +94,50 @@ export function stopSessionRecording(): void {
   chunker = undefined;
 }
 
-export function isSessionRecording(): boolean {
-  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(): boolean {
+  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(): void {
+  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(): void {
@@ -99,6 +162,14 @@ function start(): void {
     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: RecordingStream = {
     recordingId: generateUniqueId(TRACE_ID_BYTES),
@@ -111,7 +182,9 @@ function start(): void {
     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);
       }
@@ -153,11 +226,11 @@ function start(): void {
   if (!lastChanceRegistered) {
     lastChanceRegistered = true;
     onLastChance(() => {
-      flushingOnLastChance = true;
+      flushingWhileDocumentMayEnd = true;
       try {
         chunker?.flush();
       } finally {
-        flushingOnLastChance = false;
+        flushingWhileDocumentMayEnd = false;
       }
     });
   }

package/src/instrumentations/session-recording/index_test.ts

@@ -1,6 +1,6 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { SessionRecorder, SessionRecorderOptions } from "../../types/session-recording";
-import { win } from "../../utils";
+import { doc, win } from "../../utils";
 
 vi.mock("../../transport", () => ({
   sendSessionRecordingChunk: vi.fn(),
@@ -270,4 +270,89 @@ 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: DocumentVisibilityState): void {
+      Object.defineProperty(doc!, "visibilityState", { value: state, configurable: true });
+    }
+
+    function setVisibility(state: DocumentVisibilityState): void {
+      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: any) => 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);
+    });
+  });
 });