@dash0/sdk-web 0.6.2

package/src/instrumentations/navigation/page-load.ts

@@ -0,0 +1,96 @@
+import { addEventListener, debug, doc, win, roundToTwoDecimals, error, toNanosTs, getTimeOrigin } from "../../utils";
+import { KeyValue, LogRecord } from "../../../types/otlp";
+import { EVENT_NAME, EVENT_NAMES, LOG_SEVERITIES } from "../../semantic-conventions";
+import { sendLog } from "../../transport";
+import { getTraceContextForPageLoad, addAttribute } from "../../utils/otel";
+import { addCommonAttributes } from "../../attributes";
+import { transmitPageViewEvent } from "./event";
+
+/**
+ * Tracks page loads as per this OTel spec:
+ * https://github.com/open-telemetry/semantic-conventions/pull/1910/files
+ *
+ * Notable difference: The full URL is transmitted as a signal attribute.
+ */
+export function startPageLoadInstrumentation() {
+  try {
+    transmitPageViewEvent(getStartTimeUnixNanos(), win?.location.href ? new URL(win?.location.href) : undefined);
+  } catch (e) {
+    error("Failed to transmit initial page view event", e);
+  }
+
+  if (doc?.readyState === "complete") {
+    return onLoaded();
+  }
+
+  if (win) {
+    addEventListener(win, "load", function () {
+      // we want to get timing data for loadEventEnd,
+      // so asynchronously process this
+      setTimeout(onLoaded, 0);
+    });
+  }
+}
+
+/**
+ * See https://github.com/open-telemetry/semantic-conventions/pull/1919
+ */
+function onLoaded() {
+  const nt = win?.performance.getEntriesByType("navigation")[0];
+  if (!nt) {
+    debug("Navigation timings not available. Cannot emit navigation timing log");
+    return;
+  }
+
+  const attributes: KeyValue[] = [];
+  addAttribute(attributes, EVENT_NAME, EVENT_NAMES.NAVIGATION_TIMING);
+
+  const bodyAttributes: KeyValue[] = [];
+  addAttribute(bodyAttributes, "name", nt.name);
+  addNavigationTiming(bodyAttributes, nt, "responseStatus");
+
+  addNavigationTiming(bodyAttributes, nt, "fetchStart");
+  addNavigationTiming(bodyAttributes, nt, "requestStart");
+  addNavigationTiming(bodyAttributes, nt, "responseStart");
+  addNavigationTiming(bodyAttributes, nt, "domInteractive");
+  addNavigationTiming(bodyAttributes, nt, "domContentLoadedEventEnd");
+  addNavigationTiming(bodyAttributes, nt, "domComplete");
+  addNavigationTiming(bodyAttributes, nt, "loadEventEnd");
+
+  addNavigationTiming(bodyAttributes, nt, "transferSize");
+  addNavigationTiming(bodyAttributes, nt, "encodedBodySize");
+  addNavigationTiming(bodyAttributes, nt, "decodedBodySize");
+
+  const log: LogRecord = {
+    timeUnixNano: getStartTimeUnixNanos(),
+    attributes: attributes,
+    severityNumber: LOG_SEVERITIES.INFO,
+    severityText: "INFO",
+    body: {
+      kvlistValue: {
+        values: bodyAttributes,
+      },
+    },
+  };
+  addCommonAttributes(log.attributes);
+
+  const traceContext = getTraceContextForPageLoad();
+  if (traceContext) {
+    log.traceId = traceContext.traceId;
+    log.spanId = traceContext.spanId;
+  }
+
+  sendLog(log);
+}
+
+function addNavigationTiming(attributes: KeyValue[], nt: PerformanceNavigationTiming, field: string) {
+  // @ts-expect-error index access not recognized by TS, but this makes the code more reusable
+  const value = nt[field];
+  if (typeof value === "number" && !isNaN(value)) {
+    addAttribute(attributes, field, Number.isInteger(value) ? value : roundToTwoDecimals(value));
+  }
+}
+
+function getStartTimeUnixNanos(): string {
+  return toNanosTs(Math.round(getTimeOrigin()));
+}

package/src/instrumentations/navigation/page-transition.ts

