@dash0/sdk-web 0.13.4 → 0.14.0

package/dist/types/types/options.d.ts

@@ -0,0 +1,35 @@
+import { AttributeValueType } from "../utils/otel";
+import { AnyValue } from "./otlp";
+import { Endpoint, Vars } from "../vars";
+export type InstrumentationName = "@dash0/navigation" | "@dash0/web-vitals" | "@dash0/error" | "@dash0/fetch";
+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[];
+    /**
+     * Which instrumentations to enable. Defaults to undefined, which means all instrumentations.
+     */
+    enabledInstrumentations?: InstrumentationName[];
+    /**
+     * 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" | "urlAttributeScrubber" | "pageViewInstrumentation">>;

package/dist/types/types/otlp.d.ts

@@ -0,0 +1,104 @@
+import { LOG_SEVERITY_NUMBER, LOG_SEVERITY_TEXT } from "../semantic-conventions";
+export type AnyValue = {
+    ["stringValue"]?: string;
+    ["boolValue"]?: boolean;
+    /** Format: int64 */
+    ["intValue"]?: string;
+    /** Format: double */
+    ["doubleValue"]?: number;
+    ["arrayValue"]?: ArrayValue;
+    ["kvlistValue"]?: KeyValueList;
+    /** Format: byte */
+    ["bytesValue"]?: string;
+};
+export type ArrayValue = {
+    ["values"]: AnyValue[];
+};
+export type KeyValue = {
+    ["key"]: string;
+    ["value"]: AnyValue;
+};
+export type KeyValueList = {
+    ["values"]: KeyValue[];
+};
+export type Resource = {
+    ["attributes"]: KeyValue[];
+};
+export type InstrumentationScope = {
+    ["name"]?: string;
+    ["version"]?: string;
+    ["attributes"]: KeyValue[];
+};
+export type ExportLogsServiceRequest = {
+    resourceLogs: ResourceLogs[];
+};
+export type ResourceLogs = {
+    resource: Resource;
+    scopeLogs: ScopeLogs[];
+};
+export type ScopeLogs = {
+    scope?: InstrumentationScope;
+    logRecords: LogRecord[];
+    schemaUrl?: string;
+};
+export type LogRecord = {
+    /** Format: uint64 */
+    timeUnixNano: string;
+    severityNumber?: LOG_SEVERITY_NUMBER;
+    severityText?: LOG_SEVERITY_TEXT;
+    body?: AnyValue;
+    attributes: KeyValue[];
+    /** Format: byte */
+    traceId?: string;
+    /** Format: byte */
+    spanId?: string;
+};
+export type ExportTraceServiceRequest = {
+    resourceSpans: ResourceSpans[];
+};
+export type ResourceSpans = {
+    resource: Resource;
+    scopeSpans: ScopeSpans[];
+};
+export type ScopeSpans = {
+    scope?: InstrumentationScope;
+    spans: Span[];
+};
+export type SpanStatus = {
+    message?: string;
+    code: 0 | 1 | 2;
+};
+export type SpanEvent = {
+    timeUnixNano: string;
+    name: string;
+    attributes: KeyValue[];
+};
+export type SpanLink = {
+    /** Format: byte */
+    traceId: string;
+    /** Format: byte */
+    spanId: string;
+    traceState?: string;
+    attributes: KeyValue[];
+    droppedAttributesCount: number;
+    flags?: number;
+};
+export type Span = {
+    /** Format: byte */
+    traceId: string;
+    /** Format: byte */
+    spanId: string;
+    traceState?: string;
+    /** Format: byte */
+    parentSpanId?: string;
+    name: string;
+    kind: number;
+    startTimeUnixNano: string;
+    endTimeUnixNano: string;
+    attributes: KeyValue[];
+    events: SpanEvent[];
+    /** Format: int64 */
+    droppedEventsCount?: number;
+    links: SpanLink[];
+    status: SpanStatus;
+};

package/dist/types/utils/fn.d.ts

@@ -1 +1,2 @@
 export declare function noop(): void;
+export declare function identity<T>(a: T): T;

package/dist/types/utils/otel/attributes.d.ts

@@ -1,4 +1,4 @@
-import { AnyValue, KeyValue } from "../../../types/otlp";
+import { AnyValue, KeyValue } from "../../types/otlp";
 type PrimitiveAttributeValue = string | number | boolean;
 export type AttributeValueType = PrimitiveAttributeValue | Array<PrimitiveAttributeValue> | Record<string, PrimitiveAttributeValue>;
 export declare function toAnyValue(value: AttributeValueType | AnyValue): AnyValue;

package/dist/types/utils/otel/error.d.ts

@@ -1,5 +1,5 @@
 import { InProgressSpan } from "./span";
