@dash0/sdk-web 0.22.1 → 0.24.0

package/dist/modules/instrumentations/navigation/event.js

@@ -1,4 +1,4 @@
-import { addAttribute, getTraceContextForPageLoad } from "../../utils/otel";
+import { addAttribute, addAttributes, getTraceContextForPageLoad } from "../../utils/otel";
 import { EVENT_NAME, EVENT_NAMES, LOG_SEVERITIES, PAGE_VIEW_CHANGE_STATE, PAGE_VIEW_CHANGE_STATE_VALUES, PAGE_VIEW_TYPE, PAGE_VIEW_TYPE_VALUES, } from "../../semantic-conventions";
 import { doc, NO_VALUE_FALLBACK } from "../../utils";
 import { addCommonAttributes } from "../../attributes";
@@ -9,23 +9,26 @@ function getPageViewMeta(url) {
         return {};
     return vars.pageViewInstrumentation.generateMetadata?.(url) ?? {};
 }
-export function transmitPageViewEvent(timeUnixNano, url, virtual, replaced) {
-    const meta = getPageViewMeta(url);
+function buildAndSendPageViewLog(opts) {
     const attributes = [];
     addAttribute(attributes, EVENT_NAME, EVENT_NAMES.PAGE_VIEW);
-    if (meta.attributes) {
-        Object.entries(meta.attributes).forEach(([key, value]) => addAttribute(attributes, key, value));
+    if (opts.metaAttributes) {
+        Object.entries(opts.metaAttributes).forEach(([key, value]) => addAttribute(attributes, key, value));
     }
-    addCommonAttributes(attributes, { url });
+    addCommonAttributes(attributes, { url: opts.url });
+    // Add custom attributes last to allow overrides
+    addAttributes(attributes, opts.customAttributes);
     const bodyAttributes = [];
-    addAttribute(bodyAttributes, "title", meta.title ?? doc?.title ?? NO_VALUE_FALLBACK);
+    addAttribute(bodyAttributes, "title", opts.title ?? doc?.title ?? NO_VALUE_FALLBACK);
     if (doc?.referrer) {
         addAttribute(bodyAttributes, "referrer", doc.referrer);
     }
-    addAttribute(bodyAttributes, PAGE_VIEW_TYPE, virtual ? PAGE_VIEW_TYPE_VALUES.VIRTUAL : PAGE_VIEW_TYPE_VALUES.INITIAL);
-    addAttribute(bodyAttributes, PAGE_VIEW_CHANGE_STATE, replaced ? PAGE_VIEW_CHANGE_STATE_VALUES.REPLACE : PAGE_VIEW_CHANGE_STATE_VALUES.PUSH);
+    addAttribute(bodyAttributes, PAGE_VIEW_TYPE, opts.pageViewType);
+    if (opts.changeState) {
+        addAttribute(bodyAttributes, PAGE_VIEW_CHANGE_STATE, opts.changeState);
+    }
     const log = {
-        timeUnixNano: timeUnixNano,
+        timeUnixNano: opts.timeUnixNano,
         attributes: attributes,
         severityNumber: LOG_SEVERITIES.INFO,
         severityText: "INFO",
@@ -42,3 +45,32 @@ export function transmitPageViewEvent(timeUnixNano, url, virtual, replaced) {
     }
     sendLog(log);
 }
+export function transmitPageViewEvent(timeUnixNano, url, virtual, replaced) {
+    const meta = getPageViewMeta(url);
+    buildAndSendPageViewLog({
+        timeUnixNano,
+        url,
+        title: meta.title,
+        metaAttributes: meta.attributes,
+        pageViewType: virtual ? PAGE_VIEW_TYPE_VALUES.VIRTUAL : PAGE_VIEW_TYPE_VALUES.INITIAL,
+        changeState: replaced ? PAGE_VIEW_CHANGE_STATE_VALUES.REPLACE : PAGE_VIEW_CHANGE_STATE_VALUES.PUSH,
+    });
+}
+/**
+ * Emits a manually-triggered page view log, e.g. from the public `startView` API.
+ * Deliberately does NOT read `vars.pageViewInstrumentation.generateMetadata` and does NOT
+ * include a `change_state` body key (a manual view is neither a pushState nor replaceState).
+ * The emitted `type` is PAGE_VIEW_TYPE_VALUES.VIRTUAL, matching automatic virtual page views —
+ * manual views are deliberately indistinguishable from virtual ones downstream.
+ * Caller-provided attributes are added after the SDK-generated ones so they can override them,
+ * matching the sendEvent semantics.
+ */
+export function transmitManualPageViewEvent(opts) {
+    buildAndSendPageViewLog({
+        timeUnixNano: opts.timeUnixNano,
+        url: opts.url,
+        title: opts.title,
+        customAttributes: opts.attributes,
+        pageViewType: PAGE_VIEW_TYPE_VALUES.VIRTUAL,
+    });
+}

package/dist/modules/instrumentations/navigation/event_test.js

@@ -0,0 +1,128 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+vi.mock("../../transport", () => ({
+    sendLog: vi.fn(),
+}));
+import { sendLog } from "../../transport";
+import { transmitPageViewEvent, transmitManualPageViewEvent } from "./event";
+import { vars } from "../../vars";
+const sendLogMock = sendLog;
+describe("transmitPageViewEvent", () => {
+    beforeEach(() => {
+        sendLogMock.mockClear();
+        vars.pageViewInstrumentation = { trackVirtualPageViews: true, includeParts: [] };
+    });
+    afterEach(() => {
+        vi.clearAllMocks();
+    });
+    it("transmits an initial page view with type=INITIAL and change_state=pushState", () => {
+        transmitPageViewEvent("1700000000000000000", new URL("https://example.com/landing"));
+        expect(sendLogMock).toHaveBeenCalledTimes(1);
+        const log = sendLogMock.mock.calls[0][0];
+        expect(log.timeUnixNano).toBe("1700000000000000000");
+        expect(log.severityNumber).toBe(9);
+        expect(log.severityText).toBe("INFO");
+        expect(log.attributes).toEqual(expect.arrayContaining([{ key: "event.name", value: { stringValue: "browser.page_view" } }]));
+        const bodyValues = log.body?.kvlistValue?.values;
+        expect(bodyValues).toEqual(expect.arrayContaining([
+            { key: "type", value: { doubleValue: 0 } },
+            { key: "change_state", value: { stringValue: "pushState" } },
+        ]));
+    });
+    it("transmits a virtual page view with type=VIRTUAL and change_state=replaceState when replaced", () => {
+        transmitPageViewEvent("1700000000000000000", new URL("https://example.com/settings"), true, true);
+        const log = sendLogMock.mock.calls[0][0];
+        const bodyValues = log.body?.kvlistValue?.values;
+        expect(bodyValues).toEqual(expect.arrayContaining([
+            { key: "type", value: { doubleValue: 1 } },
+            { key: "change_state", value: { stringValue: "replaceState" } },
+        ]));
+    });
+    it("applies generateMetadata title and attributes when provided", () => {
+        vars.pageViewInstrumentation = {
+            trackVirtualPageViews: true,
+            includeParts: [],
+            generateMetadata: () => ({ title: "Custom Title", attributes: { "app.screen": "settings" } }),
+        };
+        transmitPageViewEvent("1700000000000000000", new URL("https://example.com/settings"), true);
+        const log = sendLogMock.mock.calls[0][0];
+        expect(log.attributes).toEqual(expect.arrayContaining([{ key: "app.screen", value: { stringValue: "settings" } }]));
+        const bodyValues = log.body?.kvlistValue?.values;
+        expect(bodyValues).toEqual(expect.arrayContaining([{ key: "title", value: { stringValue: "Custom Title" } }]));
+    });
+});
+describe("transmitManualPageViewEvent", () => {
+    beforeEach(() => {
+        sendLogMock.mockClear();
+        vars.pageViewInstrumentation = {
+            trackVirtualPageViews: true,
+            includeParts: [],
+            generateMetadata: () => ({ title: "should not be used", attributes: { should_not_appear: true } }),
+        };
+    });
+    afterEach(() => {
+        vi.clearAllMocks();
+        vars.pageViewInstrumentation = { trackVirtualPageViews: true, includeParts: [] };
+    });
+    it("emits type=VIRTUAL and no change_state key", () => {
+        transmitManualPageViewEvent({ timeUnixNano: "1700000000000000000", title: "/settings" });
+        const log = sendLogMock.mock.calls[0][0];
+        const bodyValues = log.body?.kvlistValue?.values;
+        expect(bodyValues).toEqual(expect.arrayContaining([
+            { key: "type", value: { doubleValue: 1 } },
+            { key: "title", value: { stringValue: "/settings" } },
+        ]));
+        expect(bodyValues.find((v) => v.key === "change_state")).toBeUndefined();
+    });
+    it("does not invoke vars.pageViewInstrumentation.generateMetadata", () => {
+        const generateMetadata = vi.fn().mockReturnValue({ title: "ignored" });
+        vars.pageViewInstrumentation = { trackVirtualPageViews: true, includeParts: [], generateMetadata };
+        transmitManualPageViewEvent({ timeUnixNano: "1700000000000000000", title: "/settings" });
+        expect(generateMetadata).not.toHaveBeenCalled();
+        const log = sendLogMock.mock.calls[0][0];
+        const bodyValues = log.body?.kvlistValue?.values;
+        expect(bodyValues).toEqual(expect.arrayContaining([{ key: "title", value: { stringValue: "/settings" } }]));
+    });
+    it("merges custom attributes into signal attributes", () => {
+        transmitManualPageViewEvent({
+            timeUnixNano: "1700000000000000000",
+            title: "/settings",
+            attributes: { "app.screen": "settings", "app.tab_index": 2 },
+        });
+        const log = sendLogMock.mock.calls[0][0];
+        expect(log.attributes).toEqual(expect.arrayContaining([
+            { key: "app.screen", value: { stringValue: "settings" } },
+            { key: "app.tab_index", value: { doubleValue: 2 } },
+        ]));
+    });
+    it("adds custom attributes after SDK-generated ones so they can override", () => {
+        transmitManualPageViewEvent({
+            timeUnixNano: "1700000000000000000",
+            title: "/settings",
+            url: new URL("https://example.com/real-path"),
+            attributes: { "page.url.path": "/custom-path" },
+        });
+        const log = sendLogMock.mock.calls[0][0];
+        const pathAttributes = log.attributes.filter((attr) => attr.key === "page.url.path");
+        expect(pathAttributes.length).toBeGreaterThan(1);
+        expect(pathAttributes[pathAttributes.length - 1]).toEqual({
+            key: "page.url.path",
+            value: { stringValue: "/custom-path" },
+        });
+    });
+    it("passes url through to page.url.* attributes when provided", () => {
+        transmitManualPageViewEvent({
+            timeUnixNano: "1700000000000000000",
+            title: "/settings",
+            url: new URL("https://example.com/settings"),
+        });
+        const log = sendLogMock.mock.calls[0][0];
+        expect(log.attributes).toEqual(expect.arrayContaining([{ key: "page.url.path", value: { stringValue: "/settings" } }]));
+    });
+    it("includes referrer the same way the auto path does", () => {
+        transmitManualPageViewEvent({ timeUnixNano: "1700000000000000000", title: "/settings" });
+        const log = sendLogMock.mock.calls[0][0];
+        const bodyValues = log.body?.kvlistValue?.values;
+        // doc.referrer is empty string in jsdom by default, so "referrer" key should be absent
+        expect(bodyValues.find((v) => v.key === "referrer")).toBeUndefined();
+    });
+});

package/dist/modules/utils/wrap.js

@@ -1,4 +1,4 @@
-import { debug } from "./debug";
+import { debug, warn } from "./debug";
 const INSTRUMENTED_BY_DASH0_SYMBOL = Symbol.for("INSTRUMENTED_BY_DASH0");
 function isAlreadyInstrumented(objOrFunction) {
     // @ts-expect-error -- typescript does not know about this hidden marker and we're not going to tell it 🤫
@@ -18,6 +18,19 @@ export function wrap(module, target, wrapper) {
         debug(`${String(target)} has already been instrumented, skipping`);
         return;
     }
-    markAsInstrumented(original);
-    module[target] = wrapper(original);
+    try {
+        const wrapped = wrapper(original);
+        // Mark the replacement as well: a later wrap() call reads the replacement from module[target],
+        // so marking only the original would let repeated instrumentation wrap the wrapper.
+        markAsInstrumented(original);
+        if (wrapped) {
+            markAsInstrumented(wrapped);
+        }
+        module[target] = wrapped;
+    }
+    catch (e) {
+        // Pages can lock properties via Object.defineProperty/Object.freeze -- failing to install
+        // one instrumentation must not throw out of init() and abort the remaining ones.
+        warn(`failed to instrument ${String(target)}, the page may have locked the property`, e);
+    }
 }

package/dist/modules/utils/wrap_test.js

@@ -0,0 +1,31 @@
+import { describe, expect, it, vi } from "vitest";
+import { wrap } from "./wrap";
+describe("wrap", () => {
+    it("replaces the target with the wrapper's return value", () => {
+        const original = () => "original";
+        const module = { fn: original };
+        wrap(module, "fn", (orig) => () => `wrapped ${orig()}`);
+        expect(module.fn()).toBe("wrapped original");
+    });
+    it("does not wrap the same target twice", () => {
+        const module = { fn: () => "original" };
+        const wrapper = vi.fn((orig) => () => `wrapped ${orig()}`);
+        wrap(module, "fn", wrapper);
+        wrap(module, "fn", wrapper);
+        expect(wrapper).toHaveBeenCalledTimes(1);
+        expect(module.fn()).toBe("wrapped original");
+    });
+    it("skips undefined targets", () => {
+        const module = {};
+        const wrapper = vi.fn();
+        expect(() => wrap(module, "fn", wrapper)).not.toThrow();
+        expect(wrapper).not.toHaveBeenCalled();
+    });
+    it("does not throw when the page locked the target property", () => {
+        const original = () => "original";
+        const module = {};
+        Object.defineProperty(module, "fn", { value: original, writable: false, configurable: false });
+        expect(() => wrap(module, "fn", (orig) => () => `wrapped ${orig()}`)).not.toThrow();
+        expect(module.fn).toBe(original);
+    });
+});