@@ -0,0 +1,100 @@
+import { debug, nowNanos, win, wrap } from "../../utils";
+import { vars } from "../../vars";
+import { transmitPageViewEvent } from "./event";
+
+type LocationState = Partial<{
+  path: string;
+  search: string;
+  hash: string;
+}>;
+
+let currentLocation: LocationState = {};
+let shouldIncludeHashChanges = false;
+let shouldIncludeSearchChanges = false;
+
+/**
+ * Tracks page transitions (virtual page views) as per this OTel spec:
+ * https://github.com/open-telemetry/semantic-conventions/pull/1910/files
+ *
+ * Notable difference: The full URL is transmitted as a signal attribute.
+ */
+export function startPageTransitionInstrumentation() {
+  if (!win || !win.history) {
+    debug("Browser does not support history API, skipping instrumentation");
+    return;
+  }
+
+  if (!vars.pageViewInstrumentation.trackVirtualPageViews) {
+    return;
+  }
+
+  shouldIncludeSearchChanges = vars.pageViewInstrumentation.includeParts?.includes("SEARCH") ?? false;
+  shouldIncludeHashChanges = vars.pageViewInstrumentation.includeParts?.includes("HASH") ?? false;
+
+  /**
+   * Not wrapping history.go, history.backward and history.forward here, because their call signatures don't receive
+   * url information. For these cases we can use the popstate and hashchange events.
+   */
+  wrap(
+    win.history,
+    "replaceState",
+    (original) =>
+      function (this: History, state, unused, url) {
+        onUrlChange(url ? String(url) : undefined, true);
+        return original.apply(this, [state, unused, url]);
+      }
+  );
+  wrap(
+    win.history,
+    "pushState",
+    (original) =>
+      function (this: History, state, unused, url) {
+        onUrlChange(url ? String(url) : undefined);
+        return original.apply(this, [state, unused, url]);
+      }
+  );
+
+  win.addEventListener("hashchange", onHashChange);
+  win.addEventListener("popstate", onPopState);
+
+  try {
+    updateCurrentLocation(new URL(win.location.href));
+  } catch {}
+}
+
+function onPopState() {
+  // popState event is fired after the location entry has been updated, so the location should already contain the new url.
+  onUrlChange(win?.location.href);
+}
+
+function onHashChange(event: HashChangeEvent) {
+  onUrlChange(event.newURL);
+}
+
+function onUrlChange(url?: string, replaced?: boolean) {
+  if (!url) return;
+
+  try {
+    const parsedUrl = new URL(url, win?.location.href);
+    if (isLocationChange(parsedUrl)) {
+      updateCurrentLocation(parsedUrl);
+      transmitPageViewEvent(nowNanos(), parsedUrl, true, Boolean(replaced));
+    }
+  } catch (e) {
+    debug("Failed to handle url change", e);
+  }
+}
+
+function updateCurrentLocation(url: URL) {
+  currentLocation.path = url.pathname;
+  currentLocation.search = url.search;
+  currentLocation.hash = url.hash;
+}
+
+function isLocationChange(newUrl: URL) {
+  return (
+    newUrl.pathname !== currentLocation.path ||
+    (shouldIncludeSearchChanges && newUrl.search !== currentLocation.search) ||
+    (shouldIncludeHashChanges && newUrl.hash !== currentLocation.hash)
+  );
+}

package/src/instrumentations/web-vitals.ts

@@ -0,0 +1,37 @@
+import { onLCP, onINP, onCLS, Metric } from "web-vitals";
+import { KeyValue, LogRecord } from "../../types/otlp";
+import { EVENT_NAME, EVENT_NAMES, LOG_SEVERITIES } from "../semantic-conventions";
+import { nowNanos, roundToTwoDecimals } from "../utils";
+import { sendLog } from "../transport";
+import { addAttribute } from "../utils/otel";
+import { addCommonAttributes } from "../attributes";
+
+export function startWebVitalsInstrumentation() {
+  onLCP(onWebVital);
+  onINP(onWebVital);
+  onCLS(onWebVital);
+}
+
+function onWebVital(metric: Metric) {
+  const attributes: KeyValue[] = [];
+  addAttribute(attributes, EVENT_NAME, EVENT_NAMES.WEB_VITAL);
+
+  const bodyAttributes: KeyValue[] = [];
+  addAttribute(bodyAttributes, "name", metric.name);
+  addAttribute(bodyAttributes, "value", roundToTwoDecimals(metric.value));
+  addAttribute(bodyAttributes, "delta", roundToTwoDecimals(metric.delta));
+
+  const log: LogRecord = {
+    timeUnixNano: nowNanos(),
+    attributes: attributes,
+    severityNumber: LOG_SEVERITIES.INFO,
+    severityText: "INFO",
+    body: {
+      kvlistValue: {
+        values: bodyAttributes,
+      },
+    },
+  };
+  addCommonAttributes(log.attributes);
+  sendLog(log);
+}