-import { SpanStatus } from "../../../types/otlp";
+import { SpanStatus } from "../../types/otlp";
 interface ExceptionWithCode {
     code: string | number;
     name?: string;

package/dist/types/utils/otel/span.d.ts

@@ -1,4 +1,4 @@
-import { KeyValue, Span, SpanStatus } from "../../../types/otlp";
+import { KeyValue, Span, SpanStatus } from "../../types/otlp";
 export type InProgressSpan = Omit<Span, "endTimeUnixNano">;
 export declare function startSpan(name: string): InProgressSpan;
 export declare function endSpan(span: InProgressSpan, status: SpanStatus | undefined, durationNano: number | undefined): Span;

package/dist/types/vars.d.ts

@@ -1,5 +1,6 @@
-import { AnyValue, InstrumentationScope, KeyValue, Resource } from "../types/otlp";
 import { AttributeValueType } from "./utils/otel";
+import { AnyValue, InstrumentationScope, KeyValue, Resource } from "./types/otlp";
+import { UrlAttributeScrubber } from "./attributes";
 export type Endpoint = {
     /**
      * OTLP HTTP URL excluding the /v1/* prefix
@@ -118,6 +119,15 @@ export type Vars = {
      * These headers will be transferred as span attributes
      */
     headersToCapture: RegExp[];
+    /**
+     * Allows the application of a custom scrubbing function to url attributes before they are applied to signals.
+     * This is invoked for each url processed for inclusion in signal attributes. For example this applies both to `page.url.*`
+     * and `url.*` attribute namespaces.
+     * Sensitive parts of the url attributes should be replaced with `REDACTED`,
+     * avoid partially or fully dropping attributes to preserve telemetry quality.
+     * Note: basic auth credentials in urls are automatically redacted before this is invoked.
+     */
+    urlAttributeScrubber: UrlAttributeScrubber;
     pageViewInstrumentation: PageViewInstrumentationSettings;
 };
 export declare const vars: Vars;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dash0/sdk-web",
-  "version": "0.13.4",
+  "version": "0.14.0",
   "description": "Dash0's Web SDK to collect telemetry from end-users' web browsers",
   "type": "module",
   "main": "dist/dash0.umd.cjs",

package/src/api/attributes.ts

@@ -1,6 +1,6 @@
-import { AnyValue } from "../../types/otlp";
 import { addAttribute, AttributeValueType, removeAttribute } from "../utils/otel";
 import { vars } from "../vars";
+import { AnyValue } from "../types/otlp";
 
 /**
  * Adds a signal attribute to be transmitted with every signal.

package/src/api/events.ts

@@ -1,9 +1,9 @@
-import { AnyValue, KeyValue } from "../../types/otlp";
 import { EVENT_NAME, EVENT_NAMES, WEB_EVENT_TITLE, LOG_SEVERITIES, LOG_SEVERITY_TEXT } from "../semantic-conventions";
 import { sendLog } from "../transport";
 import { addCommonAttributes } from "../attributes";
 import { addAttribute, AttributeValueType, toAnyValue } from "../utils/otel";
 import { nowNanos, TimeInput, toNanosTs, warn } from "../utils";
+import { AnyValue, KeyValue } from "../types/otlp";
 
 type EventOptions = {
   /**

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 { AnyValue } from "../../types/otlp";
 import { startNavigationInstrumentation } from "../instrumentations/navigation";
 import { merge } from "ts-deepmerge";
 import { initializeTabId } from "../utils/tab-id";
-
-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/api/report-error.ts

@@ -1,5 +1,5 @@
-import { ErrorLike, ReportErrorOpts } from "../../types/errors";
 import { reportError as reportErrorInternal } from "../instrumentations/errors/unhandled-error";
+import { ReportErrorOpts, ErrorLike } from "../types/errors";
 
 export function reportError(error: string | ErrorLike, opts?: ReportErrorOpts) {
   reportErrorInternal(error, opts);

package/src/attributes/common.ts

@@ -1,4 +1,3 @@
-import { KeyValue } from "../../types/otlp";
 import { generateUniqueId, nav, NO_VALUE_FALLBACK, WEB_EVENT_ID_BYTES, win } from "../utils";
 import {
   BROWSER_TAB_ID,
@@ -14,6 +13,7 @@ import { vars } from "../vars";
 import { addAttribute } from "../utils/otel";
 import { addUrlAttributes } from "./url";
 import { tabId } from "../utils/tab-id";
+import { KeyValue } from "../types/otlp";
 
 type Options = {
   /**

package/src/attributes/common_test.ts

@@ -1,11 +1,11 @@
 import { describe, it, expect, vi, beforeEach } from "vitest";
 import { addCommonAttributes } from "./common";
-import { KeyValue } from "../../types/otlp";
 import * as utils from "../utils";
 import * as varsModule from "../vars";
 import * as urlModule from "./url";
 import * as sessionApi from "../api/session";
 import * as tabIdModule from "../utils/tab-id";
+import { KeyValue } from "../types/otlp";
 
 describe("addCommonAttributes", () => {
   beforeEach(() => {

package/src/attributes/url.ts

@@ -1,7 +1,19 @@
-import { KeyValue } from "../../types/otlp";
 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));
+    }
   }
 }