@dash0/sdk-web 0.6.2

package/src/utils/ignore-rules.ts

@@ -0,0 +1,59 @@
+import { vars } from "../vars";
+
+export function matchesAny(regexp: RegExp[], s: string) {
+  for (let i = 0, len = regexp.length; i < len; i++) {
+    if (regexp[i]!.test(s)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+const DATA_URL_PREFIX = "data:";
+
+export function isUrlIgnored(url?: string | number): boolean {
+  if (!url) {
+    return true;
+  }
+
+  // Force string conversion. During runtime we have seen that some URLs passed into this code path aren't actually
+  // strings. Reason currently unknown.
+  url = String(url);
+  if (!url) {
+    return true;
+  }
+
+  // We never want to track data URLs. Instead of matching these via regular expressions (which might be expensive),
+  // we are explicitly doing a startsWith ignore case check
+  // https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs
+  if (url.substring == null || url.substring(0, DATA_URL_PREFIX.length).toLowerCase() === DATA_URL_PREFIX) {
+    return true;
+  }
+
+  // Disable monitoring of data transmission requests. The data transmission strategy already ensures
+  // that data transmission requests are not picked up internally. However, we have seen some users
+  // leverage custom (broken) XMLHttpRequest instrumentation to implement application code which
+  // then break the detection of data transmission requests.
+  if (isTransportRequest(url)) {
+    return true;
+  }
+
+  return matchesAny(vars.ignoreUrls, url);
+}
+
+function isTransportRequest(url: string) {
+  const lowerCaseUrl = url.toLowerCase();
+
+  for (let i = 0, len = vars.endpoints.length; i < len; i++) {
+    const endpoint = vars.endpoints[i]!;
+    if (lowerCaseUrl.startsWith(endpoint.url)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export function isErrorMessageIgnored(message?: string) {
+  return !message || matchesAny(vars.ignoreErrorMessages, message);
+}

package/src/utils/index.ts

@@ -0,0 +1,16 @@
+export * from "./debug";
+export * from "./obj";
+export * from "./fn";
+export * from "./globals";
+export * from "./id";
+export * from "./listeners";
+export * from "./local-storage";
+export * from "./performance";
+export * from "./rate-limit";
+export * from "./time";
+export * from "./constants";
+export * from "./math";
+export * from "./origin";
+export * from "./url";
+export * from "./pick";
+export * from "./wrap";

package/src/utils/listeners.ts

@@ -0,0 +1,18 @@
+// aliasing the global function for improved minification and
+// protection against hasOwnProperty overrides.
+
+export function addEventListener(target: EventTarget, eventType: string, callback: (arg: Event) => unknown) {
+  if (target.addEventListener) {
+    target.addEventListener(eventType, callback, false);
+  } else if ((target as any).attachEvent) {
+    (target as any).attachEvent("on" + eventType, callback);
+  }
+}
+
+export function removeEventListener(target: EventTarget, eventType: string, callback: () => unknown) {
+  if (target.removeEventListener) {
+    target.removeEventListener(eventType, callback, false);
+  } else if ((target as any).detachEvent) {
+    (target as any).detachEvent("on" + eventType, callback);
+  }
+}

package/src/utils/local-storage.ts

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

package/src/utils/math.ts

@@ -0,0 +1,3 @@
+export function roundToTwoDecimals(n: number) {
+  return Math.round(n * 100) / 100;
+}

package/src/utils/obj.ts

@@ -0,0 +1,12 @@
+const globalHasOwnProperty = Object.prototype.hasOwnProperty;
+
+/**
+ * protection against hasOwnProperty overrides.
+ */
+export function hasOwnProperty(obj: Record<string, unknown>, key: string) {
+  return globalHasOwnProperty.call(obj, key);
+}
+
+export function hasKey<O extends object>(obj: O, key: string | number | symbol): key is keyof O {
+  return key in obj;
+}

package/src/utils/on-last-chance.ts

@@ -0,0 +1,36 @@
+import { addEventListener } from "./listeners";
+import { doc, win } from "./globals";
+
+let isUnloading = false;
+
+/**
+ * Triggers the `fn` when the HTML document is getting unloaded
+ * (or when it looks like it might be). Useful to flush batch activities.
+ */
+export function onLastChance(fn: () => void) {
+  if (isUnloading) {
+    fn();
+  }
+
+  if (!doc || !win) return;
+
+  addEventListener(doc, "visibilitychange", function () {
+    if (doc!.visibilityState !== "visible") {
+      fn();
+    }
+  });
+
+  addEventListener(win, "pagehide", function () {
+    isUnloading = true;
+    fn();
+  });
+
+  // According to the spec visibilitychange should be a replacement for
+  // beforeunload, but the reality is different (as of 2019-04-17). Chrome will
+  // close tabs without firing visibilitychange. beforeunload on the other hand
+  // is fired.
+  addEventListener(win, "beforeunload", function () {
+    isUnloading = true;
+    fn();
+  });
+}

package/src/utils/origin.ts

@@ -0,0 +1,15 @@
+import { parseUrl } from "./url";
+
+/** Returns the origin if present (if in browser context). */
+function getOrigin(): string | undefined {
+  return typeof location !== "undefined" ? location.origin : undefined;
+}
+
+export function isSameOrigin(url: string) {
+  try {
+    const parsedUrl = parseUrl(url);
+    return parsedUrl.origin === getOrigin();
+  } catch (_e) {
+    return false;
+  }
+}

package/src/utils/otel/attributes.ts

@@ -0,0 +1,67 @@
+import { AnyValue, KeyValue } from "../../../types/otlp";
+
+type PrimitiveAttributeValue = string | number | boolean;
+export type AttributeValueType =
+  | PrimitiveAttributeValue
+  | Array<PrimitiveAttributeValue>
+  | Record<string, PrimitiveAttributeValue>;
+
+const ANY_VALUE_KEYS = [
+  "stringValue",
+  "boolValue",
+  "intValue",
+  "doubleValue",
+  "arrayValue",
+  "kvlistValue",
+  "bytesValue",
+];
+
+function isAnyValue(value: unknown): value is AnyValue {
+  if (value == null || typeof value !== "object") return false;
+
+  const keys = Object.keys(value);
+  return keys.length === 1 && ANY_VALUE_KEYS.includes(keys[0]!);
+}
+
+export function toAnyValue(value: AttributeValueType | AnyValue): AnyValue;
+export function toAnyValue(value?: AttributeValueType | AnyValue): AnyValue | undefined;
+export function toAnyValue(value?: AttributeValueType | AnyValue): AnyValue | undefined {
+  if (value == null) {
+    return undefined;
+  }
+
+  let anyValue: AnyValue = {};
+  if (Array.isArray(value)) {
+    anyValue["arrayValue"] = { values: value.map((e) => toAnyValue(e)) };
+  } else if (typeof value === "string") {
+    anyValue["stringValue"] = value;
+  } else if (typeof value === "number") {
+    anyValue["doubleValue"] = value;
+  } else if (typeof value === "boolean") {
+    anyValue["boolValue"] = value;
+  } else if (isAnyValue(value)) {
+    anyValue = value;
+  } else if (typeof value === "object") {
+    anyValue["kvlistValue"] = { values: Object.entries(value).map(([key, value]) => toKeyValue(key, value)) };
+  }
+
+  return anyValue;
+}
+
+export function toKeyValue(key: string, value: AttributeValueType | AnyValue): KeyValue {
+  return {
+    key: key,
+    value: toAnyValue(value),
+  };
+}
+
+export function addAttribute(attributes: KeyValue[], key: string, value: AttributeValueType | AnyValue) {
+  attributes.push(toKeyValue(key, value));
+}
+
+export function removeAttribute(attributes: KeyValue[], key: string) {
+  const index = attributes.findIndex((attr) => attr["key"] === key);
+  if (index !== -1) {
+    attributes.splice(index, 1);
+  }
+}

package/src/utils/otel/attributes_test.ts

@@ -0,0 +1,181 @@
+import { expect, describe, it } from "vitest";
+import { toAnyValue } from "./attributes";
+import { AnyValue } from "../../../types/otlp";
+
+describe("toAnyValue", () => {
+  describe("primitive values", () => {
+    it("converts string values to stringValue", () => {
+      const result = toAnyValue("hello");
+      expect(result).toEqual({ stringValue: "hello" });
+    });
+
+    it("converts number values to doubleValue", () => {
+      const result = toAnyValue(42);
+      expect(result).toEqual({ doubleValue: 42 });
+    });
+
+    it("converts boolean true to boolValue", () => {
+      const result = toAnyValue(true);
+      expect(result).toEqual({ boolValue: true });
+    });
+
+    it("converts boolean false to boolValue", () => {
+      const result = toAnyValue(false);
+      expect(result).toEqual({ boolValue: false });
+    });
+
+    it("converts zero to doubleValue", () => {
+      const result = toAnyValue(0);
+      expect(result).toEqual({ doubleValue: 0 });
+    });
+
+    it("converts negative numbers to doubleValue", () => {
+      const result = toAnyValue(-123.45);
+      expect(result).toEqual({ doubleValue: -123.45 });
+    });
+
+    it("converts empty string to stringValue", () => {
+      const result = toAnyValue("");
+      expect(result).toEqual({ stringValue: "" });
+    });
+  });
+
+  describe("array values", () => {
+    it("converts array of strings to arrayValue", () => {
+      const result = toAnyValue(["a", "b", "c"]);
+      expect(result).toEqual({
+        arrayValue: {
+          values: [{ stringValue: "a" }, { stringValue: "b" }, { stringValue: "c" }],
+        },
+      });
+    });
+
+    it("converts array of numbers to arrayValue", () => {
+      const result = toAnyValue([1, 2, 3]);
+      expect(result).toEqual({
+        arrayValue: {
+          values: [{ doubleValue: 1 }, { doubleValue: 2 }, { doubleValue: 3 }],
+        },
+      });
+    });
+
+    it("converts array of booleans to arrayValue", () => {
+      const result = toAnyValue([true, false]);
+      expect(result).toEqual({
+        arrayValue: {
+          values: [{ boolValue: true }, { boolValue: false }],
+        },
+      });
+    });
+
+    it("converts mixed array to arrayValue", () => {
+      const result = toAnyValue([1, "hello", true]);
+      expect(result).toEqual({
+        arrayValue: {
+          values: [{ doubleValue: 1 }, { stringValue: "hello" }, { boolValue: true }],
+        },
+      });
+    });
+
+    it("converts empty array to arrayValue", () => {
+      const result = toAnyValue([]);
+      expect(result).toEqual({
+        arrayValue: {
+          values: [],
+        },
+      });
+    });
+  });
+
+  describe("object values", () => {
+    it("converts simple object to kvlistValue", () => {
+      const result = toAnyValue({ name: "John", age: 30 });
+      expect(result).toEqual({
+        kvlistValue: {
+          values: [
+            { key: "name", value: { stringValue: "John" } },
+            { key: "age", value: { doubleValue: 30 } },
+          ],
+        },
+      });
+    });
+
+    it("converts empty object to kvlistValue", () => {
+      const result = toAnyValue({});
+      expect(result).toEqual({
+        kvlistValue: {
+          values: [],
+        },
+      });
+    });
+
+    it("converts object with mixed value types", () => {
+      const result = toAnyValue({
+        str: "text",
+        num: 42,
+        bool: true,
+      });
+      expect(result).toEqual({
+        kvlistValue: {
+          values: [
+            { key: "str", value: { stringValue: "text" } },
+            { key: "num", value: { doubleValue: 42 } },
+            { key: "bool", value: { boolValue: true } },
+          ],
+        },
+      });
+    });
+  });
+
+  describe("AnyValue passthrough", () => {
+    it("returns existing AnyValue unchanged", () => {
+      const anyValue: AnyValue = { stringValue: "test" };
+      const result = toAnyValue(anyValue);
+      expect(result).toBe(anyValue);
+    });
+
+    it("returns existing doubleValue AnyValue unchanged", () => {
+      const anyValue: AnyValue = { doubleValue: 123 };
+      const result = toAnyValue(anyValue);
+      expect(result).toBe(anyValue);
+    });
+
+    it("returns existing boolValue AnyValue unchanged", () => {
+      const anyValue: AnyValue = { boolValue: false };
+      const result = toAnyValue(anyValue);
+      expect(result).toBe(anyValue);
+    });
+
+    it("returns existing arrayValue AnyValue unchanged", () => {
+      const anyValue: AnyValue = {
+        arrayValue: {
+          values: [{ stringValue: "test" }],
+        },
+      };
+      const result = toAnyValue(anyValue);
+      expect(result).toBe(anyValue);
+    });
+
+    it("returns existing kvlistValue AnyValue unchanged", () => {
+      const anyValue: AnyValue = {
+        kvlistValue: {
+          values: [{ key: "test", value: { stringValue: "value" } }],
+        },
+      };
+      const result = toAnyValue(anyValue);
+      expect(result).toBe(anyValue);
+    });
+  });
+
+  describe("undefined and null handling", () => {
+    it("returns undefined for undefined", () => {
+      const result = toAnyValue(undefined);
+      expect(result).toBeUndefined();
+    });
+
+    it("returns undefined for null", () => {
+      const result = toAnyValue(null as any);
+      expect(result).toBeUndefined();
+    });
+  });
+});

package/src/utils/otel/error.ts

@@ -0,0 +1,63 @@
+import { addSpanEvent, InProgressSpan } from "./span";
+import { KeyValue, SpanStatus } from "../../../types/otlp";
+import { addAttribute } from "./attributes";
+import {
+  SPAN_EVENT_NAME_EXCEPTION,
+  EXCEPTION_MESSAGE,
+  EXCEPTION_STACKTRACE,
+  EXCEPTION_TYPE,
+  SPAN_STATUS_ERROR,
+} from "../../semantic-conventions";
+
+interface ExceptionWithCode {
+  code: string | number;
+  name?: string;
+  message?: string;
+  stack?: string;
+}
+
+interface ExceptionWithMessage {
+  code?: string | number;
+  message: string;
+  name?: string;
+  stack?: string;
+}
+
+interface ExceptionWithName {
+  code?: string | number;
+  message?: string;
+  name: string;
+  stack?: string;
+}
+
+export type Exception = ExceptionWithCode | ExceptionWithMessage | ExceptionWithName | string;
+
+export function recordException(span: InProgressSpan, exception: Exception) {
+  const attributes: KeyValue[] = [];
+
+  if (typeof exception === "string") {
+    addAttribute(attributes, EXCEPTION_MESSAGE, exception);
+  } else if (exception) {
+    if (exception.code) {
+      addAttribute(attributes, EXCEPTION_TYPE, exception.code.toString());
+    } else if (exception.name) {
+      addAttribute(attributes, EXCEPTION_TYPE, exception.name);
+    }
+
+    if (exception.message) {
+      addAttribute(attributes, EXCEPTION_MESSAGE, exception.message);
+    }
+    if (exception.stack) {
+      addAttribute(attributes, EXCEPTION_STACKTRACE, exception.stack);
+    }
+
+    addSpanEvent(span, SPAN_EVENT_NAME_EXCEPTION, attributes);
+  }
+}
+
+export function errorToSpanStatus(e: Exception): SpanStatus {
+  return {
+    code: SPAN_STATUS_ERROR,
+    message: e && typeof e === "object" && "message" in e ? (e.message as string) : String(e),
+  };
+}

package/src/utils/otel/http.ts

@@ -0,0 +1,9 @@
+import { HTTP_REQUEST_HEADER, HTTP_RESPONSE_HEADER } from "../../semantic-conventions";
+
+export function httpRequestHeaderKey(key: string) {
+  return `${HTTP_REQUEST_HEADER}.${key.toLowerCase()}`;
+}
+
+export function httpResponseHeaderKey(key: string) {
+  return `${HTTP_RESPONSE_HEADER}.${key.toLowerCase()}`;
+}

package/src/utils/otel/index.ts

@@ -0,0 +1,4 @@
+export * from "./attributes";
+export * from "./trace-context";
+export * from "./span";
+export * from "./error";

package/src/utils/otel/span.ts

@@ -0,0 +1,70 @@
+import { KeyValue, Span, SpanStatus } from "../../../types/otlp";
+import { nowNanos } from "../time";
+import { generateUniqueId, SPAN_ID_BYTES, TRACE_ID_BYTES } from "../id";
+import { SPAN_KIND_CLIENT, SPAN_STATUS_UNSET } from "../../semantic-conventions";
+
+export type InProgressSpan = Omit<Span, "endTimeUnixNano">;
+
+export function startSpan(name: string): InProgressSpan {
+  return {
+    traceId: generateUniqueId(TRACE_ID_BYTES),
+    spanId: generateUniqueId(SPAN_ID_BYTES),
+    name,
+    // Always CLIENT for now https://github.com/open-telemetry/opentelemetry-proto/blob/ac3242b03157295e4ee9e616af53b81517b06559/opentelemetry/proto/trace/v1/trace.proto#L143-L169
+    // Note: we directly define otlp here, this differs from the values used by oteljs internally.
+    kind: SPAN_KIND_CLIENT,
+    startTimeUnixNano: nowNanos(),
+    attributes: [],
+    events: [],
+    links: [],
+    status: { code: SPAN_STATUS_UNSET },
+  };
+}
+
+export function endSpan(span: InProgressSpan, status: SpanStatus | undefined, durationNano: number | undefined): Span {
+  // We cast here to avoid having to instantiate a copy of the span
+  const s = span as Span;
+  if (status) {
+    s.status = status;
+  }
+  s.endTimeUnixNano =
+    durationNano != null ? String(Math.round(parseInt(s.startTimeUnixNano) + durationNano)) : nowNanos();
+  return s;
+}
+
+/**
+ * Adds an event to a span. Can optionally accept the events timestamp and attributes for the event.
+ * The timestamp needs to be specified as nanoseconds since unix epoch in string format.
+ */
+export function addSpanEvent(
+  span: InProgressSpan,
+  name: string,
+  attributesOrTs?: string | KeyValue[] | undefined,
+  attributes?: KeyValue[] | undefined
+) {
+  let ts: string | undefined = undefined;
+  let attr: KeyValue[] | undefined = undefined;
+
+  if (typeof attributesOrTs === "string") {
+    ts = attributesOrTs;
+  } else if (Array.isArray(attributesOrTs)) {
+    attr = attributesOrTs;
+  }
+
+  if (attributes) {
+    attr = attributes;
+  }
+
+  span.events.push({
+    name,
+    timeUnixNano: ts != null ? ts : nowNanos(),
+    attributes: attr ?? [],
+  });
+}
+
+export function setSpanStatus(span: InProgressSpan, code: SpanStatus["code"], message?: string) {
+  span.status = {
+    code,
+    message,
+  };
+}

package/src/utils/otel/trace-context.ts

@@ -0,0 +1,84 @@
+import { doc } from "../globals";
+import { perf } from "../globals";
+import { InProgressSpan } from "./span";
+
+const TRACE_PARENT_HEADER = "traceparent";
+
+type TraceContext = {
+  traceId?: string;
+  spanId?: string;
+};
+
+/**
+ * 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(): TraceContext | undefined {
+  const match =
+    getTraceparentFromMetaElement().match(w3cTraceparentFormat) ||
+    getTraceparentFromNavigationTiming().match(w3cTraceparentFormat);
+  if (match) {
+    return {
+      traceId: match[1],
+      spanId: match[2],
+    };
+  }
+
+  return undefined;
+}
+
+function getTraceparentFromMetaElement(): string {
+  return (
+    Array.from(doc?.getElementsByTagName("meta") ?? [])
+      .find((e) => e.getAttribute("name")?.toLowerCase() === TRACE_PARENT_HEADER)
+      ?.content.trim() || ""
+  );
+}
+
+function getTraceparentFromNavigationTiming(): string {
+  const nt = perf.getEntriesByType("navigation")[0];
+  if (!nt) {
+    return "";
+  }
+
+  if (!nt.serverTiming) {
+    return "";
+  }
+
+  return getTraceparentFromServerTiming(nt.serverTiming);
+}
+
+function getTraceparentFromServerTiming(serverTimings: readonly PerformanceServerTiming[]): string {
+  for (const serverEntry of serverTimings) {
+    if (serverEntry.name === TRACE_PARENT_HEADER) {
+      return serverEntry.description.trim();
+    }
+  }
+
+  return "";
+}
+
+export function addTraceContextHttpHeaders(
+  fn: (name: string, value: string) => void,
+  ctx: unknown,
+  span: InProgressSpan
+) {
+  /**
+   * 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`);
+}