@dash0/sdk-web 0.13.5 → 0.14.0

package/src/api/init.ts

@@ -1,4 +1,4 @@
-import { Endpoint, Vars, vars } from "../vars";
+import { vars } from "../vars";
 import {
   DEPLOYMENT_ENVIRONMENT_NAME,
   DEPLOYMENT_ID,
@@ -23,57 +23,12 @@ import {
 import { trackSessions } from "./session";
 import { startWebVitalsInstrumentation } from "../instrumentations/web-vitals";
 import { startErrorInstrumentation } from "../instrumentations/errors";
-import { addAttribute, AttributeValueType } from "../utils/otel";
+import { addAttribute } from "../utils/otel";
 import { instrumentFetch } from "../instrumentations/http/fetch";
 import { startNavigationInstrumentation } from "../instrumentations/navigation";
 import { merge } from "ts-deepmerge";
 import { initializeTabId } from "../utils/tab-id";
-import { AnyValue } from "../types/otlp";
-
-export type InitOptions = {
-  serviceName: string;
-  serviceVersion?: string;
-  environment?: string;
-  deploymentName?: string;
-  deploymentId?: string;
-
-  /**
-   * Additional attributes to include with transmitted signals
-   */
-  additionalSignalAttributes?: Record<string, AttributeValueType | AnyValue>;
-
-  /**
-   * OTLP endpoints to which the generated telemetry should be sent to.
-   */
-  endpoint: Endpoint | Endpoint[];
-
-  /**
-   * The  session inactivity timeout. Session inactivity is the maximum
-   * allowed time to pass between two page loads before the session is considered
-   * to be expired. Also think of cache time-to-idle configuration options.
-   */
-  sessionInactivityTimeoutMillis?: number;
-
-  /**
-   * The default session termination timeout. Session termination is the maximum
-   * allowed time to pass since session start before the session is considered
-   * to be expired. Also think of cache time-to-live configuration options.
-   */
-  sessionTerminationTimeoutMillis?: number;
-} & Partial<
-  Pick<
-    Vars,
-    | "ignoreUrls"
-    | "ignoreErrorMessages"
-    | "wrapEventHandlers"
-    | "wrapTimers"
-    | "propagateTraceHeadersCorsURLs"
-    | "maxWaitForResourceTimingsMillis"
-    | "maxToleranceForResourceTimingsMillis"
-    | "headersToCapture"
-    | "pageViewInstrumentation"
-  >
->;
+import { InitOptions, InstrumentationName } from "../types/options";
 
 let hasBeenInitialised: boolean = false;
 
@@ -112,6 +67,7 @@ export function init(opts: InitOptions) {
         "maxWaitForResourceTimingsMillis",
         "maxToleranceForResourceTimingsMillis",
         "headersToCapture",
+        "urlAttributeScrubber",
         "pageViewInstrumentation",
       ])
     )
@@ -121,10 +77,19 @@ export function init(opts: InitOptions) {
   initializeSignalAttributes(opts);
   initializeTabId();
   trackSessions(opts.sessionInactivityTimeoutMillis, opts.sessionTerminationTimeoutMillis);
-  startNavigationInstrumentation();
-  startWebVitalsInstrumentation();
-  startErrorInstrumentation();
-  instrumentFetch();
+
+  if (isInstrumentationEnabled("@dash0/navigation", opts)) {
+    startNavigationInstrumentation();
+  }
+  if (isInstrumentationEnabled("@dash0/web-vitals", opts)) {
+    startWebVitalsInstrumentation();
+  }
+  if (isInstrumentationEnabled("@dash0/error", opts)) {
+    startErrorInstrumentation();
+  }
+  if (isInstrumentationEnabled("@dash0/fetch", opts)) {
+    instrumentFetch();
+  }
 
   hasBeenInitialised = true;
 }
@@ -219,3 +184,11 @@ function detectDeploymentId(opts: InitOptions): string | undefined {
     return undefined;
   }
 }
+
+function isInstrumentationEnabled(name: InstrumentationName, opts: InitOptions): boolean {
+  const instrumentations = opts.enabledInstrumentations;
+
+  if (!instrumentations) return true;
+
+  return instrumentations.includes(name);
+}

package/src/api/init_test.ts

