@dash0/sdk-web 0.23.0 → 0.25.0

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

@@ -0,0 +1,60 @@
+import { describe, expect, it, vi } from "vitest";
+import { buildSessionRecordingLog } from "./log";
+import { Chunk } from "./chunker";
+
+vi.mock("../../api/session", () => ({ sessionId: "aabbccdd11223344" }));
+
+describe("session recording log record", () => {
+  const stream = {
+    recordingId: "0123456789abcdef0123456789abcdef",
+    traceId: "d04200aabbccdd112233440123456789",
+    spanId: "0123456789abcdef",
+  };
+
+  const chunk: Chunk = {
+    seq: 3,
+    body: '[{"type":2,"timestamp":1700000000000}]',
+    eventCount: 1,
+    hasSnapshot: true,
+    startTime: 1700000000000,
+    endTime: 1700000004500,
+  };
+
+  it("builds an INFO log record with the chunk body as a string", () => {
+    const log = buildSessionRecordingLog(stream, chunk);
+
+    expect(log.timeUnixNano).toBe("1700000000000000000");
+    expect(log.severityNumber).toBe(9);
+    expect(log.severityText).toBe("INFO");
+    expect(log.body).toEqual({ stringValue: chunk.body });
+    expect(log.traceId).toBe(stream.traceId);
+    expect(log.spanId).toBe(stream.spanId);
+  });
+
+  it("stamps the event name, the stream and the chunk metadata as attributes", () => {
+    const log = buildSessionRecordingLog(stream, chunk);
+
+    expect(log.attributes).toEqual(
+      expect.arrayContaining([
+        { key: "event.name", value: { stringValue: "browser.session_recording" } },
+        { key: "session.id", value: { stringValue: "aabbccdd11223344" } },
+        { key: "dash0.session_recording.id", value: { stringValue: stream.recordingId } },
+        { key: "dash0.session_recording.seq", value: { intValue: "3" } },
+        { key: "dash0.session_recording.event_count", value: { intValue: "1" } },
+        { key: "dash0.session_recording.has_snapshot", value: { boolValue: true } },
+        { key: "dash0.session_recording.end_time_unix_nano", value: { intValue: "1700000004500000000" } },
+      ])
+    );
+  });
+
+  it("keeps the trace and span ids stable across chunks of one stream", () => {
+    const first = buildSessionRecordingLog(stream, chunk);
+    const second = buildSessionRecordingLog(stream, { ...chunk, seq: 4, hasSnapshot: false });
+
+    expect(second.traceId).toBe(first.traceId);
+    expect(second.spanId).toBe(first.spanId);
+    expect(second.attributes).toEqual(
+      expect.arrayContaining([{ key: "dash0.session_recording.has_snapshot", value: { boolValue: false } }])
+    );
+  });
+});

package/src/semantic-conventions.ts

@@ -29,6 +29,13 @@ export const WINDOW_HEIGHT = "browser.window.height";
 export const NETWORK_CONNECTION_TYPE = "network.connection.subtype";
 export const EXCEPTION_COMPONENT_STACK = "exception.component_stack";
 
+// Session Recording Attribute Keys
+export const SESSION_RECORDING_ID = "dash0.session_recording.id";
+export const SESSION_RECORDING_SEQ = "dash0.session_recording.seq";
+export const SESSION_RECORDING_EVENT_COUNT = "dash0.session_recording.event_count";
+export const SESSION_RECORDING_HAS_SNAPSHOT = "dash0.session_recording.has_snapshot";
+export const SESSION_RECORDING_END_TIME_UNIX_NANO = "dash0.session_recording.end_time_unix_nano";
+
 // User Attribute Keys
 export const USER_ID = "user.id";
 export const USER_NAME = "user.name";
@@ -68,6 +75,7 @@ export const EVENT_NAMES = {
   NAVIGATION_TIMING: "browser.navigation_timing",
   WEB_VITAL: "browser.web_vital",
   ERROR: "browser.error",
+  SESSION_RECORDING: "browser.session_recording",
 };
 export const SPAN_EVENT_NAME_EXCEPTION = "exception";
 

package/src/transport/fetch.ts

@@ -9,7 +9,15 @@ const BEACON_BODY_SIZE_LIMIT = 60000;
 let pendingBodySize = 0;
 let pendingRequestCount = 0;
 
