@dash0/sdk-web 0.6.2

package/dist/modules/utils/otel/trace-context.js

@@ -0,0 +1,60 @@
+import { doc } from "../globals";
+import { perf } from "../globals";
+const TRACE_PARENT_HEADER = "traceparent";
+/**
+ * See https://www.w3.org/TR/trace-context/#traceparent-header
+ */
+const w3cTraceparentFormat = /^00-([a-f0-9]{32})-([a-f0-9]{16})-[0-9]{1,2}$/;
+export function getTraceContextForPageLoad() {
+    const match = getTraceparentFromMetaElement().match(w3cTraceparentFormat) ||
+        getTraceparentFromNavigationTiming().match(w3cTraceparentFormat);
+    if (match) {
+        return {
+            traceId: match[1],
+            spanId: match[2],
+        };
+    }
+    return undefined;
+}
+function getTraceparentFromMetaElement() {
+    return (Array.from(doc?.getElementsByTagName("meta") ?? [])
+        .find((e) => e.getAttribute("name")?.toLowerCase() === TRACE_PARENT_HEADER)
+        ?.content.trim() || "");
+}
+function getTraceparentFromNavigationTiming() {
+    const nt = perf.getEntriesByType("navigation")[0];
+    if (!nt) {
+        return "";
+    }
+    if (!nt.serverTiming) {
+        return "";
+    }
+    return getTraceparentFromServerTiming(nt.serverTiming);
+}
+function getTraceparentFromServerTiming(serverTimings) {
+    for (const serverEntry of serverTimings) {
+        if (serverEntry.name === TRACE_PARENT_HEADER) {
+            return serverEntry.description.trim();
+        }
+    }
+    return "";
+}
+export function addTraceContextHttpHeaders(fn, ctx, span) {
+    /**
+     * W3C Traceparent header.
+     * General format is ${version}-${trace-id}-${parent-id}-${trace-flags}
+     *
+     * The only spec'd version is currently 00
+     * Trace flags are an 8 bit field of bit flags:
+     * Sampled: 00000001 - Should only be set if a definite decision to record the trace was made.
+     * If set downstream processors should also record the trace
+     * Random Trace ID: 00000010 - IF set the component guarantees that the seven right most bytes of the trace-id
+     * are randomly generated. Downstream processors are then able to rely on this for technical things like shard keys.
+     *
+     * References:
+     * https://www.w3.org/TR/trace-context-2/#traceparent-header
+     * https://www.w3.org/TR/trace-context-2/#trace-flags
+     * https://www.w3.org/TR/trace-context-2/#random-trace-id-flag
+     */
+    fn.call(ctx, "traceparent", `00-${span.traceId}-${span.spanId}-03`);
+}

package/dist/modules/utils/performance.js

