@dash0/sdk-web 0.24.0 → 0.26.0

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

@@ -0,0 +1,118 @@
+import { setTimeout, clearTimeout } from "../../utils/timers";
+import { SessionRecordingEvent } from "../../types/session-recording";
+
+const RRWEB_EVENT_TYPE_FULL_SNAPSHOT = 2;
+const RRWEB_EVENT_TYPE_META = 4;
+
+export type Chunk = {
+  /**
+   * Zero-based, monotonic within one recording.
+   */
+  seq: number;
+  /**
+   * The rrweb events as a serialized JSON array.
+   */
+  body: string;
+  eventCount: number;
+  hasSnapshot: boolean;
+  /**
+   * Milliseconds since the unix epoch of the first and the last event in the chunk.
+   */
+  startTime: number;
+  endTime: number;
+};
+
+export type ChunkerOptions = {
+  maxBytes: number;
+  maxMillis: number;
+  onChunk: (chunk: Chunk) => void;
+};
+
+export type Chunker = {
+  add(event: SessionRecordingEvent): void;
+  flush(): void;
+  /**
+   * Drops buffered events without emitting a chunk and cancels the pending time-based flush. Used when the
+   * recorder failed to start after it already emitted events, so no stray chunk is transmitted later.
+   */
+  discard(): void;
+};
+
+/**
+ * Buffers rrweb events and hands them out as chunks. A chunk closes when its serialized size reaches
+ * `maxBytes`, when `maxMillis` have passed since its first event, when a new full snapshot begins, or when
+ * `flush()` is called. Events are serialized once, on arrival, so a flush is a join and not a second stringify.
+ */
+export function newChunker(opts: ChunkerOptions): Chunker {
+  let serialized: string[] = [];
+  let byteSize = 0;
+  let hasSnapshot = false;
+  let startTime = 0;
+  let endTime = 0;
+  let seq = 0;
+  let pendingFlushTimeout: ReturnType<typeof setTimeout> | null = null;
+
+  return { add, flush, discard };
+
+  function add(event: SessionRecordingEvent): void {
+    // A Meta event announces a new full snapshot. Close the current chunk first so the snapshot starts a fresh
+    // one and a replay can begin at that chunk.
+    if (event.type === RRWEB_EVENT_TYPE_META && serialized.length > 0) {
+      flush();
+    }
+
+    const json = JSON.stringify(event);
+    if (json == null) return;
+
+    if (serialized.length === 0) {
+      startTime = event.timestamp;
+      pendingFlushTimeout = setTimeout(flush, opts.maxMillis);
+    }
+
+    serialized.push(json);
+    byteSize += json.length;
+    endTime = event.timestamp;
+    if (event.type === RRWEB_EVENT_TYPE_FULL_SNAPSHOT) {
+      hasSnapshot = true;
+    }
+
+    if (byteSize >= opts.maxBytes) {
+      flush();
+    }
+  }
+
+  function discard(): void {
+    clearPendingFlush();
+    serialized = [];
+    byteSize = 0;
+    hasSnapshot = false;
+  }
+
+  function clearPendingFlush(): void {
+    if (pendingFlushTimeout != null) {
+      clearTimeout(pendingFlushTimeout);
+      pendingFlushTimeout = null;
+    }
+  }
+
+  function flush(): void {
+    clearPendingFlush();
+
+    if (serialized.length === 0) return;
+
+    const chunk: Chunk = {
+      seq: seq++,
+      body: "[" + serialized.join(",") + "]",
+      eventCount: serialized.length,
+      hasSnapshot,
+      startTime,
+      endTime,
+    };
+
+    serialized = [];
+    byteSize = 0;
+    hasSnapshot = false;
+
+    opts.onChunk(chunk);
+  }
+}

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

