@dash0/sdk-web 0.15.0 → 0.16.1

package/src/instrumentations/http/fetch_test.ts

@@ -0,0 +1,191 @@
+import { expect, vi, beforeEach, afterEach } from "vitest";
+import { vars } from "../../vars";
+import { instrumentFetch } from "./fetch";
+
+describe("fetch test", () => {
+  let fetchMock: any;
+
+  beforeEach(() => {
+    fetchMock = vi.fn(() => ({
+      ok: false,
+      headers: new Headers(),
+      status: 200,
+      clone: () => ({
+        body: null,
+      }),
+    }));
+    vi.stubGlobal("fetch", fetchMock);
+    vi.stubGlobal("location", { origin: "http://localhost:3000" });
+  });
+
+  afterEach(() => {
+    vi.resetAllMocks();
+    vars.propagators = undefined;
+  });
+
+  it("should inject traceparent header for cross-origin requests", async () => {
+    vars.propagators = [
+      {
+        type: "traceparent",
+        match: [new RegExp("http://foo.bar/")],
+      },
+    ];
+    instrumentFetch();
+    // eslint-disable-next-line no-restricted-globals
+    await fetch("http://foo.bar/foo");
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    const fetchHeaders = (fetchMock.mock.calls[0]!.at(1)! as { headers: Headers }).headers;
+    expect(fetchHeaders.get("traceparent")).not.toBeNull();
+  });
+
+  it("should inject xray header for cross-origin requests", async () => {
+    vars.propagators = [
+      {
+        type: "xray",
+        match: [new RegExp("http://foo.bar/")],
+      },
+    ];
+    instrumentFetch();
+    // eslint-disable-next-line no-restricted-globals
+    await fetch("http://foo.bar/foo");
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    const fetchHeaders = (fetchMock.mock.calls[0]!.at(1)! as { headers: Headers }).headers;
+    expect(fetchHeaders.get("X-Amzn-Trace-Id")).not.toBeNull();
+  });
+
+  it("should inject both headers for cross-origin requests when both match", async () => {
+    vars.propagators = [
+      {
+        type: "traceparent",
+        match: [new RegExp("http://foo.bar/")],
+      },
+      {
+        type: "xray",
+        match: [new RegExp("http://foo.bar/")],
+      },
+    ];
+    instrumentFetch();
+    // eslint-disable-next-line no-restricted-globals
+    await fetch("http://foo.bar/foo");
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    const fetchHeaders = (fetchMock.mock.calls[0]!.at(1)! as { headers: Headers }).headers;
+    expect(fetchHeaders.get("X-Amzn-Trace-Id")).not.toBeNull();
+    expect(fetchHeaders.get("traceparent")).not.toBeNull();
+  });
+
+  it("should inject no headers for non-matching cross-origin requests", async () => {
+    vars.propagators = [];
+    instrumentFetch();
+    // eslint-disable-next-line no-restricted-globals
+    await fetch("http://foo.bar/foo");
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    const expectedHeaders = undefined;
+    expect(fetchMock).toHaveBeenCalledWith("http://foo.bar/foo", expectedHeaders);
+  });
+
+  // New same-origin behavior tests
+  it("should inject all configured propagator headers for same-origin requests", async () => {
+    vars.propagators = [
+      {
+        type: "traceparent",
+        match: [new RegExp("http://foo.bar/")], // Doesn't match same-origin
+      },
+      {
+        type: "xray",
+        match: [new RegExp("http://baz.com/")], // Doesn't match same-origin
+      },
+    ];
+    instrumentFetch();
+    // Same-origin request
+    // eslint-disable-next-line no-restricted-globals
+    await fetch("http://localhost:3000/api/test");
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    const fetchHeaders = (fetchMock.mock.calls[0]!.at(1)! as { headers: Headers }).headers;
+    // Both headers should be present for same-origin, regardless of match patterns
+    expect(fetchHeaders.get("traceparent")).not.toBeNull();
+    expect(fetchHeaders.get("X-Amzn-Trace-Id")).not.toBeNull();
+  });
+
+  it("should inject only traceparent for same-origin when only traceparent propagator configured", async () => {
+    vars.propagators = [
+      {
+        type: "traceparent",
+        match: [new RegExp("http://foo.bar/")],
+      },
+    ];
+    instrumentFetch();
+    // Same-origin request
+    // eslint-disable-next-line no-restricted-globals
+    await fetch("http://localhost:3000/api/test");
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    const fetchHeaders = (fetchMock.mock.calls[0]!.at(1)! as { headers: Headers }).headers;
+    expect(fetchHeaders.get("traceparent")).not.toBeNull();
+    expect(fetchHeaders.get("X-Amzn-Trace-Id")).toBeNull();
+  });
+
+  it("should inject both traceparent and xray for same-origin when only xray propagator configured", async () => {
+    vars.propagators = [
+      {
+        type: "xray",
+        match: [new RegExp("http://foo.bar/")],
+      },
+    ];
+    instrumentFetch();
+    // Same-origin request
+    // eslint-disable-next-line no-restricted-globals
+    await fetch("http://localhost:3000/api/test");
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    const fetchHeaders = (fetchMock.mock.calls[0]!.at(1)! as { headers: Headers }).headers;
+    // Same-origin always gets traceparent + all configured propagator types
+    expect(fetchHeaders.get("traceparent")).not.toBeNull();
+    expect(fetchHeaders.get("X-Amzn-Trace-Id")).not.toBeNull();
+  });
+
+  it("should inject traceparent for same-origin when default traceparent propagator configured", async () => {
+    vars.propagators = [
+      {
+        type: "traceparent",
+        match: [], // Empty match array - matches no cross-origin URLs but same-origin gets all propagators
+      },
+    ];
+    instrumentFetch();
+    // Same-origin request
+    // eslint-disable-next-line no-restricted-globals
+    await fetch("http://localhost:3000/api/test");
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    const fetchHeaders = (fetchMock.mock.calls[0]!.at(1)! as { headers: Headers }).headers;
+    // Same-origin gets all configured propagator types
+    expect(fetchHeaders.get("traceparent")).not.toBeNull();
+    expect(fetchHeaders.get("X-Amzn-Trace-Id")).toBeNull();
+  });
+
+  it("should follow cross-origin pattern matching for non-same-origin requests", async () => {
+    vars.propagators = [
+      {
+        type: "traceparent",
+        match: [new RegExp("http://foo.bar/")],
+      },
+      {
+        type: "xray",
+        match: [new RegExp("http://baz.com/")],
+      },
+    ];
+    instrumentFetch();
+    // Cross-origin request that matches only traceparent pattern
+    // eslint-disable-next-line no-restricted-globals
+    await fetch("http://foo.bar/api");
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    const fetchHeaders = (fetchMock.mock.calls[0]!.at(1)! as { headers: Headers }).headers;
+    expect(fetchHeaders.get("traceparent")).not.toBeNull();
+    expect(fetchHeaders.get("X-Amzn-Trace-Id")).toBeNull();
+  });
+});