@@ -0,0 +1,162 @@
+import { doc, perf, win } from "./globals";
+import { now } from "./time";
+import { noop } from "./fn";
+import { setTimeout } from "./timers";
+import { addEventListener, removeEventListener } from "./listeners";
+const TEN_MINUTES_IN_MILLIS = 1000 * 60 * 10;
+const ONE_DAY_IN_MILLIS = 1000 * 60 * 60 * 24;
+export const isResourceTimingAvailable = !!(perf && perf.getEntriesByType);
+export const isPerformanceObserverAvailable = perf && typeof win["PerformanceObserver"] === "function" && typeof perf["now"] === "function";
+export const PerformanceTimingNames = Object.freeze({
+    CONNECT_END: "connectEnd",
+    CONNECT_START: "connectStart",
+    DECODED_BODY_SIZE: "decodedBodySize",
+    DOM_COMPLETE: "domComplete",
+    DOM_CONTENT_LOADED_EVENT_END: "domContentLoadedEventEnd",
+    DOM_CONTENT_LOADED_EVENT_START: "domContentLoadedEventStart",
+    DOM_INTERACTIVE: "domInteractive",
+    DOMAIN_LOOKUP_END: "domainLookupEnd",
+    DOMAIN_LOOKUP_START: "domainLookupStart",
+    ENCODED_BODY_SIZE: "encodedBodySize",
+    FETCH_START: "fetchStart",
+    LOAD_EVENT_END: "loadEventEnd",
+    LOAD_EVENT_START: "loadEventStart",
+    NAVIGATION_START: "navigationStart",
+    REDIRECT_END: "redirectEnd",
+    REDIRECT_START: "redirectStart",
+    REQUEST_START: "requestStart",
+    RESPONSE_END: "responseEnd",
+    RESPONSE_START: "responseStart",
+    SECURE_CONNECTION_START: "secureConnectionStart",
+    START_TIME: "startTime",
+    UNLOAD_EVENT_END: "unloadEventEnd",
+    UNLOAD_EVENT_START: "unloadEventStart",
+});
+export function observeResourcePerformance(opts) {
+    if (!isPerformanceObserverAvailable)
+        return observeWithoutPerformanceObserverSupport(opts.onEnd);
+    // Used to calculate the duration when no resource was found.
+    let startTime;
+    let endTime;
+    let resource;
+    // Global resources that will need to be disposed
+    let observer;
+    let fallbackNoResourceFoundTimerHandle;
+    let fallbackEndNeverCalledTimerHandle;
+    return {
+        start: onStart,
+        end: onEnd,
+        cancel: disposeGlobalResources,
+    };
+    function onStart() {
+        startTime = perf.now();
+        try {
+            const PerformanceObserver = win?.PerformanceObserver;
+            if (PerformanceObserver) {
+                observer = new PerformanceObserver(onResourceFound);
+                observer?.observe({ type: "resource" });
+            }
+        }
+        catch (_e) {
+            // Some browsers may not support the passed entryTypes and decide to throw an error.
+            // This would then result in an error with a message like:
+            //
+            // entryTypes only contained unsupported types
+            //
+            // Swallow and ignore the error. Treat it like unavailable performance observer data.
+        }
+        fallbackEndNeverCalledTimerHandle = setTimeout(disposeGlobalResources, TEN_MINUTES_IN_MILLIS);
+    }
+    function onEnd() {
+        endTime = perf.now();
+        cancelFallbackEndNeverCalledTimer();
+        if (resource || !isWaitingAcceptable()) {
+            end();
+        }
+        else {
+            addEventListener(doc, "visibilitychange", onVisibilityChanged);
+            fallbackNoResourceFoundTimerHandle = setTimeout(end, opts.maxWaitForResourceMillis);
+        }
+    }
+    function end() {
+        disposeGlobalResources();
+        // In some old web browsers, e.g. Chrome 31, the value provided as the duration
+        // can be very wrong. We have seen cases where this value is measured in years.
+        // If this does seem be the case, then we will ignore the duration property and
+        // instead prefer our approximation.
+        if (resource?.duration && resource.duration < ONE_DAY_IN_MILLIS) {
+            opts.onEnd({ resource, duration: Math.round(resource.duration) });
+        }
+        else {
+            opts.onEnd({ resource, duration: Math.round(endTime - startTime) });
+        }
+    }
+    function onResourceFound(list) {
+        const r = list.getEntriesByType("resource").find((e) => {
+            // This polymorphism is not properly represented in the api types. The cast is safe since we're only accessing the resource timings.
+            const entry = e;
+            return (entry.startTime >= startTime &&
+                (!endTime || endTime + opts.maxToleranceForResourceTimingsMillis >= entry.responseEnd) &&
+                opts.resourceMatcher(entry));
+        });
+        if (!r)
+            return;
+        resource = r;
+        if (endTime)
+            end();
+    }
+    function onVisibilityChanged() {
+        if (!isWaitingAcceptable())
+            end();
+    }
+    function disposeGlobalResources() {
+        disconnectResourceObserver();
+        cancelFallbackNoResourceFoundTimer();
+        cancelFallbackEndNeverCalledTimer();
+        stopVisibilityObservation();
+    }
+    function disconnectResourceObserver() {
+        if (observer) {
+            try {
+                observer?.disconnect();
+            }
+            catch (_e) {
+                // Observer disconnect may throw when connect attempt wasn't successful. Ignore this.
+            }
+            observer = undefined;
+        }
+    }
+    function cancelFallbackNoResourceFoundTimer() {
+        if (fallbackNoResourceFoundTimerHandle) {
+            clearTimeout(fallbackNoResourceFoundTimerHandle);
+            fallbackNoResourceFoundTimerHandle = undefined;
+        }
+    }
+    function cancelFallbackEndNeverCalledTimer() {
+        if (fallbackEndNeverCalledTimerHandle) {
+            clearTimeout(fallbackEndNeverCalledTimerHandle);
+            fallbackEndNeverCalledTimerHandle = undefined;
+        }
+    }
+    function stopVisibilityObservation() {
+        if (!doc)
+            return;
+        removeEventListener(doc, "visibilitychange", onVisibilityChanged);
+    }
+}
+// We may only wait for resource data to arrive as long as the document is visible or in the process
+// of becoming visible. In all other cases we might lose data when waiting, e.g. when the document
+// is in the process of being disposed.
+function isWaitingAcceptable() {
+    return doc?.visibilityState === "visible" || doc?.visibilityState === "prerender";
+}
+function observeWithoutPerformanceObserverSupport(onEnd) {
+    let start = 0;
+    return {
+        start: () => {
+            start = now();
+        },
+        end: () => onEnd({ duration: now() - start }),
+        cancel: noop,
+    };
+}

