@dash0/sdk-web 0.24.0 → 0.26.0

package/src/transport/index_test.ts

@@ -0,0 +1,90 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { LogRecord } from "../types/otlp";
+
+vi.mock("./fetch", () => ({
+  send: vi.fn(() => Promise.resolve()),
+}));
+
+// The SDK's timer wrapper captures the window timers at import time, before vitest installs fake timers.
+// Resolve the globals lazily so vi.useFakeTimers() drives the rate limiter's reset intervals.
+vi.mock("../utils/timers", () => ({
+  setTimeout: (...args: Parameters<typeof globalThis.setTimeout>) => globalThis.setTimeout(...args),
+  clearTimeout: (...args: Parameters<typeof globalThis.clearTimeout>) => globalThis.clearTimeout(...args),
+  setInterval: (...args: Parameters<typeof globalThis.setInterval>) => globalThis.setInterval(...args),
+  clearInterval: (...args: Parameters<typeof globalThis.clearInterval>) => globalThis.clearInterval(...args),
+}));
+
+type Module = typeof import("./index");
+
+function log(seq: number): LogRecord {
+  return {
+    timeUnixNano: "1",
+    severityNumber: 9,
+    severityText: "INFO",
+    body: { stringValue: "[]" },
+    attributes: [{ key: "dash0.session_recording.seq", value: { intValue: String(seq) } }],
+  };
+}
+
+describe("sendSessionRecordingChunk", () => {
+  let mod: Module;
+  let vars: typeof import("../vars").vars;
+  let send: ReturnType<typeof vi.fn>;
+
+  beforeEach(async () => {
+    vi.resetModules();
+    vi.useFakeTimers();
+    mod = await import("./index");
+    vars = (await import("../vars")).vars;
+    send = (await import("./fetch")).send as any;
+    send.mockClear();
+    vars.isSessionSampled = true;
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("sends each chunk as its own compressed /v1/logs request, bypassing the log batcher", () => {
+    mod.sendSessionRecordingChunk(log(0));
+    mod.sendSessionRecordingChunk(log(1));
+
+    expect(send).toHaveBeenCalledTimes(2);
+    for (const [path, body, opts] of send.mock.calls) {
+      expect(path).toBe("/v1/logs");
+      expect(body.resourceLogs[0].scopeLogs[0].logRecords).toHaveLength(1);
+      expect(opts).toEqual({ compress: true });
+    }
+  });
+
+  it("sends uncompressed when asked to, so the unload flush reaches fetch synchronously", () => {
+    mod.sendSessionRecordingChunk(log(0), { compress: false });
+
+    expect(send).toHaveBeenCalledTimes(1);
+    expect(send.mock.calls[0]![2]).toEqual({ compress: false });
+  });
+
+  it("does not send when the session is not sampled", () => {
+    vars.isSessionSampled = false;
+    mod.sendSessionRecordingChunk(log(0));
+    expect(send).not.toHaveBeenCalled();
+  });
+
+  it("drops chunks beyond its own burst budget without touching the shared log budget", () => {
+    for (let i = 0; i < 70; i++) {
+      mod.sendSessionRecordingChunk(log(i));
+    }
+    expect(send).toHaveBeenCalledTimes(64);
+
+    // Regular logs are batched, not sent immediately; the point is that they are still accepted.
+    mod.sendLog(log(100));
+    vi.advanceTimersByTime(10_000);
+    const logPaths = send.mock.calls.slice(64).map((c) => c[0]);
+    expect(logPaths).toContain("/v1/logs");
+
+    // The ten-second window has reset, so recording chunks flow again.
+    send.mockClear();
+    mod.sendSessionRecordingChunk(log(71));
+    expect(send).toHaveBeenCalledTimes(1);
+  });
+});

package/src/types/options.ts

@@ -7,7 +7,8 @@ export type InstrumentationName =
   | "@dash0/web-vitals"
   | "@dash0/error"
   | "@dash0/fetch"
-  | "@dash0/xhr";
+  | "@dash0/xhr"
+  | "@dash0/session-recording";
 
 /**
  * VCS (version control) context describing the build the SDK is running
@@ -141,6 +142,7 @@ export type InitOptions = {
     | "headersToCapture"
     | "urlAttributeScrubber"
     | "pageViewInstrumentation"
+    | "sessionRecording"
     | "enableTransportCompression"
   >
 >;

package/src/types/session-recording.ts

@@ -0,0 +1,144 @@
+/**
+ * The subset of rrweb's `record()` option surface the SDK forwards. Declared structurally so the
+ * public API of `@dash0/sdk-web` does not depend on `@rrweb/types`; rrweb's `record` satisfies it.
+ */
+export type SessionRecorderOptions = {
+  /**
+   * Called by the recorder for every rrweb event. `isCheckout` is true for the events that
+   * start a new full snapshot (see `checkoutEveryNms`).
+   */
+  emit: (event: SessionRecordingEvent, isCheckout?: boolean) => void;
+  checkoutEveryNms?: number;
+  maskAllInputs?: boolean;
+  maskTextClass?: string | RegExp;
+  maskTextSelector?: string;
+  maskInputFn?: (text: string, element: HTMLElement | null) => string;
+  maskTextFn?: (text: string, element: HTMLElement | null) => string;
+  blockClass?: string | RegExp;
+  blockSelector?: string;
+  ignoreClass?: string;
+  recordCanvas?: boolean;
+  collectFonts?: boolean;
+  inlineStylesheet?: boolean;
+};
+
+/**
+ * A function that starts recording and returns a function that stops it.
+ * `record` from `@rrweb/record` (re-exported by `@dash0/sdk-web/session-recording`) has this shape.
+ */
+export type SessionRecorder = (options: SessionRecorderOptions) => (() => void) | undefined;
+
+/**
+ * The shape of an rrweb event the SDK relies on. rrweb events carry more data, which the SDK
+ * forwards untouched inside the chunk body.
+ */
+export type SessionRecordingEvent = {
+  /**
+   * rrweb EventType. 2 is FullSnapshot, 4 is Meta.
+   */
+  type: number;
+  /**
+   * Milliseconds since the unix epoch.
+   */
+  timestamp: number;
+  data?: unknown;
+};
+
+export type SessionRecordingSettings = {
+  /**
+   * The percentage of sessions for which a recording is captured. Must be a number between 0 and 100.
+   * The decision is deterministic per session ID and uses the same hash as `sessionSamplingRate`, so
+   * recorded sessions are always a subset of the sessions for which telemetry is transmitted.
+   *
+   * @default 100
+   */
+  samplingRate?: number;
+
+  /**
+   * Replace the value of every visible input, textarea and select with asterisks before it leaves the browser.
+   * `<input type="hidden">` values are element attributes and are not masked; use `blockSelector` for those.
+   * Set to `false` only when you know no form on the page accepts sensitive data.
+   *
+   * @default true
+   */
+  maskAllInputs?: boolean;
+
+  /**
+   * CSS selector for elements whose text content must be masked. Use `"*"` to mask all text on the page.
+   */
+  maskTextSelector?: string;
+
+  /**
+   * Elements with this class have their text content masked.
+   *
+   * @default "dash0-mask"
+   */
+  maskTextClass?: string | RegExp;
+
+  /**
+   * Elements with this class are not recorded at all. A placeholder with the same dimensions
+   * is shown in the replay instead.
+   *
+   * @default "dash0-block"
+   */
+  blockClass?: string | RegExp;
+
+  /**
+   * CSS selector for elements that are not recorded at all.
+   */
+  blockSelector?: string;
+
+  /**
+   * Custom function to mask input values. Receives the raw value and the element, and must return the masked value.
+   */
+  maskInputFn?: (text: string, element: HTMLElement | null) => string;
+
+  /**
+   * Custom function to mask text nodes. Receives the raw text and the parent element, and must return the masked text.
+   */
+  maskTextFn?: (text: string, element: HTMLElement | null) => string;
+
+  /**
+   * Record the content of canvas elements. This is expensive and off by default.
+   *
+   * @default false
+   */
+  recordCanvas?: boolean;
+
+  /**
+   * Collect fonts so the replay renders with the same typefaces. Adds payload size.
+   *
+   * @default false
+   */
+  collectFonts?: boolean;
+
+  /**
+   * The maximum serialized size of one chunk in bytes. When the buffered events reach this size, a chunk is
+   * transmitted. A single rrweb event larger than this (typically a full snapshot) is transmitted on its own.
+   *
+   * @default 48000
+   */
+  chunkMaxBytes?: number;
+
+  /**
+   * The maximum time buffered events wait before they are transmitted as a chunk.
+   *
+   * @default 5000
+   */
+  chunkMaxMillis?: number;
+
+  /**
+   * How often the recorder takes a new full snapshot of the DOM, in milliseconds. A replay can start
+   * from any chunk that contains a full snapshot.
+   *
+   * @default 300000
+   */
+  checkoutEveryNms?: number;
+
+  /**
+   * The recorder to use. Pass `recorder` from `@dash0/sdk-web/session-recording`. When omitted, the SDK waits for
+   * a recorder to be registered through `startSessionRecording(recorder)` or through the
+   * `dash0-session-recording.iife.js` script.
+   */
+  recorder?: SessionRecorder;
+};

package/src/vars.ts

@@ -2,6 +2,7 @@ import { AttributeValueType } from "./utils/otel";
 import { AnyValue, InstrumentationScope, KeyValue, Resource } from "./types/otlp";
 import { UrlAttributeScrubber } from "./attributes";
 import { identity } from "./utils";
+import { SessionRecordingSettings } from "./types/session-recording";
 
 export type PropagatorType = "traceparent" | "xray";
 
@@ -166,6 +167,12 @@ export type Vars = {
 
   pageViewInstrumentation: PageViewInstrumentationSettings;
 
+  /**
+   * Session recording (replay) settings. Recording only starts when a recorder is provided, either through
+   * `sessionRecording.recorder`, `startSessionRecording(recorder)`, or the `dash0-session-recording.iife.js` script.
+   */
+  sessionRecording: SessionRecordingSettings;
+
   /**
    * Enables telemetry transport compression using gzip.
    * experimental - in rare cases causes Chrome to crash to use at your own risk.
@@ -203,6 +210,17 @@ export const vars: Vars = {
     trackVirtualPageViews: true,
     includeParts: [],
   },
+  sessionRecording: {
+    samplingRate: 100,
+    maskAllInputs: true,
+    maskTextClass: "dash0-mask",
+    blockClass: "dash0-block",
+    recordCanvas: false,
+    collectFonts: false,
+    chunkMaxBytes: 48000,
+    chunkMaxMillis: 5000,
+    checkoutEveryNms: 300000,
+  },
   enableTransportCompression: false,
   isSessionSampled: true,
 };