package/src/instrumentations/http/propagator-integration_test.ts

@@ -0,0 +1,93 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { addW3CTraceContextHttpHeaders, addXRayTraceContextHttpHeaders } from "../../utils/otel/trace-context";
+import { InProgressSpan } from "../../utils/otel/span";
+
+describe("Multiple propagator integration", () => {
+  let headers: Record<string, string>;
+  let mockAppend: (name: string, value: string) => void;
+  let mockSpan: InProgressSpan;
+
+  beforeEach(() => {
+    headers = {};
+    mockAppend = (name: string, value: string) => {
+      headers[name] = value;
+    };
+    mockSpan = {
+      traceId: "4efaaf4d1e8720b39541901950019ee5",
+      spanId: "53995c3f42cd8ad8",
+      attributes: [],
+    } as unknown as InProgressSpan;
+  });
+
+  it("should add both W3C traceparent and X-Ray headers when both propagators match", () => {
+    // Simulate what happens when both propagator types are matched
+    const propagatorTypes = ["traceparent", "xray"];
+
+    // Add headers for each type (this simulates addHeadersBasedOnTypes)
+    for (const type of propagatorTypes) {
+      if (type === "xray") {
+        addXRayTraceContextHttpHeaders(mockAppend, {}, mockSpan);
+      } else if (type === "traceparent") {
+        addW3CTraceContextHttpHeaders(mockAppend, {}, mockSpan);
+      }
+    }
+
+    // Verify both headers were added
+    expect(headers).toHaveProperty("traceparent");
+    expect(headers).toHaveProperty("X-Amzn-Trace-Id");
+
+    // Verify header formats
+    expect(headers["traceparent"]).toBe("00-4efaaf4d1e8720b39541901950019ee5-53995c3f42cd8ad8-01");
+    expect(headers["X-Amzn-Trace-Id"]).toBe(
+      "Root=1-4efaaf4d-1e8720b39541901950019ee5;Parent=53995c3f42cd8ad8;Sampled=1"
+    );
+  });
+
+  it("should only add W3C header when only traceparent propagator matches", () => {
+    const propagatorTypes = ["traceparent"];
+
+    for (const type of propagatorTypes) {
+      if (type === "xray") {
+        addXRayTraceContextHttpHeaders(mockAppend, {}, mockSpan);
+      } else if (type === "traceparent") {
+        addW3CTraceContextHttpHeaders(mockAppend, {}, mockSpan);
+      }
+    }
+
+    expect(headers).toHaveProperty("traceparent");
+    expect(headers).not.toHaveProperty("X-Amzn-Trace-Id");
+  });
+
+  it("should only add X-Ray header when only xray propagator matches", () => {
+    const propagatorTypes = ["xray"];
+
+    for (const type of propagatorTypes) {
+      if (type === "xray") {
+        addXRayTraceContextHttpHeaders(mockAppend, {}, mockSpan);
+      } else if (type === "traceparent") {
+        addW3CTraceContextHttpHeaders(mockAppend, {}, mockSpan);
+      }
+    }
+
+    expect(headers).not.toHaveProperty("traceparent");
+    expect(headers).toHaveProperty("X-Amzn-Trace-Id");
+  });
+
+  it("should handle Headers object correctly", () => {
+    const headersObj = new Headers();
+    const propagatorTypes = ["traceparent", "xray"];
+
+    for (const type of propagatorTypes) {
+      if (type === "xray") {
+        addXRayTraceContextHttpHeaders(headersObj.append.bind(headersObj), headersObj, mockSpan);
+      } else if (type === "traceparent") {
+        addW3CTraceContextHttpHeaders(headersObj.append.bind(headersObj), headersObj, mockSpan);
+      }
+    }
+
+    expect(headersObj.get("traceparent")).toBe("00-4efaaf4d1e8720b39541901950019ee5-53995c3f42cd8ad8-01");
+    expect(headersObj.get("X-Amzn-Trace-Id")).toBe(
+      "Root=1-4efaaf4d-1e8720b39541901950019ee5;Parent=53995c3f42cd8ad8;Sampled=1"
+    );
+  });
+});