package/dist/modules/utils/pick.js

@@ -0,0 +1,17 @@
+/**
+ * Creates a new object by picking specified properties from the source object.
+ * Similar to TypeScript's Pick<T, K> utility type but as a runtime function.
+ *
+ * @param obj - The source object to pick properties from
+ * @param keys - Array of property keys to pick from the source object
+ * @returns A new object containing only the specified properties
+ */
+export function pick(obj, keys) {
+    const result = {};
+    for (const key of keys) {
+        if (key in obj) {
+            result[key] = obj[key];
+        }
+    }
+    return result;
+}

package/dist/modules/utils/pick_test.js

@@ -0,0 +1,104 @@
+import { describe, it, expect } from "vitest";
+import { pick } from "./pick";
+describe("pick", () => {
+    it("should pick specified properties from an object", () => {
+        const source = {
+            name: "John",
+            age: 30,
+            email: "john@example.com",
+            city: "New York",
+        };
+        const result = pick(source, ["name", "age"]);
+        expect(result).toEqual({
+            name: "John",
+            age: 30,
+        });
+    });
+    it("should return empty object when picking from empty object", () => {
+        const source = {};
+        const result = pick(source, ["name", "age"]);
+        expect(result).toEqual({});
+    });
+    it("should handle picking non-existent properties", () => {
+        const source = {
+            name: "John",
+            age: 30,
+        };
+        const result = pick(source, ["name", "nonExistent"]);
+        expect(result).toEqual({
+            name: "John",
+        });
+    });
+    it("should pick all properties when all keys are specified", () => {
+        const source = {
+            a: 1,
+            b: 2,
+            c: 3,
+        };
+        const result = pick(source, ["a", "b", "c"]);
+        expect(result).toEqual(source);
+        expect(result).not.toBe(source); // Should be a new object
+    });
+    it("should return empty object when no keys are specified", () => {
+        const source = {
+            name: "John",
+            age: 30,
+        };
+        const result = pick(source, []);
+        expect(result).toEqual({});
+    });
+    it("should preserve property values including falsy ones", () => {
+        const source = {
+            name: "",
+            age: 0,
+            active: false,
+            data: null,
+            info: undefined,
+        };
+        const result = pick(source, ["name", "age", "active", "data", "info"]);
+        expect(result).toEqual({
+            name: "",
+            age: 0,
+            active: false,
+            data: null,
+            info: undefined,
+        });
+    });
+    it("should work with nested objects", () => {
+        const source = {
+            user: {
+                name: "John",
+                age: 30,
+            },
+            settings: {
+                theme: "dark",
+            },
+            isActive: true,
+        };
+        const result = pick(source, ["user", "isActive"]);
+        expect(result).toEqual({
+            user: {
+                name: "John",
+                age: 30,
+            },
+            isActive: true,
+        });
+        expect(result.user).toBe(source.user); // Should reference the same nested object
+    });
+    it("should maintain type safety", () => {
+        const user = {
+            id: 1,
+            name: "John",
+            email: "john@example.com",
+            isActive: true,
+        };
+        const result = pick(user, ["id", "name"]);
+        // TypeScript should infer the type as Pick<User, 'id' | 'name'>
+        expect(result.id).toBe(1);
+        expect(result.name).toBe("John");
+        expect(result).toEqual({
+            id: 1,
+            name: "John",
+        });
+    });
+});

package/dist/modules/utils/rate-limit.js