@@ -0,0 +1,147 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { Chunk, newChunker } from "./chunker";
+
+// The SDK's timer wrapper captures window.setTimeout at import time, before vitest installs fake timers.
+// Resolve the globals lazily so vi.useFakeTimers() takes effect.
+vi.mock("../../utils/timers", () => ({
+  setTimeout: (...args: Parameters<typeof globalThis.setTimeout>) => globalThis.setTimeout(...args),
+  clearTimeout: (...args: Parameters<typeof globalThis.clearTimeout>) => globalThis.clearTimeout(...args),
+}));
+
+const META = 4;
+const FULL_SNAPSHOT = 2;
+const INCREMENTAL = 3;
+
+function event(type: number, timestamp: number, data: unknown = {}) {
+  return { type, timestamp, data };
+}
+
+describe("session recording chunker", () => {
+  let chunks: Chunk[];
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    chunks = [];
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  function create(maxBytes = 10_000, maxMillis = 5000) {
+    return newChunker({ maxBytes, maxMillis, onChunk: (c) => chunks.push(c) });
+  }
+
+  it("does nothing on flush when empty", () => {
+    const chunker = create();
+    chunker.flush();
+    expect(chunks).toEqual([]);
+  });
+
+  it("discards buffered events and the pending time-based flush", () => {
+    const chunker = create();
+    chunker.add(event(META, 1000));
+    chunker.add(event(FULL_SNAPSHOT, 1001));
+
+    chunker.discard();
+    vi.advanceTimersByTime(10_000);
+    expect(chunks).toEqual([]);
+
+    // The chunker stays usable, and the dropped events do not leak into the next chunk.
+    chunker.add(event(INCREMENTAL, 2000));
+    chunker.flush();
+    expect(chunks).toHaveLength(1);
+    expect(chunks[0]!.seq).toBe(0);
+    expect(chunks[0]!.eventCount).toBe(1);
+    expect(chunks[0]!.hasSnapshot).toBe(false);
+  });
+
+  it("flushes on explicit flush with a serialized JSON array body", () => {
+    const chunker = create();
+    chunker.add(event(META, 1000, { href: "http://x" }));
+    chunker.add(event(FULL_SNAPSHOT, 1001));
+    chunker.add(event(INCREMENTAL, 1002));
+    chunker.flush();
+
+    expect(chunks).toHaveLength(1);
+    const chunk = chunks[0]!;
+    expect(chunk.seq).toBe(0);
+    expect(chunk.eventCount).toBe(3);
+    expect(chunk.hasSnapshot).toBe(true);
+    expect(chunk.startTime).toBe(1000);
+    expect(chunk.endTime).toBe(1002);
+    expect(JSON.parse(chunk.body)).toEqual([
+      { type: META, timestamp: 1000, data: { href: "http://x" } },
+      { type: FULL_SNAPSHOT, timestamp: 1001, data: {} },
+      { type: INCREMENTAL, timestamp: 1002, data: {} },
+    ]);
+  });
+
+  it("flushes when maxMillis elapse after the first event", () => {
+    const chunker = create(10_000, 5000);
+    chunker.add(event(INCREMENTAL, 1));
+    vi.advanceTimersByTime(4999);
+    expect(chunks).toHaveLength(0);
+    chunker.add(event(INCREMENTAL, 2));
+    vi.advanceTimersByTime(1);
+    expect(chunks).toHaveLength(1);
+    expect(chunks[0]!.eventCount).toBe(2);
+  });
+
+  it("flushes when the serialized size reaches maxBytes", () => {
+    const chunker = create(100, 60_000);
+    const payload = "x".repeat(40);
+    chunker.add(event(INCREMENTAL, 1, payload)); // ~70 bytes
+    expect(chunks).toHaveLength(0);
+    chunker.add(event(INCREMENTAL, 2, payload)); // crosses 100
+    expect(chunks).toHaveLength(1);
+    expect(chunks[0]!.eventCount).toBe(2);
+  });
+
+  it("emits an oversized single event as its own chunk", () => {
+    const chunker = create(50, 60_000);
+    chunker.add(event(FULL_SNAPSHOT, 1, "y".repeat(500)));
+    expect(chunks).toHaveLength(1);
+    expect(chunks[0]!.eventCount).toBe(1);
+    expect(chunks[0]!.hasSnapshot).toBe(true);
+  });
+
+  it("closes the current chunk when a Meta event starts a new snapshot", () => {
+    const chunker = create();
+    chunker.add(event(META, 1));
+    chunker.add(event(FULL_SNAPSHOT, 2));
+    chunker.add(event(INCREMENTAL, 3));
+    expect(chunks).toHaveLength(0);
+
+    chunker.add(event(META, 4));
+    expect(chunks).toHaveLength(1);
+    expect(chunks[0]!.eventCount).toBe(3);
+
+    chunker.add(event(FULL_SNAPSHOT, 5));
+    chunker.flush();
+    expect(chunks).toHaveLength(2);
+    expect(chunks[1]!.eventCount).toBe(2);
+    expect(chunks[1]!.hasSnapshot).toBe(true);
+  });
+
+  it("increments seq across chunks and resets hasSnapshot", () => {
+    const chunker = create();
+    chunker.add(event(FULL_SNAPSHOT, 1));
+    chunker.flush();
+    chunker.add(event(INCREMENTAL, 2));
+    chunker.flush();
+    chunker.add(event(INCREMENTAL, 3));
+    chunker.flush();
+
+    expect(chunks.map((c) => c.seq)).toEqual([0, 1, 2]);
+    expect(chunks.map((c) => c.hasSnapshot)).toEqual([true, false, false]);
+  });
+
+  it("cancels the pending timer on flush so it does not fire twice", () => {
+    const chunker = create(10_000, 1000);
+    chunker.add(event(INCREMENTAL, 1));
+    chunker.flush();
+    vi.advanceTimersByTime(5000);
+    expect(chunks).toHaveLength(1);
+  });
+});

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

