@dash0/sdk-web 0.23.0 → 0.25.0

package/dist/modules/transport/index.js

@@ -4,16 +4,32 @@ import { vars } from "../vars";
 import { debug, error, createRateLimiter } from "../utils";
 const logBatcher = newBatcher(sendLogs);
 const spanBatcher = newBatcher(sendSpans);
-let rateLimiter;
-function isRateLimited() {
-    if (!rateLimiter) {
-        rateLimiter = createRateLimiter({
-            maxCallsPerTenMinutes: 4096,
-            maxCallsPerTenSeconds: 128,
-        });
-    }
-    return rateLimiter();
+/**
+ * Returns an `isRateLimited()` check whose limiter is created on first use, so the module can be imported
+ * without touching timers.
+ */
+function lazyRateLimiter(opts) {
+    let limiter;
+    return () => {
+        if (!limiter) {
+            limiter = createRateLimiter(opts);
+        }
+        return limiter();
+    };
 }
+const isRateLimited = lazyRateLimiter({
+    maxCallsPerTenMinutes: 4096,
+    maxCallsPerTenSeconds: 128,
+});
+// 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) {
     if (!vars.isSessionSampled)
         return;
@@ -23,7 +39,24 @@ export function sendLog(log) {
     }
     logBatcher.send(log);
 }
-function sendLogs(logs) {
+/**
+ * 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, opts) {
+    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, opts) {
     send("/v1/logs", {
         resourceLogs: [
             {
@@ -36,7 +69,7 @@ function sendLogs(logs) {
                 ],
             },
         ],
-    }).catch((err) => {
+    }, opts).catch((err) => {
         error("Failed to transmit logs", err);
     });
 }

package/dist/modules/transport/index_test.js

@@ -0,0 +1,73 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+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) => globalThis.setTimeout(...args),
+    clearTimeout: (...args) => globalThis.clearTimeout(...args),
+    setInterval: (...args) => globalThis.setInterval(...args),
+    clearInterval: (...args) => globalThis.clearInterval(...args),
+}));
+function log(seq) {
+    return {
+        timeUnixNano: "1",
+        severityNumber: 9,
+        severityText: "INFO",
+        body: { stringValue: "[]" },
+        attributes: [{ key: "dash0.session_recording.seq", value: { intValue: String(seq) } }],
+    };
+}
+describe("sendSessionRecordingChunk", () => {
+    let mod;
+    let vars;
+    let send;
+    beforeEach(async () => {
+        vi.resetModules();
+        vi.useFakeTimers();
+        mod = await import("./index");
+        vars = (await import("../vars")).vars;
+        send = (await import("./fetch")).send;
+        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/dist/modules/types/session-recording.js

@@ -0,0 +1 @@
+export {};

package/dist/modules/vars.js

@@ -23,6 +23,17 @@ export const 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,
 };