@dash0/sdk-web 0.24.0 → 0.26.0

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

@@ -0,0 +1,358 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { SessionRecorder, SessionRecorderOptions } from "../../types/session-recording";
+import { doc, win } from "../../utils";
+
+vi.mock("../../transport", () => ({
+  sendSessionRecordingChunk: vi.fn(),
+  sendLog: vi.fn(),
+  sendSpan: vi.fn(),
+}));
+
+vi.mock("../../api/session", () => ({
+  sessionId: "aabbccdd11223344",
+}));
+
+type Module = typeof import("./index");
+
+describe("session recording lifecycle", () => {
+  let mod: Module;
+  let vars: typeof import("../../vars").vars;
+  let sendSessionRecordingChunk: ReturnType<typeof vi.fn>;
+  let stopFn: ReturnType<typeof vi.fn>;
+  let recorder: ReturnType<typeof vi.fn> & SessionRecorder;
+  let capturedOptions: SessionRecorderOptions | undefined;
+
+  beforeEach(async () => {
+    vi.resetModules();
+    vi.useFakeTimers();
+    mod = await import("./index");
+    vars = (await import("../../vars")).vars;
+    sendSessionRecordingChunk = (await import("../../transport")).sendSessionRecordingChunk as any;
+    sendSessionRecordingChunk.mockClear();
+
+    vars.isSessionSampled = true;
+    vars.ignoreUrls = [];
+    vars.endpoints = [{ url: "https://ingress.example.com", authToken: "x" }];
+    vars.sessionRecording = { ...vars.sessionRecording, samplingRate: 100, recorder: undefined };
+
+    stopFn = vi.fn();
+    capturedOptions = undefined;
+    recorder = vi.fn((opts: SessionRecorderOptions) => {
+      capturedOptions = opts;
+      return stopFn;
+    }) as any;
+  });
+
+  afterEach(() => {
+    mod.stopSessionRecording();
+    vi.useRealTimers();
+  });
+
+  it("does not start before init arms recording", () => {
+    mod.registerSessionRecorder(recorder);
+    expect(recorder).not.toHaveBeenCalled();
+    expect(mod.isSessionRecording()).toBe(false);
+  });
+
+  it("starts when armed after the recorder was registered", () => {
+    mod.registerSessionRecorder(recorder);
+    mod.armSessionRecording();
+    expect(recorder).toHaveBeenCalledTimes(1);
+    expect(mod.isSessionRecording()).toBe(true);
+  });
+
+  it("starts when the recorder is registered after arming", () => {
+    mod.armSessionRecording();
+    expect(recorder).not.toHaveBeenCalled();
+    mod.registerSessionRecorder(recorder);
+    expect(recorder).toHaveBeenCalledTimes(1);
+  });
+
+  it("picks up window.dash0Recorder when arming, so the recorder script may run before the initializer", () => {
+    (win as any).dash0Recorder = recorder;
+    try {
+      mod.armSessionRecording();
+      expect(recorder).toHaveBeenCalledTimes(1);
+      expect(mod.isSessionRecording()).toBe(true);
+    } finally {
+      delete (win as any).dash0Recorder;
+    }
+  });
+
+  it("prefers an explicitly registered recorder over window.dash0Recorder", () => {
+    const globalRecorder = vi.fn(() => vi.fn());
+    (win as any).dash0Recorder = globalRecorder;
+    try {
+      mod.registerSessionRecorder(recorder);
+      mod.armSessionRecording();
+      expect(recorder).toHaveBeenCalledTimes(1);
+      expect(globalRecorder).not.toHaveBeenCalled();
+    } finally {
+      delete (win as any).dash0Recorder;
+    }
+  });
+
+  it("ignores a window.dash0Recorder that is not a function", () => {
+    (win as any).dash0Recorder = "nope";
+    try {
+      mod.armSessionRecording();
+      expect(mod.isSessionRecording()).toBe(false);
+    } finally {
+      delete (win as any).dash0Recorder;
+    }
+  });
+
+  it("uses the recorder from vars.sessionRecording.recorder", () => {
+    vars.sessionRecording.recorder = recorder;
+    mod.armSessionRecording();
+    expect(recorder).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not start twice", () => {
+    mod.armSessionRecording();
+    mod.registerSessionRecorder(recorder);
+    mod.registerSessionRecorder(recorder);
+    mod.armSessionRecording();
+    expect(recorder).toHaveBeenCalledTimes(1);
+  });
+
+  it("forwards privacy settings to the recorder with masking on by default", () => {
+    mod.armSessionRecording();
+    mod.registerSessionRecorder(recorder);
+
+    expect(capturedOptions).toMatchObject({
+      maskAllInputs: true,
+      maskTextClass: "dash0-mask",
+      blockClass: "dash0-block",
+      recordCanvas: false,
+      collectFonts: false,
+      checkoutEveryNms: 300000,
+    });
+    expect(typeof capturedOptions!.emit).toBe("function");
+  });
+
+  it("does not start when the session is not sampled", () => {
+    vars.isSessionSampled = false;
+    mod.armSessionRecording();
+    mod.registerSessionRecorder(recorder);
+    expect(recorder).not.toHaveBeenCalled();
+  });
+
+  it("does not start when the recording sampling rate excludes the session", () => {
+    vars.sessionRecording.samplingRate = 0;
+    mod.armSessionRecording();
+    mod.registerSessionRecorder(recorder);
+    expect(recorder).not.toHaveBeenCalled();
+  });
+
+  it("does not start when the page url is ignored", () => {
+    vars.ignoreUrls = [/localhost/];
+    mod.armSessionRecording();
+    mod.registerSessionRecorder(recorder);
+    expect(recorder).not.toHaveBeenCalled();
+  });
+
+  it("survives a recorder that throws", () => {
+    const throwing = vi.fn(() => {
+      throw new Error("boom");
+    }) as any;
+    mod.armSessionRecording();
+    mod.registerSessionRecorder(throwing);
+    expect(mod.isSessionRecording()).toBe(false);
+  });
+
+  it("discards events emitted by a recorder that then refuses to start", () => {
+    // rrweb emits Meta + FullSnapshot synchronously and returns undefined when it cannot record.
+    const refusing = vi.fn((opts: SessionRecorderOptions) => {
+      opts.emit({ type: 4, timestamp: 1000, data: {} });
+      opts.emit({ type: 2, timestamp: 1001, data: {} });
+      return undefined;
+    }) as any;
+    mod.armSessionRecording();
+    mod.registerSessionRecorder(refusing);
+
+    expect(mod.isSessionRecording()).toBe(false);
+    vi.advanceTimersByTime(10_000);
+    expect(sendSessionRecordingChunk).not.toHaveBeenCalled();
+
+    // stop must be a harmless no-op afterwards
+    expect(() => mod.stopSessionRecording()).not.toThrow();
+    expect(sendSessionRecordingChunk).not.toHaveBeenCalled();
+  });
+
+  it("swallows a stop function that throws and still resets its state", () => {
+    stopFn.mockImplementation(() => {
+      throw new Error("stop failed");
+    });
+    mod.armSessionRecording();
+    mod.registerSessionRecorder(recorder);
+    capturedOptions!.emit({ type: 3, timestamp: 1, data: {} });
+
+    expect(() => mod.stopSessionRecording()).not.toThrow();
+    expect(mod.isSessionRecording()).toBe(false);
+    // buffered events are still flushed
+    expect(sendSessionRecordingChunk).toHaveBeenCalledTimes(1);
+  });
+
+  it("ignores events the recorder emits after stop", () => {
+    mod.armSessionRecording();
+    mod.registerSessionRecorder(recorder);
+    mod.stopSessionRecording();
+    sendSessionRecordingChunk.mockClear();
+
+    // rrweb's trailing throttle timers can still call emit after its stop function ran.
+    capturedOptions!.emit({ type: 3, timestamp: 1, data: {} });
+    vi.advanceTimersByTime(10_000);
+    expect(sendSessionRecordingChunk).not.toHaveBeenCalled();
+  });
+
+  it("compresses periodic chunks but sends the last-chance flush uncompressed", () => {
+    mod.armSessionRecording();
+    mod.registerSessionRecorder(recorder);
+
+    capturedOptions!.emit({ type: 3, timestamp: 1, data: {} });
+    vi.advanceTimersByTime(5000);
+    expect(sendSessionRecordingChunk).toHaveBeenCalledTimes(1);
+    expect(sendSessionRecordingChunk.mock.calls[0]![1]).toEqual({ compress: true });
+
+    capturedOptions!.emit({ type: 3, timestamp: 2, data: {} });
+    globalThis.dispatchEvent(new Event("pagehide"));
+    expect(sendSessionRecordingChunk).toHaveBeenCalledTimes(2);
+    expect(sendSessionRecordingChunk.mock.calls[1]![1]).toEqual({ compress: false });
+
+    // back to normal once the page keeps running
+    capturedOptions!.emit({ type: 3, timestamp: 3, data: {} });
+    vi.advanceTimersByTime(5000);
+    expect(sendSessionRecordingChunk).toHaveBeenCalledTimes(3);
+    expect(sendSessionRecordingChunk.mock.calls[2]![1]).toEqual({ compress: true });
+  });
+
+  it("transmits chunks that share one trace id embedding the session id", () => {
+    mod.armSessionRecording();
+    mod.registerSessionRecorder(recorder);
+
+    capturedOptions!.emit({ type: 4, timestamp: 1000, data: {} });
+    capturedOptions!.emit({ type: 2, timestamp: 1001, data: {} });
+    vi.advanceTimersByTime(5000);
+    capturedOptions!.emit({ type: 3, timestamp: 7000, data: {} });
+    vi.advanceTimersByTime(5000);
+
+    expect(sendSessionRecordingChunk).toHaveBeenCalledTimes(2);
+    const [first, second] = sendSessionRecordingChunk.mock.calls.map((c) => c[0]);
+
+    expect(first.traceId).toMatch(/^d04200aabbccdd11223344[0-9a-f]{10}$/);
+    expect(second.traceId).toBe(first.traceId);
+    expect(second.spanId).toBe(first.spanId);
+    expect(first.attributes).toEqual(
+      expect.arrayContaining([
+        { key: "event.name", value: { stringValue: "browser.session_recording" } },
+        { key: "dash0.session_recording.seq", value: { intValue: "0" } },
+        { key: "dash0.session_recording.has_snapshot", value: { boolValue: true } },
+      ])
+    );
+    expect(second.attributes).toEqual(
+      expect.arrayContaining([
+        { key: "dash0.session_recording.seq", value: { intValue: "1" } },
+        { key: "dash0.session_recording.has_snapshot", value: { boolValue: false } },
+      ])
+    );
+  });
+
+  it("stops the recorder and flushes buffered events on stop", () => {
+    mod.armSessionRecording();
+    mod.registerSessionRecorder(recorder);
+    capturedOptions!.emit({ type: 3, timestamp: 1, data: {} });
+    expect(sendSessionRecordingChunk).not.toHaveBeenCalled();
+
+    mod.stopSessionRecording();
+
+    expect(stopFn).toHaveBeenCalledTimes(1);
+    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);
+    });
+  });
+});

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