@@ -0,0 +1,20 @@
+import { setInterval } from "./timers";
+export function createRateLimiter(opts) {
+    const maxCalls = opts.maxCalls || 4096;
+    const maxCallsPerTenMinutes = opts.maxCallsPerTenMinutes || 128;
+    const maxCallsPerTenSeconds = opts.maxCallsPerTenSeconds || 32;
+    let totalCalls = 0;
+    let totalCallsInLastTenMinutes = 0;
+    let totalCallsInLastTenSeconds = 0;
+    setInterval(function () {
+        totalCallsInLastTenMinutes = 0;
+    }, 1000 * 60 * 10);
+    setInterval(function () {
+        totalCallsInLastTenSeconds = 0;
+    }, 1000 * 10);
+    return function isExcessiveUsage() {
+        return (++totalCalls > maxCalls ||
+            ++totalCallsInLastTenMinutes > maxCallsPerTenMinutes ||
+            ++totalCallsInLastTenSeconds > maxCallsPerTenSeconds);
+    };
+}

package/dist/modules/utils/session-storage.js

@@ -0,0 +1,21 @@
+// sessionStorage API re-exposed to allow testing.
+import { sessionStorage } from "./globals";
+export const isSupported = sessionStorage != null &&
+    typeof sessionStorage.getItem === "function" &&
+    typeof sessionStorage.setItem === "function";
+export function getItem(k) {
+    if (isSupported && sessionStorage) {
+        return sessionStorage.getItem(k);
+    }
+    return null;
+}
+export function setItem(k, v) {
+    if (isSupported && sessionStorage) {
+        sessionStorage.setItem(k, v);
+    }
+}
+export function removeItem(k) {
+    if (isSupported && sessionStorage) {
+        sessionStorage.removeItem(k);
+    }
+}

package/dist/modules/utils/tab-id.js

@@ -0,0 +1,29 @@
+import { getItem, isSupported, setItem } from "./session-storage";
+import { debug, warn } from "./debug";
+import { generateUniqueId, TAB_ID_BYTES } from "./id";
+const TAB_ID_STORAGE_KEY = "d0_tab";
+export let tabId = null;
+/**
+ * We want to be able to identify what browser tab the user is looking at. We do this by identifying tabs through
+ * random-generated IDs that are kept in session storage. To quote MDN:
+ *
+ * > sessionStorage is partitioned by both origin and browser tabs (top-level browsing contexts)
+ */
+export function initializeTabId() {
+    if (!isSupported) {
+        debug("Storage API is not available and tab tracking is therefore not supported.");
+        return;
+    }
+    try {
+        const storedValue = getItem(TAB_ID_STORAGE_KEY);
+        if (storedValue) {
+            tabId = storedValue;
+            return;
+        }
+        tabId = generateUniqueId(TAB_ID_BYTES);
+        setItem(TAB_ID_STORAGE_KEY, tabId);
+    }
+    catch (e) {
+        warn("Failed to record tab ID information", e);
+    }
+}

package/dist/modules/utils/time.js

@@ -0,0 +1,28 @@
+import { perf } from "./globals";
+export function now() {
+    return new Date().getTime();
+}
+export function nowNanos() {
+    const timeOrigin = getTimeOrigin();
+    if (timeOrigin) {
+        return String((perf.now() + timeOrigin) * 1000000);
+    }
+    return toNanosTs(new Date());
+}
+export function toNanosTs(time) {
+    if (typeof time === "object") {
+        return toNanosTs(time.getTime());
+    }
+    // We don't multiply, because we want to keep number precision
+    return String(time) + "000000";
+}
+export function getTimeOrigin() {
+    let timeOrigin = perf?.timeOrigin;
+    if (typeof timeOrigin !== "number") {
+        timeOrigin = perf?.timing?.fetchStart;
+    }
+    return timeOrigin;
+}
+export function domHRTimestampToNanos(ts) {
+    return String(Math.round((ts + getTimeOrigin()) * 1000000));
+}

package/dist/modules/utils/timers.js