-export async function send(path: string, body: unknown): Promise<void> {
+export type SendOptions = {
+  /**
+   * Compress this request regardless of `vars.enableTransportCompression`. Used for payloads that are
+   * large and highly compressible, such as session recording chunks.
+   */
+  compress?: boolean;
+};
+
+export async function send(path: string, body: unknown, opts?: SendOptions): Promise<void> {
   debug("Transmitting telemetry to endpoints", body);
 
   const jsonString = JSON.stringify(body);
@@ -18,7 +26,7 @@ export async function send(path: string, body: unknown): Promise<void> {
   let isCompressed = false;
 
   // Try to compress if supported
-  if (typeof CompressionStream !== "undefined" && vars.enableTransportCompression) {
+  if (typeof CompressionStream !== "undefined" && (vars.enableTransportCompression || opts?.compress)) {
     requestBody = await compressWithGzip(jsonString);
     byteLength = requestBody.byteLength;
     isCompressed = true;

package/src/transport/fetch_test.ts

@@ -334,4 +334,34 @@ describe("fetch transport keepalive handling", () => {
       expect(call[1].keepalive).toBe(true);
     });
   });
+
+  describe("compress option", () => {
+    it("gzips the body when opts.compress is set even though enableTransportCompression is off", async () => {
+      // jsdom's Blob has no stream(); use Node's Blob, which CompressionStream can consume.
+      const { Blob: NodeBlob } = await import("node:buffer");
+      vi.stubGlobal("Blob", NodeBlob);
+      vars.enableTransportCompression = false;
+
+      try {
+        await send("/v1/logs", { data: "x".repeat(1000) }, { compress: true });
+      } finally {
+        vi.unstubAllGlobals();
+      }
+
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+      const init = fetchMock.mock.calls[0]![1];
+      expect(init.headers["Content-Encoding"]).toBe("gzip");
+      expect(init.body).toBeInstanceOf(ArrayBuffer);
+    });
+
+    it("does not gzip without opts.compress when enableTransportCompression is off", async () => {
+      vars.enableTransportCompression = false;
+
+      await send("/v1/logs", { data: "x".repeat(1000) });
+
+      const init = fetchMock.mock.calls[0]![1];
+      expect(init.headers["Content-Encoding"]).toBeUndefined();
+      expect(typeof init.body).toBe("string");
+    });
+  });
 });

package/src/transport/index.ts

@@ -1,5 +1,5 @@
 import { newBatcher } from "./batcher";
-import { send } from "./fetch";
+import { send, SendOptions } from "./fetch";
 import { vars } from "../vars";
 import { debug, error, createRateLimiter } from "../utils";
 import { ExportLogsServiceRequest, ExportTraceServiceRequest, LogRecord, Span } from "../types/otlp";
@@ -7,18 +7,34 @@ import { ExportLogsServiceRequest, ExportTraceServiceRequest, LogRecord, Span }
 const logBatcher = newBatcher<LogRecord>(sendLogs);
 const spanBatcher = newBatcher<Span>(sendSpans);
 
-let rateLimiter: (() => boolean) | undefined;
+/**
+ * Returns an `isRateLimited()` check whose limiter is created on first use, so the module can be imported
+ * without touching timers.
+ */
+function lazyRateLimiter(opts: Parameters<typeof createRateLimiter>[0]): () => boolean {
+  let limiter: (() => boolean) | undefined;
+  return () => {
+    if (!limiter) {
+      limiter = createRateLimiter(opts);
+    }
+    return limiter();
+  };
+}
 
-function isRateLimited() {
-  if (!rateLimiter) {
-    rateLimiter = createRateLimiter({
-      maxCallsPerTenMinutes: 4096,
-      maxCallsPerTenSeconds: 128,
-    });
-  }
+const isRateLimited = lazyRateLimiter({
+  maxCallsPerTenMinutes: 4096,
+  maxCallsPerTenSeconds: 128,
+});
 
-  return rateLimiter();
-}
+// Session recording chunks get their own budget. They are large and periodic, and must neither consume the
+// shared budget of spans and logs nor be starved by it. The budget is deliberately generous: every chunk
+// depends on the ones before it, so a dropped chunk makes the replay unrenderable until the next full snapshot
+// (`checkoutEveryNms`). At the default `chunkMaxBytes` of 48 KB, 64 chunks per 10 s allow a ~3 MB mutation
+// burst (a heavy first render), and 512 per 10 min cap a runaway page at ~25 MB of uncompressed replay JSON.
+const isSessionRecordingRateLimited = lazyRateLimiter({
+  maxCallsPerTenMinutes: 512,
+  maxCallsPerTenSeconds: 64,
+});
 
 export function sendLog(log: LogRecord): void {
   if (!vars.isSessionSampled) return;
@@ -31,20 +47,43 @@ export function sendLog(log: LogRecord): void {
   logBatcher.send(log);
 }
 
-function sendLogs(logs: LogRecord[]): void {
-  send("/v1/logs", {
-    resourceLogs: [
-      {
-        resource: vars.resource,
-        scopeLogs: [
-          {
-            scope: vars.scope,
-            logRecords: logs,
-          },
-        ],
-      },
-    ],
-  } satisfies ExportLogsServiceRequest).catch((err) => {
+/**
+ * Transmits a session recording chunk as a single log record. Chunks bypass the log batcher: batching 15 chunks
+ * of up to `chunkMaxBytes` each would produce requests far beyond the keepalive body limit.
+ *
+ * Chunks are gzipped by default because replay JSON compresses roughly 8:1. Pass `compress: false` when the
+ * request must be issued synchronously, i.e. while the document is being unloaded: compression is asynchronous
+ * and the page may be gone before `fetch()` is ever called.
+ */
+export function sendSessionRecordingChunk(log: LogRecord, opts?: SendOptions): void {
+  if (!vars.isSessionSampled) return;
+
+  if (isSessionRecordingRateLimited()) {
+    debug("Session recording rate limit. Will not send chunk.", log);
+    return;
+  }
+
+  sendLogs([log], { compress: opts?.compress ?? true });
+}
+
+function sendLogs(logs: LogRecord[], opts?: SendOptions): void {
+  send(
+    "/v1/logs",
+    {
+      resourceLogs: [
+        {
+          resource: vars.resource,
+          scopeLogs: [
+            {
+              scope: vars.scope,
+              logRecords: logs,
+            },
+          ],
+        },
+      ],
+    } satisfies ExportLogsServiceRequest,
+    opts
+  ).catch((err) => {
     error("Failed to transmit logs", err);
   });
 }

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,
 };