package/src/semantic-conventions.ts

@@ -0,0 +1,91 @@
+// Resource Attribute Keys
+export const SERVICE_NAME = "service.name";
+export const SERVICE_VERSION = "service.version";
+export const DEPLOYMENT_ENVIRONMENT_NAME = "deployment.environment.name";
+export const DEPLOYMENT_NAME = "deployment.name";
+export const DEPLOYMENT_ID = "deployment.id";
+
+// Misc Signal Attribute Keys
+export const EVENT_NAME = "event.name";
+export const EVENT_TITLE = "dash0.event.title";
+export const PAGE_LOAD_ID = "page.load.id";
+export const SESSION_ID = "session.id";
+export const USER_AGENT = "user_agent.original";
+export const BROWSER_TAB_ID = "browser.tab.id";
+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";
+
+// User Attribute Keys
+export const USER_ID = "user.id";
+export const USER_NAME = "user.name";
+export const USER_FULL_NAME = "user.full_name";
+export const USER_EMAIL = "user.email";
+export const USER_HASH = "user.hash";
+export const USER_ROLES = "user.roles";
+
+// Exception Attribute Keys
+export const EXCEPTION_MESSAGE = "exception.message";
+export const EXCEPTION_TYPE = "exception.type";
+export const EXCEPTION_STACKTRACE = "exception.stacktrace";
+
+// URL Attribute Keys
+export const URL_DOMAIN = "url.domain";
+export const URL_FRAGMENT = "url.fragment";
+export const URL_FULL = "url.full";
+export const URL_PATH = "url.path";
+export const URL_QUERY = "url.query";
+export const URL_SCHEME = "url.scheme";
+
+// Http Attribute Keys
+export const HTTP_REQUEST_METHOD = "http.request.method";
+export const HTTP_REQUEST_METHOD_ORIGINAL = "http.request.method_original";
+export const HTTP_REQUEST_HEADER = "http.request.header";
+export const HTTP_RESPONSE_STATUS_CODE = "http.response.status_code";
+export const HTTP_RESPONSE_HEADER = "http.response.header";
+export const HTTP_RESPONSE_BODY_SIZE = "http.response.body.size";
+
+// Event Names
+export const EVENT_NAMES = {
+  PAGE_VIEW: "browser.page_view",
+  NAVIGATION_TIMING: "browser.navigation_timing",
+  WEB_VITAL: "browser.web_vital",
+  ERROR: "browser.error",
+};
+export const SPAN_EVENT_NAME_EXCEPTION = "exception";
+
+// Log Severities
+export const LOG_SEVERITIES = {
+  UNSPECIFIED: 0,
+  TRACE: 1,
+  DEBUG: 5,
+  INFO: 9,
+  WARN: 13,
+  ERROR: 17,
+  FATAL: 21,
+};
+export type LOG_SEVERITY_TEXT = keyof typeof LOG_SEVERITIES;
+export type LOG_SEVERITY_NUMBER = (typeof LOG_SEVERITIES)[LOG_SEVERITY_TEXT];
+
+// Page View Event Attributes
+// SEE: https://github.com/open-telemetry/semantic-conventions/pull/1910/files
+export const PAGE_VIEW_TYPE = "type";
+export const PAGE_VIEW_TYPE_VALUES = {
+  INITIAL: 0,
+  VIRTUAL: 1,
+};
+export const PAGE_VIEW_CHANGE_STATE = "change_state";
+export const PAGE_VIEW_CHANGE_STATE_VALUES = {
+  PUSH: "pushState",
+  REPLACE: "replaceState",
+};
+
+// Span Status
+export const SPAN_STATUS_UNSET = 0;
+export const SPAN_STATUS_OK = 1; // This is here for completion, status ok is reserved for use by application developers
+export const SPAN_STATUS_ERROR = 2;
+
+// Span Kind
+// See: https://github.com/open-telemetry/opentelemetry-proto/blob/ac3242b03157295e4ee9e616af53b81517b06559/opentelemetry/proto/trace/v1/trace.proto#L143-L169
+export const SPAN_KIND_CLIENT = 3;