@@ -0,0 +1,62 @@
+import { warn, debug } from "./debug";
+import { win } from "./globals";
+// This module contains wrappers around the standard timer API. These wrappers can be used to
+// ensure that execution of timers happens outside of any Angular specific zones. This in turn
+// means that this script will never disturb Angular's stabilization phase.
+// https://angular.io/api/core/ApplicationRef#isStable
+// Please note that it may sometimes be necessary to deliberately execute code inside of
+// Angular's Zones. Always take care to make a deliberate decision when to use and when not to
+// use these wrappers.
+// We take a copy of all globals to ensure that no other script will change them all of a sudden.
+// This ensures that when we register a timeout/interval on one global, that we will be able to
+// de-register it again in all cases.
+const globals = {
+    setTimeout: win?.setTimeout,
+    clearTimeout: win?.clearTimeout,
+    setInterval: win?.setInterval,
+    clearInterval: win?.clearInterval,
+};
+// If the globals don't exist at execution time of this file, then we know that the globals stored
+// above are not wrapped by Zone.js. This in turn can mean better performance for Angular users.
+export const isRunningZoneJs = win != null && win["Zone"] != null && win["Zone"]["root"] != null && typeof win["Zone"]["root"]["run"] === "function";
+if (isRunningZoneJs) {
+    debug("Discovered Zone.js globals. Will attempt to register all timers inside the root Zone.");
+}
+export function setTimeout(..._) {
+    return executeGlobally.apply("setTimeout", arguments);
+}
+export function clearTimeout(..._) {
+    return executeGlobally.apply("clearTimeout", arguments);
+}
+export function setInterval(..._) {
+    return executeGlobally.apply("setInterval", arguments);
+}
+export function clearInterval(..._) {
+    return executeGlobally.apply("clearInterval", arguments);
+}
+function executeGlobally() {
+    // We don't want to incur a performance penalty for all users just because some
+    // users are relying on zone.js. This API looks quite ridiculous, but it
+    // allows for concise and efficient code, e.g. arguments does not need to be
+    // translated into an array.
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    const globalFunctionName = this;
+    if (isRunningZoneJs) {
+        try {
+            // Incurr a performance overhead for Zone.js users that we just cannot avoid:
+            // Copy the arguments passed in here so that we can use them inside the root
+            // zone.
+            const args = Array.prototype.slice.apply(arguments);
+            // @ts-expect-error necessary Zone.js types not added
+            return win["Zone"]["root"]["run"](globals[globalFunctionName], win, args);
+        }
+        catch (e) {
+            warn("Failed to execute %s inside of zone (via Zone.js). Falling back to execution inside currently " +
+                "active zone.", globalFunctionName, e);
+            // failure – maybe zone js not properly initialized? Fall back to execution
+            // outside of Zone.js as a last resort (outside of try/catch and if)
+        }
+    }
+    // Note: Explicitly passing win as 'this' even though we are getting the function from 'globals'
+    return globals[globalFunctionName]?.apply(win, arguments);
+}

package/dist/modules/utils/url.js

@@ -0,0 +1,11 @@
+import { doc, loc } from "./globals";
+/**
+ * Parses url using URL constructor. Supports URL objects as passthrough input to simplify implementations
+ * May throw if parsing fails
+ * @param url
+ */
+export function parseUrl(url) {
+    if (typeof url !== "string")
+        return url;
+    return new URL(url, doc?.baseURI ?? loc?.href);
+}

package/dist/modules/utils/wrap.js

@@ -0,0 +1,22 @@
+import { debug } 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 🤫
+    return objOrFunction[INSTRUMENTED_BY_DASH0_SYMBOL] === true;
+}
+function markAsInstrumented(objOrFunction) {
+    // @ts-expect-error -- typescript does not know about this hidden marker and we're not going to tell it 🤫
+    objOrFunction[INSTRUMENTED_BY_DASH0_SYMBOL] = true;
+}
+export function wrap(module, target, wrapper) {
+    const original = module[target];
+    if (!original) {
+        debug(`${String(target)} is not defined, unable to instrument`);
+        return;
+    }
+    if (isAlreadyInstrumented(original)) {
+        debug(`${String(target)} has already been instrumented, skipping`);
+    }
+    markAsInstrumented(original);
+    module[target] = wrapper(original);
+}

package/dist/modules/vars.js

@@ -0,0 +1,25 @@
+// TODO use OTel types here?
+export const vars = {
+    endpoints: [],
+    resource: {
+        attributes: [],
+    },
+    scope: {
+        name: "dash0-web-sdk",
+        version: __sdkVersion,
+        attributes: [],
+    },
+    signalAttributes: [],
+    ignoreUrls: [],
+    ignoreErrorMessages: [],
+    wrapEventHandlers: true,
+    wrapTimers: true,
+    propagateTraceHeadersCorsURLs: [],
+    maxWaitForResourceTimingsMillis: 10000,
+    maxToleranceForResourceTimingsMillis: 3000,
+    headersToCapture: [],
+    pageViewInstrumentation: {
+        trackVirtualPageViews: true,
+        includeParts: [],
+    },
+};