@dash0/sdk-web 0.14.1 → 0.16.0

package/src/api/init_test.ts

@@ -1,5 +1,7 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { InitOptions, InstrumentationName } from "../types/options";
+import { PropagatorConfig, Vars } from "../vars";
+import { init as initFun } from "./init";
 
 // Mock all the instrumentation modules
 vi.mock("../instrumentations/web-vitals", () => ({
@@ -18,21 +20,30 @@ 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";
+import { startWebVitalsInstrumentation } from "../instrumentations/web-vitals";
 
 describe("init", () => {
   const baseOptions: InitOptions = {
     serviceName: "test-service",
     endpoint: { url: "https://test-endpoint.com", authToken: "invalid" },
   };
+  let vars: Vars;
+  let init: typeof initFun;
 
-  beforeEach(() => {
+  beforeEach(async () => {
     vi.clearAllMocks();
     // Reset the hasBeenInitialised flag by re-importing the module
     vi.resetModules();
+    // Reset vars state after module reset
+    // since init itself needs vars, this needs to imported again as well.
+    // Otherwise the tests that make assumptions on the vars fail because they use a different reference.
+    const { vars: importedVars } = await import("../vars");
+    const { init: importedInit } = await import("./init");
+    vars = importedVars;
+    init = importedInit;
   });
 
   afterEach(() => {
@@ -41,8 +52,6 @@ describe("init", () => {
 
   describe("instrumentation enablement", () => {
     it("should enable all instrumentations when enabledInstrumentations is undefined", async () => {
-      const { init } = await import("./init");
-
       init({
         ...baseOptions,
         enabledInstrumentations: undefined,
@@ -69,8 +78,6 @@ describe("init", () => {
 
     instrumentations.forEach((instrumentation) => {
       it(`should enable ${instrumentation} instrumentation when present in enabledInstrumentations array`, async () => {
-        const { init } = await import("./init");
-
         init({
           ...baseOptions,
           enabledInstrumentations: [instrumentation],
@@ -87,8 +94,6 @@ describe("init", () => {
       });
 
       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({
@@ -105,4 +110,120 @@ describe("init", () => {
       });
     });
   });
+
+  describe("propagator configuration", () => {
+    it("should set propagators configuration when provided", async () => {
+      const propagators: PropagatorConfig[] = [
+        { type: "traceparent" as const, match: [/.*\/api\/.*/] },
+        { type: "xray" as const, match: [/.*\.amazonaws\.com.*/] },
+      ];
+
+      init({
+        ...baseOptions,
+        propagators,
+      });
+
+      expect(vars.propagators).toEqual(propagators);
+    });
+
+    it("should warn when both propagators and legacy config are provided", async () => {
+      const spyOnWarn = vi.spyOn(console, "warn");
+      const propagators: PropagatorConfig[] = [{ type: "traceparent" as const, match: [/.*\/api\/.*/] }];
+
+      init({
+        ...baseOptions,
+        propagators,
+        propagateTraceHeadersCorsURLs: [/.*\.example\.com.*/],
+      });
+
+      expect(spyOnWarn).toHaveBeenCalledWith(
+        "Both 'propagators' and deprecated 'propagateTraceHeadersCorsURLs' were provided. Using 'propagators' configuration. Please migrate to the new 'propagators' config."
+      );
+      expect(vars.propagators).toEqual(propagators);
+    });
+
+    it("should convert legacy config to new format with deprecation warning", async () => {
+      const spyOnWarn = vi.spyOn(console, "warn");
+      const legacyConfig = [/.*\.example\.com.*/, /.*\.test\.com.*/];
+
+      init({
+        ...baseOptions,
+        propagateTraceHeadersCorsURLs: legacyConfig,
+      });
+
+      expect(spyOnWarn).toHaveBeenCalledWith(
+        "'propagateTraceHeadersCorsURLs' is deprecated. Please use the new 'propagators' configuration."
+      );
+
+      expect(vars.propagators).toEqual([
+        {
+          type: "traceparent",
+          match: [...legacyConfig],
+        },
+      ]);
+    });
+
+    it("should set default propagators when no configuration is provided", async () => {
+      init(baseOptions);
+
+      expect(vars.propagators).toEqual([
+        {
+          type: "traceparent",
+          match: [],
+        },
+      ]);
+    });
+
+    it("should not convert empty legacy config", async () => {
+      const spyOnWarn = vi.spyOn(console, "warn");
+
+      init({
+        ...baseOptions,
+        propagateTraceHeadersCorsURLs: [],
+      });
+
+      expect(spyOnWarn).not.toHaveBeenCalled();
+      expect(vars.propagators).toEqual([
+        {
+          type: "traceparent",
+          match: [],
+        },
+      ]);
+    });
+
+    it("should handle mixed pattern types in propagators", async () => {
+      const spyOnWarn = vi.spyOn(console, "warn");
+
+      const propagators: PropagatorConfig[] = [
+        {
+          type: "traceparent" as const,
+          match: [/.*\/api\/.*/],
+        },
+        {
+          type: "xray" as const,
+          match: [/.*\.amazonaws\.com.*/, /.*\.aws\.com.*/],
+        },
+      ];
+
+      init({
+        ...baseOptions,
+        propagators,
+      });
+
+      expect(vars.propagators).toEqual(propagators);
+      expect(spyOnWarn).not.toHaveBeenCalled();
+    });
+
+    it("should handle empty propagators array", async () => {
+      const spyOnWarn = vi.spyOn(console, "warn");
+
+      init({
+        ...baseOptions,
+        propagators: [],
+      });
+
+      expect(vars.propagators).toEqual([]);
+      expect(spyOnWarn).not.toHaveBeenCalled();
+    });
+  });
 });

package/src/entrypoint/npm-package.ts

@@ -13,7 +13,7 @@ export { reportError } from "../api/report-error";
 // Additional utility types
 export type { AttributeValueType } from "../utils/otel";
 export type { AnyValue } from "../types/otlp";
-export type { PageViewMeta } from "../vars";
+export type { PageViewMeta, PropagatorConfig, PropagatorType } from "../vars";
 export type { UrlAttributeScrubber, UrlAttributeRecord } from "../attributes/url";
 
 export function init(opts: InitOptions): void {

package/src/instrumentations/http/fetch.ts

@@ -3,7 +3,8 @@ import { isUrlIgnored, matchesAny } from "../../utils/ignore-rules";
 import {
   addAttribute,
   setSpanStatus,
-  addTraceContextHttpHeaders,
+  addW3CTraceContextHttpHeaders,
+  addXRayTraceContextHttpHeaders,
   endSpan,
   errorToSpanStatus,
   Exception,
@@ -20,7 +21,7 @@ import {
   SPAN_STATUS_UNSET,
 } from "../../semantic-conventions";
 import { isSameOrigin, wrap, parseUrl } from "../../utils";
-import { vars } from "../../vars";
+import { vars, PropagatorType } from "../../vars";
 import { httpRequestHeaderKey, httpResponseHeaderKey } from "../../utils/otel/http";
 import { sendSpan } from "../../transport";
 import { addResourceNetworkEvents, addResourceSize, HTTP_METHOD_OTHER, isWellKnownHttpMethod } from "./utils";
@@ -72,20 +73,21 @@ function wrapFetch(original: typeof fetch) {
       addAttribute(span.attributes, HTTP_REQUEST_METHOD_ORIGINAL, originalMethod);
     }
 
-    const shouldSetCorrelationHeaders = isSameOrigin(url) || matchesAny(vars.propagateTraceHeadersCorsURLs, url);
+    const propagatorTypes = determinePropagatorTypes(url);
+    const shouldSetCorrelationHeaders = propagatorTypes.length > 0;
     if (shouldSetCorrelationHeaders) {
       if (copyOfInit?.headers) {
         // ensure we have a unified container for the headers
         copyOfInit.headers = new Headers(copyOfInit.headers);
-        addTraceContextHttpHeaders(copyOfInit.headers.append, copyOfInit.headers, span);
+        addTraceContextHttpHeaders(copyOfInit.headers.append, copyOfInit.headers, span, propagatorTypes);
       } else if (input instanceof Request) {
-        addTraceContextHttpHeaders(request.headers.append, request.headers, span);
+        addTraceContextHttpHeaders(request.headers.append, request.headers, span, propagatorTypes);
       } else {
         if (!copyOfInit) {
           copyOfInit = {};
         }
         copyOfInit.headers = new Headers();
-        addTraceContextHttpHeaders(copyOfInit.headers.append, copyOfInit.headers, span);
+        addTraceContextHttpHeaders(copyOfInit.headers.append, copyOfInit.headers, span, propagatorTypes);
       }
     }
 
@@ -196,3 +198,54 @@ function endSpanOnError(span: InProgressSpan, error: Exception) {
   recordException(span, error);
   sendSpan(endSpan(span, errorToSpanStatus(error), undefined));
 }
+
+function determinePropagatorTypes(url: string): PropagatorType[] {
+  const matchingTypes: PropagatorType[] = [];
+  const isUrlSameOrigin = isSameOrigin(url);
+
+  // For same-origin requests, always include traceparent + all configured propagators
+  if (isUrlSameOrigin) {
+    // Always add traceparent for same-origin requests
+    matchingTypes.push("traceparent");
+
+    // Add all other configured propagator types for same-origin requests
+    if (vars.propagators) {
+      for (const propagator of vars.propagators) {
+        if (propagator.type !== "traceparent" && !matchingTypes.includes(propagator.type)) {
+          matchingTypes.push(propagator.type);
+        }
+      }
+    }
+    return matchingTypes;
+  }
+
+  // For cross-origin requests, use new propagators config if available
+  if (vars.propagators) {
+    for (const propagator of vars.propagators) {
+      if (matchesAny(propagator.match, url)) {
+        // Avoid duplicates
+        if (!matchingTypes.includes(propagator.type)) {
+          matchingTypes.push(propagator.type);
+        }
+      }
+    }
+    return matchingTypes;
+  }
+
+  return [];
+}
+
+function addTraceContextHttpHeaders(
+  fn: (name: string, value: string) => void,
+  ctx: unknown,
+  span: InProgressSpan,
+  types: PropagatorType[]
+) {
+  for (const type of types) {
+    if (type === "xray") {
+      addXRayTraceContextHttpHeaders(fn, ctx, span);
+    } else {
+      addW3CTraceContextHttpHeaders(fn, ctx, span);
+    }
+  }
+}

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

@@ -1,8 +1,7 @@
 import { newBatcher } from "./batcher";
 import { send } from "./fetch";
 import { vars } from "../vars";
-import { createRateLimiter } from "../utils/rate-limit";
-import { debug, error } from "../utils";
+import { debug, error, createRateLimiter } from "../utils";
 import { ExportLogsServiceRequest, ExportTraceServiceRequest, LogRecord, Span } from "../types/otlp";
 
 const logBatcher = newBatcher<LogRecord>(sendLogs);
@@ -13,7 +12,6 @@ let rateLimiter: (() => boolean) | undefined;
 function isRateLimited() {
   if (!rateLimiter) {
     rateLimiter = createRateLimiter({
-      maxCalls: 8096,
       maxCallsPerTenMinutes: 4096,
       maxCallsPerTenSeconds: 128,
     });

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/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}`;
+}