package/src/transport/batcher.ts

@@ -0,0 +1,59 @@
+import { onLastChance } from "../utils/on-last-chance";
+import { doc } from "../utils";
+import { setTimeout } from "../utils/timers";
+
+const SCHEDULE_DELAY_MILLIS = 1000;
+const MAX_QUEUE_SIZE = 15;
+
+export type Batcher<T> = {
+  send(item: T): void;
+};
+
+export function newBatcher<T>(sendInternal: (items: T[]) => void): Batcher<T> {
+  const queuedItems: T[] = [];
+  let pendingFlushTimeout: ReturnType<typeof setTimeout> | null;
+
+  // We attempt batching of messages to be more efficient on the client, network and
+  // server-side. While the connection is either a persistent HTTP 2 connection or
+  // an HTTP 1.1 connection with keep-alive, there is still some overhead involved
+  // in having many small messages.
+  //
+  // For this reason we attempt batching. When batching we must be careful to
+  // force a transmission when the document is unloaded.
+  onLastChance(flush);
+
+  return {
+    send(item: T): void {
+      if (isWindowHidden()) {
+        // We cannot guarantee that we will ever get time to transmit data in a batched
+        // format when the window is hidden, as this might occur while the document is
+        // being unloaded. Immediately force a transmission in these cases.
+        sendInternal([item]);
+        return;
+      }
+
+      queuedItems.push(item);
+      if (queuedItems.length >= MAX_QUEUE_SIZE) {
+        flush();
+      } else if (pendingFlushTimeout == null) {
+        pendingFlushTimeout = setTimeout(flush, SCHEDULE_DELAY_MILLIS);
+      }
+    },
+  };
+
+  function flush() {
+    if (pendingFlushTimeout != null) {
+      clearTimeout(pendingFlushTimeout);
+      pendingFlushTimeout = null;
+    }
+
+    if (queuedItems.length > 0) {
+      sendInternal(queuedItems.slice());
+      queuedItems.length = 0;
+    }
+  }
+}
+
+function isWindowHidden() {
+  return doc?.visibilityState !== "visible";
+}

package/src/transport/fetch.ts