@@ -0,0 +1,108 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { InitOptions, InstrumentationName } from "../types/options";
+
+// Mock all the instrumentation modules
+vi.mock("../instrumentations/web-vitals", () => ({
+  startWebVitalsInstrumentation: vi.fn(),
+}));
+
+vi.mock("../instrumentations/errors", () => ({
+  startErrorInstrumentation: vi.fn(),
+}));
+
+vi.mock("../instrumentations/http/fetch", () => ({
+  instrumentFetch: vi.fn(),
+}));
+
+vi.mock("../instrumentations/navigation", () => ({
+  startNavigationInstrumentation: vi.fn(),
+}));
+
+import { startWebVitalsInstrumentation } from "../instrumentations/web-vitals";
+import { startErrorInstrumentation } from "../instrumentations/errors";
+import { instrumentFetch } from "../instrumentations/http/fetch";
+import { startNavigationInstrumentation } from "../instrumentations/navigation";
+
+describe("init", () => {
+  const baseOptions: InitOptions = {
+    serviceName: "test-service",
+    endpoint: { url: "https://test-endpoint.com", authToken: "invalid" },
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    // Reset the hasBeenInitialised flag by re-importing the module
+    vi.resetModules();
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("instrumentation enablement", () => {
+    it("should enable all instrumentations when enabledInstrumentations is undefined", async () => {
+      const { init } = await import("./init");
+
+      init({
+        ...baseOptions,
+        enabledInstrumentations: undefined,
+      });
+
+      expect(startNavigationInstrumentation).toHaveBeenCalled();
+      expect(startWebVitalsInstrumentation).toHaveBeenCalled();
+      expect(startErrorInstrumentation).toHaveBeenCalled();
+      expect(instrumentFetch).toHaveBeenCalled();
+    });
+
+    const instrumentations: InstrumentationName[] = [
+      "@dash0/navigation",
+      "@dash0/web-vitals",
+      "@dash0/error",
+      "@dash0/fetch",
+    ];
+    const instrumentationMocks = {
+      "@dash0/navigation": startNavigationInstrumentation,
+      "@dash0/web-vitals": startWebVitalsInstrumentation,
+      "@dash0/error": startErrorInstrumentation,
+      "@dash0/fetch": instrumentFetch,
+    };
+
+    instrumentations.forEach((instrumentation) => {
+      it(`should enable ${instrumentation} instrumentation when present in enabledInstrumentations array`, async () => {
+        const { init } = await import("./init");
+
+        init({
+          ...baseOptions,
+          enabledInstrumentations: [instrumentation],
+        });
+
+        expect(instrumentationMocks[instrumentation]).toHaveBeenCalled();
+
+        // Check that other instrumentations are not called
+        Object.entries(instrumentationMocks).forEach(([name, mock]) => {
+          if (name !== instrumentation) {
+            expect(mock).not.toHaveBeenCalled();
+          }
+        });
+      });
+
+      it(`should not enable ${instrumentation} instrumentation when not present in enabledInstrumentations array`, async () => {
+        const { init } = await import("./init");
+
+        const otherInstrumentations = instrumentations.filter((i) => i !== instrumentation);
+
+        init({
+          ...baseOptions,
+          enabledInstrumentations: otherInstrumentations,
+        });
+
+        expect(instrumentationMocks[instrumentation]).not.toHaveBeenCalled();
+
+        // Check that other instrumentations are called
+        otherInstrumentations.forEach((name) => {
+          expect(instrumentationMocks[name]).toHaveBeenCalled();
+        });
+      });
+    });
+  });
+});

package/src/attributes/url.ts

@@ -1,7 +1,19 @@
 import { addAttribute, AttrPrefix, withPrefix } from "../utils/otel";
 import { URL_DOMAIN, URL_FRAGMENT, URL_FULL, URL_PATH, URL_QUERY, URL_SCHEME } from "../semantic-conventions";
-import { parseUrl } from "../utils";
+import { identity, parseUrl } from "../utils";
 import { KeyValue } from "../types/otlp";
+import { vars } from "../vars";
+
+export type UrlAttributeRecord = {
+  [URL_FULL]: string;
+  [URL_PATH]?: string | undefined;
+  [URL_DOMAIN]?: string | undefined;
+  [URL_SCHEME]?: string | undefined;
+  [URL_FRAGMENT]?: string | undefined;
+  [URL_QUERY]?: string | undefined;
+};
+
+export type UrlAttributeScrubber = (attr: UrlAttributeRecord) => UrlAttributeRecord;
 
 export function addUrlAttributes(attributes: KeyValue[], url: string | URL, prefix?: AttrPrefix) {
   const applyPrefix = withPrefix(prefix);
@@ -11,17 +23,27 @@ export function addUrlAttributes(attributes: KeyValue[], url: string | URL, pref
     if (parsed.username) parsed.username = "REDACTED";
     if (parsed.password) parsed.password = "REDACTED";
 
-    addAttribute(attributes, applyPrefix(URL_FULL), parsed.href);
-    addAttribute(attributes, applyPrefix(URL_PATH), parsed.pathname);
-    addAttribute(attributes, applyPrefix(URL_DOMAIN), parsed.hostname);
-    addAttribute(attributes, applyPrefix(URL_SCHEME), parsed.protocol.replace(":", ""));
-    if (parsed.hash) {
-      addAttribute(attributes, applyPrefix(URL_FRAGMENT), parsed.hash.replace("#", ""));
-    }
-    if (parsed.search) {
-      addAttribute(attributes, applyPrefix(URL_QUERY), parsed.search.replace("?", ""));
-    }
+    const attrs = vars.urlAttributeScrubber({
+      [URL_FULL]: parsed.href,
+      [URL_PATH]: parsed.pathname,
+      [URL_DOMAIN]: parsed.hostname,
+      [URL_SCHEME]: parsed.protocol.replace(":", ""),
+      [URL_FRAGMENT]: parsed.hash ? parsed.hash.replace("#", "") : undefined,
+      [URL_QUERY]: parsed.search ? parsed.search.replace("?", "") : undefined,
+    });
+
+    Object.entries(attrs).forEach(([key, value]) => {
+      if (value !== undefined) {
+        addAttribute(attributes, applyPrefix(key), value);
+      }
+    });
   } catch (_e) {
-    addAttribute(attributes, applyPrefix(URL_FULL), String(url));
+    // This is fallback handling in case the url failed to parse or the user defined attribute scrubber behaved unexpectedly
+    // If the user did not attempt scrubbing we'll supply the full url for debugging purposes, otherwise we drop all url
+    // attributes
+    if (vars.urlAttributeScrubber === identity) {
+      // `identity` is the default assignment for this option
+      addAttribute(attributes, applyPrefix(URL_FULL), String(url));
+    }
   }
 }