@@ -0,0 +1,48 @@
+import { addAttribute } from "../../utils/otel";
+import {
+  EVENT_NAME,
+  EVENT_NAMES,
+  LOG_SEVERITIES,
+  SESSION_RECORDING_END_TIME_UNIX_NANO,
+  SESSION_RECORDING_EVENT_COUNT,
+  SESSION_RECORDING_HAS_SNAPSHOT,
+  SESSION_RECORDING_ID,
+  SESSION_RECORDING_SEQ,
+} from "../../semantic-conventions";
+import { addCommonAttributes } from "../../attributes";
+import { toNanosTs } from "../../utils";
+import { KeyValue, LogRecord } from "../../types/otlp";
+import { Chunk } from "./chunker";
+
+export type RecordingStream = {
+  /**
+   * Identifies one recorder run. All chunks of the run share it.
+   */
+  recordingId: string;
+  /**
+   * Trace context shared by all chunks of the run. The trace ID embeds the session ID.
+   */
+  traceId: string;
+  spanId: string;
+};
+
+export function buildSessionRecordingLog(stream: RecordingStream, chunk: Chunk): LogRecord {
+  const attributes: KeyValue[] = [];
+  addAttribute(attributes, EVENT_NAME, EVENT_NAMES.SESSION_RECORDING);
+  addCommonAttributes(attributes);
+  addAttribute(attributes, SESSION_RECORDING_ID, stream.recordingId);
+  addAttribute(attributes, SESSION_RECORDING_SEQ, { intValue: String(chunk.seq) });
+  addAttribute(attributes, SESSION_RECORDING_EVENT_COUNT, { intValue: String(chunk.eventCount) });
+  addAttribute(attributes, SESSION_RECORDING_HAS_SNAPSHOT, chunk.hasSnapshot);
+  addAttribute(attributes, SESSION_RECORDING_END_TIME_UNIX_NANO, { intValue: toNanosTs(chunk.endTime) });
+
+  return {
+    timeUnixNano: toNanosTs(chunk.startTime),
+    severityNumber: LOG_SEVERITIES.INFO,
+    severityText: "INFO",
+    body: { stringValue: chunk.body },
+    attributes,
+    traceId: stream.traceId,
+    spanId: stream.spanId,
+  };
+}

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