@@ -0,0 +1,72 @@
+import { vars } from "../vars";
+import { noop, warn, fetch } from "../utils";
+
+const BEACON_BODY_SIZE_LIMIT = 60000;
+
+export async function send(path: string, body: unknown): Promise<void> {
+  const jsonString = JSON.stringify(body);
+  let requestBody: ArrayBuffer | string = jsonString;
+  let byteLength = jsonString.length;
+  let isCompressed = false;
+
+  // Try to compress if supported
+  if (typeof CompressionStream !== "undefined") {
+    requestBody = await compressWithGzip(jsonString);
+    byteLength = requestBody.byteLength;
+    isCompressed = true;
+  }
+
+  // Send to all endpoints in parallel
+  await Promise.all(
+    vars.endpoints.map(async (endpoint) => {
+      try {
+        const url = new URL(endpoint["url"]);
+        url.pathname = url.pathname + (url.pathname.endsWith("/") ? path.substring(1) : path);
+
+        const headers: HeadersInit = {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${endpoint["authToken"]}`,
+        };
+
+        if (endpoint.dataset) {
+          headers["Dash0-Dataset"] = endpoint["dataset"];
+        }
+
+        // Try to compress if supported
+        if (isCompressed) {
+          headers["Content-Encoding"] = "gzip";
+        }
+
+        if (!fetch) {
+          warn("Unable to send telemetry, fetch is not defined");
+          return;
+        }
+
+        const response = await fetch(url, {
+          method: "POST",
+          headers,
+          body: requestBody,
+
+          // The keepalive flag is related to the window.sendBeacon API. This in turn has size limitations.
+          keepalive: byteLength <= BEACON_BODY_SIZE_LIMIT,
+        });
+
+        // read the body so the connection can be closed
+        response.text().catch(noop);
+
+        if (!response.ok) {
+          warn(`Failed to send telemetry to ${url}: ${response.status} ${response.statusText}`);
+        }
+      } catch (error) {
+        warn(`Error sending telemetry to ${endpoint.url}${path}:`, error);
+      }
+    })
+  );
+}
+
+async function compressWithGzip(data: string): Promise<ArrayBuffer> {
+  const blob = new Blob([data]);
+  const stream = blob.stream();
+  const compressedStream = stream.pipeThrough(new CompressionStream("gzip"));
+  return new Response(compressedStream).arrayBuffer();
+}

package/src/transport/index.ts

@@ -0,0 +1,77 @@
+import { ExportLogsServiceRequest, ExportTraceServiceRequest, LogRecord, Span } from "../../types/otlp";
+import { newBatcher } from "./batcher";
+import { send } from "./fetch";
+import { vars } from "../vars";
+import { createRateLimiter } from "../utils/rate-limit";
+import { debug, error } from "../utils";
+
+const logBatcher = newBatcher<LogRecord>(sendLogs);
+const spanBatcher = newBatcher<Span>(sendSpans);
+
+let rateLimiter: (() => boolean) | undefined;
+
+function isRateLimited() {
+  if (!rateLimiter) {
+    rateLimiter = createRateLimiter({
+      maxCalls: 8096,
+      maxCallsPerTenMinutes: 4096,
+      maxCallsPerTenSeconds: 128,
+    });
+  }
+
+  return rateLimiter();
+}
+
+export function sendLog(log: LogRecord): void {
+  if (isRateLimited()) {
+    debug("Transport rate limit. Will not send item.", log);
+    return;
+  }
+
+  logBatcher.send(log);
+}
+
+function sendLogs(logs: LogRecord[]): void {
+  send("/v1/logs", {
+    resourceLogs: [
+      {
+        resource: vars.resource,
+        scopeLogs: [
+          {
+            scope: vars.scope,
+            logRecords: logs,
+          },
+        ],
+      },
+    ],
+  } satisfies ExportLogsServiceRequest).catch((err) => {
+    error("Failed to transmit logs", err);
+  });
+}
+
+export function sendSpan(span: Span): void {
+  if (isRateLimited()) {
+    debug("Transport rate limit. Will not send item.", span);
+    return;
+  }
+
+  spanBatcher.send(span);
+}
+
+function sendSpans(spans: Span[]): void {
+  send("/v1/traces", {
+    resourceSpans: [
+      {
+        resource: vars.resource,
+        scopeSpans: [
+          {
+            scope: vars.scope,
+            spans: spans,
+          },
+        ],
+      },
+    ],
+  } satisfies ExportTraceServiceRequest).catch((err) => {
+    error("Failed to transmit spans", err);
+  });
+}

package/src/utils/constants.ts

@@ -0,0 +1,3 @@
+export const NO_VALUE_FALLBACK = "undefined";
+
+export const INIT_MESSAGE = "Initializing Dash0 Web SDK";

package/src/utils/debug.ts

@@ -0,0 +1,25 @@
+import { noop } from "./fn";
+
+type Logger = (...args: any[]) => void;
+
+export const log: Logger = createLogger("log");
+export const info: Logger = createLogger("info");
+export const warn: Logger = createLogger("warn");
+export const error: Logger = createLogger("error");
+export const debug: Logger = createLogger("debug");
+
+function createLogger(method: Extract<keyof Console, "log" | "info" | "warn" | "error" | "debug">): Logger {
+  if (typeof console === "undefined" || typeof console.log !== "function" || typeof console.log.apply !== "function") {
+    return noop;
+  }
+
+  if (console[method] && typeof console[method].apply === "function") {
+    return function () {
+      console[method].apply(console, arguments as any);
+    };
+  }
+
+  return function () {
+    console.log.apply(console, arguments as any);
+  };
+}

package/src/utils/fn.ts

@@ -0,0 +1,3 @@
+export function noop() {
+  // This function is intentionally empty.
+}

package/src/utils/globals.ts

@@ -0,0 +1,42 @@
+// aliasing globals for improved minification
+
+/* eslint-disable no-restricted-globals */
+
+export type WindowType = typeof window;
+
+// Avoid blowing up in an ssr context. It is important to check via typeof here because window might not even be declared when imported in ssr.
+export const win: typeof window | undefined = typeof window !== "undefined" ? window : undefined;
+export const doc: typeof window.document | undefined = win?.document;
+export const nav: typeof navigator | undefined = win?.navigator;
+export const loc: typeof location | undefined = typeof location !== "undefined" ? location : undefined;
+export const perf =
+  win?.performance || (win as any)?.webkitPerformance || (win as any)?.msPerformance || (win as any)?.mozPerformance;
+export const encodeURIComponent: ((arg: string) => string) | undefined = win?.encodeURIComponent;
+export const fetch = win?.fetch;
+export const localStorage: Storage | null = (function () {
+  try {
+    return win?.localStorage ?? null;
+  } catch {
+    // localStorage access is not permitted in certain security modes, e.g.
+    // when cookies are completely disabled in web browsers.
+    return null;
+  }
+})();
+export const sessionStorage: Storage | null = (function () {
+  try {
+    return win?.sessionStorage ?? null;
+  } catch {
+    // sessionStorage access is not permitted in certain security modes, e.g.
+    // when cookies are completely disabled in web browsers.
+    return null;
+  }
+})();
+
+/**
+ * Exposed via this module to enable testing.
+ */
+export function sendBeacon(url: string, data: string): boolean {
+  return nav?.sendBeacon(url, data) ?? false;
+}
+
+/* eslint-enable no-restricted-globals */

package/src/utils/id.ts

@@ -0,0 +1,17 @@
+export const SPAN_ID_BYTES = 8;
+export const TRACE_ID_BYTES = 16;
+export const PAGE_LOAD_ID_BYTES = TRACE_ID_BYTES;
+export const SESSION_ID_BYTES = TRACE_ID_BYTES;
+export const TAB_ID_BYTES = SPAN_ID_BYTES;
+
+const SHARED_CHAR_CODES_ARRAY = Array(32);
+export function generateUniqueId(byteCount: number): string {
+  for (let i = 0; i < byteCount * 2; i++) {
+    SHARED_CHAR_CODES_ARRAY[i] = Math.floor(Math.random() * 16) + 48;
+    // valid hex characters in the range 48-57 and 97-102
+    if (SHARED_CHAR_CODES_ARRAY[i] >= 58) {
+      SHARED_CHAR_CODES_ARRAY[i] += 39;
+    }
+  }
+  return String.fromCharCode.apply(null, SHARED_CHAR_CODES_ARRAY.slice(0, byteCount * 2));
+}

package/src/utils/id_test.ts

@@ -0,0 +1,41 @@
+import { expect, describe, it } from "vitest";
+import { generateUniqueId } from "./id";
+
+// Create a wrapper function for testing
+function generateId(length: number): string {
+  if (typeof length !== "number") {
+    throw new Error("Length must be a number");
+  }
+
+  if (length < 1) {
+    throw new Error("Length must be greater than 0");
+  }
+
+  return generateUniqueId(Math.ceil(length / 2)).substring(0, length);
+}
+
+describe("generateId", () => {
+  it("returns a string of the expected length", () => {
+    const id = generateId(10);
+    expect(id).toHaveLength(10);
+  });
+
+  it("returns a unique ID on each call", () => {
+    const id1 = generateId(10);
+    const id2 = generateId(10);
+    expect(id1).not.toBe(id2);
+  });
+
+  it("throws an error if length is less than 1", () => {
+    expect(() => generateId(0)).toThrow("Length must be greater than 0");
+  });
+
+  it("throws an error if length is not a number", () => {
+    expect(() => generateId("abc" as any)).toThrow("Length must be a number");
+  });
+
+  it("handles large lengths without errors", () => {
+    const id = generateId(1000);
+    expect(id).toHaveLength(1000);
+  });
+});