@dash0/sdk-web 0.23.0 → 0.25.0

package/dist/modules/instrumentations/session-recording/chunker_test.js

@@ -0,0 +1,125 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { 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) => globalThis.setTimeout(...args),
+    clearTimeout: (...args) => globalThis.clearTimeout(...args),
+}));
+const META = 4;
+const FULL_SNAPSHOT = 2;
+const INCREMENTAL = 3;
+function event(type, timestamp, data = {}) {
+    return { type, timestamp, data };
+}
+describe("session recording chunker", () => {
+    let chunks;
+    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/dist/modules/instrumentations/session-recording/index.js

@@ -0,0 +1,165 @@
+import { vars } from "../../vars";
+import { sessionId } from "../../api/session";
+import { debug, 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 { onLastChance } from "../../utils/on-last-chance";
+import { sendSessionRecordingChunk } from "../../transport";
+import { newChunker } from "./chunker";
+import { buildSessionRecordingLog } 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;
+let armed = false;
+let stopRecorder;
+let chunker;
+let lastChanceRegistered = false;
+// True while the last-chance handler flushes. The chunk emitted then must be sent uncompressed: gzip is
+// asynchronous, and a document that is being unloaded may never get to the `fetch()` behind the await.
+let flushingOnLastChance = 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) {
+    recorder = r;
+    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() {
+    armed = true;
+    if (vars.sessionRecording.recorder) {
+        recorder = vars.sessionRecording.recorder;
+    }
+    else if (!recorder) {
+        const globalRecorder = win?.[GLOBAL_RECORDER_KEY];
+        if (typeof globalRecorder === "function") {
+            recorder = globalRecorder;
+        }
+    }
+    if (recorder) {
+        start();
+    }
+}
+export function stopSessionRecording() {
+    if (stopRecorder) {
+        try {
+            stopRecorder();
+        }
+        catch (e) {
+            debug("Failed to stop session recorder", e);
+        }
+        stopRecorder = undefined;
+    }
+    chunker?.flush();
+    chunker = undefined;
+}
+export function isSessionRecording() {
+    return stopRecorder != null;
+}
+function start() {
+    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;
+    }
+    const traceId = generateTraceId(sessionId);
+    const stream = {
+        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: !flushingOnLastChance });
+            }
+            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) => {
+                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(() => {
+            flushingOnLastChance = true;
+            try {
+                chunker?.flush();
+            }
+            finally {
+                flushingOnLastChance = 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) {
+    c.discard();
+    chunker = undefined;
+}

package/dist/modules/instrumentations/session-recording/index_test.js

@@ -0,0 +1,230 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { win } from "../../utils";
+vi.mock("../../transport", () => ({
+    sendSessionRecordingChunk: vi.fn(),
+    sendLog: vi.fn(),
+    sendSpan: vi.fn(),
+}));
+vi.mock("../../api/session", () => ({
+    sessionId: "aabbccdd11223344",
+}));
+describe("session recording lifecycle", () => {
+    let mod;
+    let vars;
+    let sendSessionRecordingChunk;
+    let stopFn;
+    let recorder;
+    let capturedOptions;
+    beforeEach(async () => {
+        vi.resetModules();
+        vi.useFakeTimers();
+        mod = await import("./index");
+        vars = (await import("../../vars")).vars;
+        sendSessionRecordingChunk = (await import("../../transport")).sendSessionRecordingChunk;
+        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) => {
+            capturedOptions = opts;
+            return stopFn;
+        });
+    });
+    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.dash0Recorder = recorder;
+        try {
+            mod.armSessionRecording();
+            expect(recorder).toHaveBeenCalledTimes(1);
+            expect(mod.isSessionRecording()).toBe(true);
+        }
+        finally {
+            delete win.dash0Recorder;
+        }
+    });
+    it("prefers an explicitly registered recorder over window.dash0Recorder", () => {
+        const globalRecorder = vi.fn(() => vi.fn());
+        win.dash0Recorder = globalRecorder;
+        try {
+            mod.registerSessionRecorder(recorder);
+            mod.armSessionRecording();
+            expect(recorder).toHaveBeenCalledTimes(1);
+            expect(globalRecorder).not.toHaveBeenCalled();
+        }
+        finally {
+            delete win.dash0Recorder;
+        }
+    });
+    it("ignores a window.dash0Recorder that is not a function", () => {
+        win.dash0Recorder = "nope";
+        try {
+            mod.armSessionRecording();
+            expect(mod.isSessionRecording()).toBe(false);
+        }
+        finally {
+            delete win.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");
+        });
+        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) => {
+            opts.emit({ type: 4, timestamp: 1000, data: {} });
+            opts.emit({ type: 2, timestamp: 1001, data: {} });
+            return undefined;
+        });
+        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);
+    });
+});

package/dist/modules/instrumentations/session-recording/log.js

@@ -0,0 +1,23 @@
+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";
+export function buildSessionRecordingLog(stream, chunk) {
+    const attributes = [];
+    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/dist/modules/instrumentations/session-recording/log_test.js

@@ -0,0 +1,46 @@
+import { describe, expect, it, vi } from "vitest";
+import { buildSessionRecordingLog } from "./log";
+vi.mock("../../api/session", () => ({ sessionId: "aabbccdd11223344" }));
+describe("session recording log record", () => {
+    const stream = {
+        recordingId: "0123456789abcdef0123456789abcdef",
+        traceId: "d04200aabbccdd112233440123456789",
+        spanId: "0123456789abcdef",
+    };
+    const 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/dist/modules/semantic-conventions.js

@@ -26,6 +26,12 @@ export const WINDOW_WIDTH = "browser.window.width";
 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";
@@ -60,6 +66,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";
 // Log Severities

package/dist/modules/transport/fetch.js

@@ -7,14 +7,14 @@ import { noop, warn, fetch, debug } from "../utils";
 const BEACON_BODY_SIZE_LIMIT = 60000;
 let pendingBodySize = 0;
 let pendingRequestCount = 0;
-export async function send(path, body) {
+export async function send(path, body, opts) {
     debug("Transmitting telemetry to endpoints", body);
     const jsonString = JSON.stringify(body);
     let requestBody = jsonString;
     let byteLength = new Blob([jsonString]).size;
     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/dist/modules/transport/fetch_test.js

@@ -264,4 +264,29 @@ 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");
+        });
+    });
 });