@@ -0,0 +1,248 @@
+import { vars } from "../../vars";
+import { sessionId } from "../../api/session";
+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";
+import { Chunker, newChunker } from "./chunker";
+import { buildSessionRecordingLog, RecordingStream } from "./log";
+
+/**
+ * Global set by `dash0-session-recording.iife.js`. Read by `armSessionRecording()` and by
+ * `startSessionRecording()` when called without a recorder.
+ */
+export const GLOBAL_RECORDER_KEY = "dash0Recorder";
+
+let recorder: SessionRecorder | undefined;
+let armed = false;
+let stopRecorder: (() => void) | undefined;
+let chunker: Chunker | undefined;
+let lastChanceRegistered = 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
+ * is registered and `init()` has armed session recording, in either order.
+ */
+export function registerSessionRecorder(r: SessionRecorder): void {
+  recorder = r;
+  stoppedByConsumer = false;
+  if (armed) {
+    start();
+  }
+}
+
+/**
+ * Called from `init()` once configuration is in place and the session is sampled.
+ *
+ * Recorder precedence: `sessionRecording.recorder` from the init options, then a recorder registered through
+ * `startSessionRecording(recorder)`, then `window.dash0Recorder`. The last one is set by
+ * `dash0-session-recording.iife.js`, and is the only handover that works when that script executes before the
+ * initializer snippet has defined the `dash0` command queue.
+ */
+export function armSessionRecording(): void {
+  armed = true;
+  stoppedByConsumer = false;
+  if (vars.sessionRecording.recorder) {
+    recorder = vars.sessionRecording.recorder;
+  } else if (!recorder) {
+    const globalRecorder = (win as any)?.[GLOBAL_RECORDER_KEY];
+    if (typeof globalRecorder === "function") {
+      recorder = globalRecorder as SessionRecorder;
+    }
+  }
+  if (recorder) {
+    start();
+  }
+}
+
+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();
+    } catch (e) {
+      debug("Failed to stop session recorder", e);
+    }
+    stopRecorder = undefined;
+  }
+  chunker?.flush();
+  chunker = undefined;
+}
+
+/**
+ * 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 {
+  if (stopRecorder) {
+    debug("Session recording already running. Ignoring start.");
+    return;
+  }
+  if (!recorder || !win) return;
+
+  const settings = vars.sessionRecording;
+
+  if (!vars.isSessionSampled) {
+    debug("Session is not sampled. Session recording will not start.");
+    return;
+  }
+  if (!isSessionSampledIn(sessionId ?? "", settings.samplingRate ?? 100)) {
+    debug("Session is not sampled for recording. Session recording will not start.");
+    return;
+  }
+  if (isUrlIgnored(win.location.href)) {
+    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: RecordingStream = {
+    recordingId: generateUniqueId(TRACE_ID_BYTES),
+    traceId,
+    spanId: generateSpanId(traceId),
+  };
+
+  const c = newChunker({
+    maxBytes: settings.chunkMaxBytes ?? 48000,
+    maxMillis: settings.chunkMaxMillis ?? 5000,
+    onChunk: (chunk) => {
+      try {
+        sendSessionRecordingChunk(buildSessionRecordingLog(stream, chunk), {
+          compress: !flushingWhileDocumentMayEnd,
+        });
+      } catch (e) {
+        warn("Failed to transmit session recording chunk", e);
+      }
+    },
+  });
+  chunker = c;
+
+  try {
+    stopRecorder = recorder({
+      // rrweb can still emit after its stop function ran (trailing throttle timers), and a recorder that failed
+      // to start may have emitted already. Only accept events while this chunker is the active one.
+      emit: (event: SessionRecordingEvent) => {
+        if (chunker === c) c.add(event);
+      },
+      checkoutEveryNms: settings.checkoutEveryNms,
+      maskAllInputs: settings.maskAllInputs,
+      maskTextClass: settings.maskTextClass,
+      maskTextSelector: settings.maskTextSelector,
+      maskInputFn: settings.maskInputFn,
+      maskTextFn: settings.maskTextFn,
+      blockClass: settings.blockClass,
+      blockSelector: settings.blockSelector,
+      recordCanvas: settings.recordCanvas,
+      collectFonts: settings.collectFonts,
+    });
+  } catch (e) {
+    warn("Failed to start session recorder", e);
+    abandonChunker(c);
+    return;
+  }
+
+  if (!stopRecorder) {
+    // rrweb returns undefined when it refuses to record, e.g. in an unsupported environment.
+    warn("Session recorder did not start.");
+    abandonChunker(c);
+    return;
+  }
+
+  if (!lastChanceRegistered) {
+    lastChanceRegistered = true;
+    onLastChance(() => {
+      flushingWhileDocumentMayEnd = true;
+      try {
+        chunker?.flush();
+      } finally {
+        flushingWhileDocumentMayEnd = false;
+      }
+    });
+  }
+
+  debug("Session recording started", stream);
+}
+
+/**
+ * The recorder did not start, but it may already have emitted events into `c` and armed its flush timer. Drop
+ * them so no chunk of a stream that never started is transmitted later.
+ */
+function abandonChunker(c: Chunker): void {
+  c.discard();
+  chunker = undefined;
+}