package/src/transport/index.ts

@@ -47,7 +47,9 @@ function sendLogs(logs: LogRecord[]): void {
   });
 }
 
-export function sendSpan(span: Span): void {
+export function sendSpan(span: Span | undefined): void {
+  if (!span) return;
+
   if (isRateLimited()) {
     debug("Transport rate limit. Will not send item.", span);
     return;

package/src/types/options.ts

@@ -1,6 +1,6 @@
 import { AttributeValueType } from "../utils/otel";
 import { AnyValue } from "./otlp";
-import { Endpoint, Vars } from "../vars";
+import { Endpoint, Vars, PropagatorConfig } from "../vars";
 
 export type InstrumentationName = "@dash0/navigation" | "@dash0/web-vitals" | "@dash0/error" | "@dash0/fetch";
 
@@ -39,6 +39,12 @@ export type InitOptions = {
    * to be expired. Also think of cache time-to-live configuration options.
    */
   sessionTerminationTimeoutMillis?: number;
+
+  /**
+   * Configure trace context propagators for different URL patterns.
+   * Each propagator defines which header type to send for matching URLs.
+   */
+  propagators?: PropagatorConfig[];
 } & Partial<
   Pick<
     Vars,

package/src/utils/index.ts

@@ -8,6 +8,7 @@ export * from "./local-storage";
 export * from "./performance";
 export * from "./rate-limit";
 export * from "./time";
+export * from "./timers";
 export * from "./constants";
 export * from "./math";
 export * from "./origin";

package/src/utils/otel/span.ts

@@ -5,6 +5,7 @@ import { generateTraceId } from "../trace-id";
 import { generateSpanId } from "../span-id";
 import { addAttribute } from "./attributes";
 import { KeyValue, Span, SpanStatus } from "../../types/otlp";
+import { debug } from "../debug";
 
 export type InProgressSpan = Omit<Span, "endTimeUnixNano">;
 
@@ -30,9 +31,23 @@ export function startSpan(name: string): InProgressSpan {
   };
 }
 
-export function endSpan(span: InProgressSpan, status: SpanStatus | undefined, durationNano: number | undefined): Span {
+/**
+ * Ends the span by setting status and endTimeUnixNano on it. If the spand was already previously ended, this returns undefined
+ * to prevent the span from being ended multiple times on accident.
+ */
+export function endSpan(
+  span: InProgressSpan,
+  status: SpanStatus | undefined,
+  durationNano: number | undefined
+): Span | undefined {
   // We cast here to avoid having to instantiate a copy of the span
   const s = span as Span;
+
+  if (s.endTimeUnixNano) {
+    debug("Attempting to end already ended span. Dropping...", s);
+    return undefined;
+  }
+
   if (status) {
     s.status = status;
   }

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

@@ -59,7 +59,7 @@ function getTraceparentFromServerTiming(serverTimings: readonly PerformanceServe
   return "";
 }
 
-export function addTraceContextHttpHeaders(
+export function addW3CTraceContextHttpHeaders(
   fn: (name: string, value: string) => void,
   ctx: unknown,
   span: InProgressSpan
@@ -84,3 +84,32 @@ export function addTraceContextHttpHeaders(
    */
   fn.call(ctx, "traceparent", `00-${span.traceId}-${span.spanId}-01`);
 }
+
+export function addXRayTraceContextHttpHeaders(
+  fn: (name: string, value: string) => void,
+  ctx: unknown,
+  span: InProgressSpan
+) {
+  /**
+   * AWS X-Ray trace header.
+   * General format is Root=${trace-id};Parent=${span-id};Sampled=${sampling-flag}
+   *
+   * Converts W3C trace ID format to X-Ray format:
+   * W3C: 4efaaf4d1e8720b39541901950019ee5 (32 hex chars)
+   * X-Ray: 1-4efaaf4d-1e8720b39541901950019ee5 (1-{8chars}-{24chars})
+   *
+   * References:
+   * https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-tracingheader
+   */
+  const xrayTraceId = convertW3CTraceIdToXRay(span.traceId);
+  const xrayHeader = `Root=${xrayTraceId};Parent=${span.spanId};Sampled=1`;
+  fn.call(ctx, "X-Amzn-Trace-Id", xrayHeader);
+}
+
+function convertW3CTraceIdToXRay(w3cTraceId: string): string {
+  // X-Ray trace ID format: 1-{timestamp}-{unique-id}
+  // Split the 32-char W3C trace ID into 8-char timestamp and 24-char unique ID
+  const timestamp = w3cTraceId.substring(0, 8);
+  const uniqueId = w3cTraceId.substring(8, 32);
+  return `1-${timestamp}-${uniqueId}`;
+}

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

@@ -0,0 +1,59 @@
+import { describe, it, expect } from "vitest";
+import { addXRayTraceContextHttpHeaders } from "./trace-context";
+import { InProgressSpan } from "./span";
+
+describe("X-Ray trace context", () => {
+  it("should generate X-Ray header with correct format", () => {
+    const span = {
+      traceId: "4efaaf4d1e8720b39541901950019ee5",
+      spanId: "53995c3f42cd8ad8",
+    } as InProgressSpan;
+
+    const headers: Record<string, string> = {};
+    const mockAppend = (name: string, value: string) => {
+      headers[name] = value;
+    };
+
+    addXRayTraceContextHttpHeaders(mockAppend, {}, span);
+
+    expect(headers["X-Amzn-Trace-Id"]).toBe(
+      "Root=1-4efaaf4d-1e8720b39541901950019ee5;Parent=53995c3f42cd8ad8;Sampled=1"
+    );
+  });
+
+  it("should convert W3C trace ID to X-Ray format correctly", () => {
+    const span = {
+      traceId: "5759e988bd862e3fe1be46a994272793",
+      spanId: "53995c3f42cd8ad8",
+    } as InProgressSpan;
+
+    const headers: Record<string, string> = {};
+    const mockAppend = (name: string, value: string) => {
+      headers[name] = value;
+    };
+
+    addXRayTraceContextHttpHeaders(mockAppend, {}, span);
+
+    expect(headers["X-Amzn-Trace-Id"]).toBe(
+      "Root=1-5759e988-bd862e3fe1be46a994272793;Parent=53995c3f42cd8ad8;Sampled=1"
+    );
+  });
+
+  it("should handle different span IDs", () => {
+    const span = {
+      traceId: "4efaaf4d1e8720b39541901950019ee5",
+      spanId: "1234567890abcdef",
+    } as InProgressSpan;
+
+    const headers: Record<string, string> = {};
+    const mockAppend = (name: string, value: string) => {
+      headers[name] = value;
+    };
+
+    addXRayTraceContextHttpHeaders(mockAppend, {}, span);
+
+    expect(headers["X-Amzn-Trace-Id"]).toBe(
+      "Root=1-4efaaf4d-1e8720b39541901950019ee5;Parent=1234567890abcdef;Sampled=1"
+    );
+  });
+});

package/src/utils/performance.ts

@@ -7,6 +7,7 @@ import { addEventListener, removeEventListener } from "./listeners";
 const TEN_MINUTES_IN_MILLIS = 1000 * 60 * 10;
 const ONE_DAY_IN_MILLIS = 1000 * 60 * 60 * 24;
 const OBSERVER_WAIT_TIME_MS = 300;
+const MAX_RESOURCES_ENTRIES = 100;
 
 export const isResourceTimingAvailable = !!(perf && perf.getEntriesByType);
 export const isPerformanceObserverAvailable =
@@ -54,7 +55,11 @@ type ObserveResourcePerformanceOptions = {
 
 type PerformanceObservationContoller = {
   start: () => void;
-  end: () => void;
+  /**
+   * Ends performance observation and starts matching the observed resources.
+   * @param endTs End performance timing timestamp to use for the end of the resource, instead of the current time when end is called. Useful when calling end from a timeout handler
+   */
+  end: (endTs?: number) => void;
   cancel: () => void;
 };
 
@@ -99,8 +104,11 @@ export function observeResourcePerformance(opts: ObserveResourcePerformanceOptio
     fallbackEndNeverCalledTimerHandle = setTimeout(disposeGlobalResources, TEN_MINUTES_IN_MILLIS);
   }
 
-  function onEnd() {
-    endTime = perf.now();
+  function onEnd(endTs?: number) {
+    // If endTime is already set, we are already terminating and should not do so again
+    if (endTime) return;
+
+    endTime = endTs ?? perf.now();
     cancelFallbackEndNeverCalledTimer();
 
     if (!isWaitingAcceptable()) {
@@ -136,7 +144,16 @@ export function observeResourcePerformance(opts: ObserveResourcePerformanceOptio
         const entry = e as PerformanceResourceTiming;
         return entry.startTime >= startTime && opts.resourceMatcher(entry);
       })
-      .forEach((entry) => resources.push(entry as PerformanceResourceTiming));
+      .forEach((entry) => {
+        // Limit array size to prevent memory leaks on high-traffic pages
+        if (resources.length >= MAX_RESOURCES_ENTRIES) {
+          // Remove oldest entry (FIFO)
+          // Timings are only reported once the resource is fully recorded (i.e. the request has ended), so timings ending
+          // way before the `onEnd` is called are less likely to be good matches and we can ignore them.
+          resources.shift();
+        }
+        resources.push(entry as PerformanceResourceTiming);
+      });
   }
 
   function onVisibilityChanged() {

package/src/vars.ts

@@ -3,6 +3,13 @@ import { AnyValue, InstrumentationScope, KeyValue, Resource } from "./types/otlp
 import { UrlAttributeScrubber } from "./attributes";
 import { identity } from "./utils";
 
+export type PropagatorType = "traceparent" | "xray";
+
+export type PropagatorConfig = {
+  type: PropagatorType;
+  match: RegExp[];
+};
+
 export type Endpoint = {
   /**
    * OTLP HTTP URL excluding the /v1/* prefix
@@ -108,9 +115,16 @@ export type Vars = {
    */
   wrapTimers: boolean;
 
+  /**
+   * Configure trace context propagators for different URL patterns.
+   * Each propagator defines which header type to send for matching URLs.
+   */
+  propagators?: PropagatorConfig[];
+
   /**
    * An array of URL regular expressions
    * for which trace context headers should be sent across origins by http client instrumentations.
+   * @deprecated Use propagators instead
    */
   propagateTraceHeadersCorsURLs: RegExp[];