@obsrviq/tracker 0.6.0 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@obsrviq/tracker",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -27,7 +27,7 @@
     "@rrweb/types": "2.0.1",
     "fflate": "^0.8.2",
     "rrweb": "2.0.1",
-    "@obsrviq/types": "0.5.0"
+    "@obsrviq/types": "0.6.0"
   },
   "devDependencies": {
     "tsup": "^8.3.5",

package/src/context.ts

@@ -13,6 +13,10 @@ export interface ResolvedConfig {
   noPrivacy: boolean;
   captureNetworkBodies: boolean;
   redactHeaders: string[];
+  /** Propagate a W3C `traceparent` on first-party outbound requests (App Monitor join). */
+  tracePropagation: boolean;
+  /** First-party hosts (besides same-origin) allowed to receive `traceparent`. */
+  traceHosts: string[];
   /** Opt-in: resume the same session for a returning visit within the window. */
   continueSession: boolean;
   /** Inactivity window (ms) for continueSession. */

package/src/index.ts

@@ -22,6 +22,8 @@ const DEFAULTS = {
   noPrivacy: false,
   captureNetworkBodies: false,
   redactHeaders: ['authorization', 'cookie', 'set-cookie'],
+  tracePropagation: false,
+  traceHosts: [] as string[],
   sampleRate: 1.0,
   recordCanvas: false,
   endpoint: 'https://in.lumera.app',

package/src/network.ts

@@ -2,6 +2,7 @@ import type { NetworkEvent, NetworkResourceType, NetworkTiming } from '@obsrviq/
 import type { InstrumentCtx, Teardown } from './context.js';
 import { maskString } from './mask.js';
 import { tokenBucket } from './ratelimit.js';
+import { applyFetchTrace, newTrace, traceIdOf, traceTarget } from './trace.js';
 import { uuid } from './util.js';
 
 const BODY_CAP = 4 * 1024; // 4 KB body preview cap
@@ -19,6 +20,7 @@ const HEADER_ALLOW = new Set([
   'content-encoding',
   'x-request-id',
   'x-correlation-id',
+  'traceparent',
   'server',
   'vary',
 ]);
@@ -337,6 +339,20 @@ function wrapFetch(ctx: InstrumentCtx, tr: TimingResolver, emitNet: EmitNet): Te
     const perfStart = perfNow();
     const method = (init?.method || (input instanceof Request ? input.method : 'GET')).toUpperCase();
     const url = redactUrl(rawUrl);
+    // Trace-context propagation (best-effort, scoped to first-party hosts). Inject
+    // BEFORE reading reqHeaders so the traceparent shows in the captured headers,
+    // and stamp the trace id onto the event so replay ↔ backend trace can join.
+    let traceId: string | undefined;
+    if (traceTarget(rawUrl, ctx.config)) {
+      try {
+        const inj = applyFetchTrace(input, init);
+        input = inj.input;
+        init = inj.init;
+        traceId = inj.traceId || undefined;
+      } catch {
+        /* never let propagation break the request */
+      }
+    }
     const reqHeaders = pickHeaders(
       ctx.config.redactHeaders,
       headerEntries(init?.headers ?? (input instanceof Request ? input.headers : undefined)),
@@ -362,6 +378,7 @@ function wrapFetch(ctx: InstrumentCtx, tr: TimingResolver, emitNet: EmitNet): Te
           ok: false,
           resourceType: 'fetch',
           requestHeaders: reqHeaders,
+          traceId,
           timing,
           ...partial,
         };
@@ -425,6 +442,7 @@ interface XhrMeta {
   perfStart: number;
   reqHeaders: Record<string, string>;
   body?: string;
+  traceId?: string;
 }
 
 function wrapXhr(ctx: InstrumentCtx, tr: TimingResolver, emitNet: EmitNet): Teardown {
@@ -464,6 +482,25 @@ function wrapXhr(ctx: InstrumentCtx, tr: TimingResolver, emitNet: EmitNet): Tear
       meta.startT = ctx.clock.now();
       meta.perfStart = perfNow();
       if (ctx.config.captureNetworkBodies) meta.body = stringifyBody(body);
+      // Trace-context propagation (first-party only). setRequestHeader is valid
+      // here — after open(), before the real send() below. Our own setRequestHeader
+      // patch records it into meta.reqHeaders (traceparent is allowlisted), so a
+      // traceparent the APP already set is visible here: respect it (record its id,
+      // don't re-set — XHR COMBINES duplicate headers into an invalid "v1, v2").
+      if (traceTarget(meta.rawUrl, ctx.config)) {
+        try {
+          const appSet = meta.reqHeaders['traceparent'];
+          if (appSet) {
+            meta.traceId = traceIdOf(appSet) ?? undefined;
+          } else {
+            const tr = newTrace();
+            this.setRequestHeader('traceparent', tr.header);
+            meta.traceId = tr.traceId;
+          }
+        } catch {
+          /* header rejected (e.g. send already dispatched) — skip, never throw */
+        }
+      }
       const finish = (error?: string) => {
         const endT = ctx.clock.now();
         const base: NetworkTiming = {
@@ -501,6 +538,7 @@ function wrapXhr(ctx: InstrumentCtx, tr: TimingResolver, emitNet: EmitNet): Tear
             ok: status >= 200 && status < 400,
             resourceType: 'xhr',
             requestHeaders: meta.reqHeaders,
+            traceId: meta.traceId,
             responseHeaders: respHeaders,
             responseSize,
             requestBody: ctx.config.captureNetworkBodies ? bodyPreview(meta.body, undefined) : undefined,

package/src/trace.ts

@@ -0,0 +1,130 @@
+// W3C Trace Context propagation — stamp a `traceparent` header on FIRST-PARTY
+// outbound fetch/XHR so the backend's OpenTelemetry agent continues the same
+// trace, letting a session replay link to its server-side spans (App Monitor).
+//
+// CORS is the sharp edge: a custom request header on a CROSS-origin call promotes
+// it to a preflighted request, and the browser BLOCKS it unless the server echoes
+// the header in `Access-Control-Allow-Headers`. So we only ever propagate to:
+//   • the page's own origin (same-origin → no CORS at all), and
+//   • hosts the site explicitly allowlists via `traceHosts` (they've confirmed the
+//     server allows `traceparent`).
+// Anything else is left untouched — propagation is strictly best-effort and must
+// never break or block a request.
+
+export interface TraceIds {
+  /** 32-hex W3C trace id (== the backend span's trace_id). */
+  traceId: string;
+  /** 16-hex parent/span id for this outbound request. */
+  spanId: string;
+  /** the ready-to-send `traceparent` header value. */
+  header: string;
+}
+
+function randomHex(bytes: number): string {
+  const arr = new Uint8Array(bytes);
+  if (typeof crypto !== 'undefined' && typeof crypto.getRandomValues === 'function') {
+    crypto.getRandomValues(arr);
+  } else {
+    for (let i = 0; i < bytes; i++) arr[i] = (Math.random() * 256) | 0;
+  }
+  let s = '';
+  for (let i = 0; i < bytes; i++) s += arr[i]!.toString(16).padStart(2, '0');
+  return s;
+}
+
+/** Mint a fresh W3C trace context for one outbound request (sampled flag = 01). */
+export function newTrace(): TraceIds {
+  const traceId = randomHex(16); // 128-bit
+  const spanId = randomHex(8); //  64-bit
+  return { traceId, spanId, header: `00-${traceId}-${spanId}-01` };
+}
+
+interface TraceCfg {
+  tracePropagation: boolean;
+  traceHosts: string[];
+}
+
+/** Should we propagate to this URL? Same-origin always (safe); cross-origin only
+ *  if the host is allowlisted. Non-http(s) and unparseable URLs never match. */
+export function traceTarget(rawUrl: string, cfg: TraceCfg): boolean {
+  if (!cfg.tracePropagation) return false;
+  let u: URL;
+  try {
+    u = new URL(rawUrl, typeof location !== 'undefined' ? location.href : undefined);
+  } catch {
+    return false;
+  }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') return false;
+  if (typeof location !== 'undefined' && u.origin === location.origin) return true;
+  return hostAllowed(u.hostname, cfg.traceHosts);
+}
+
+function hostAllowed(hostname: string, hosts: string[]): boolean {
+  const h = hostname.toLowerCase();
+  for (const raw of hosts) {
+    let entry = String(raw).trim().toLowerCase();
+    if (!entry) continue;
+    if (entry.includes('://')) {
+      try {
+        entry = new URL(entry).hostname;
+      } catch {
+        /* keep the raw string */
+      }
+    }
+    entry = entry.replace(/^\*?\./, ''); // "*.example.com" / ".example.com" → "example.com"
+    if (h === entry || h.endsWith('.' + entry)) return true;
+  }
+  return false;
+}
+
+/** The 32-hex trace id inside a `traceparent` value, or null if malformed. */
+export function traceIdOf(header: string | null | undefined): string | null {
+  if (!header) return null;
+  const parts = header.split('-');
+  return parts.length >= 2 && /^[0-9a-f]{32}$/.test(parts[1]!) ? parts[1]! : null;
+}
+
+/** The traceparent already on this fetch call, honoring fetch's header semantics:
+ *  init.headers (when present) REPLACE a Request's headers, so they win. */
+function existingFetchTraceparent(input: RequestInfo | URL, init: RequestInit | undefined): string | null {
+  const hasInitHeaders = !!init && 'headers' in init && init.headers != null;
+  const src = hasInitHeaders
+    ? (init!.headers as HeadersInit)
+    : input instanceof Request
+      ? input.headers
+      : undefined;
+  if (!src) return null;
+  try {
+    return new Headers(src).get('traceparent');
+  } catch {
+    return null;
+  }
+}
+
+/** Ensure a fetch call carries a `traceparent`, and report the trace id that will
+ *  actually be ON THE WIRE. If the app already set one, we DON'T overwrite it (and
+ *  return ITS id, so the recorded event matches what the backend sees); otherwise
+ *  we mint + inject ours. Total + side-effect-free so a caller can fall back to the
+ *  originals if it throws. */
+export function applyFetchTrace(
+  input: RequestInfo | URL,
+  init: RequestInit | undefined,
+): { input: RequestInfo | URL; init: RequestInit | undefined; traceId: string } {
+  const existing = existingFetchTraceparent(input, init);
+  if (existing) {
+    // Respect the app's own trace context — record its id, change nothing.
+    return { input, init, traceId: traceIdOf(existing) ?? '' };
+  }
+  const tr = newTrace();
+  const hasInitHeaders = !!init && 'headers' in init && init.headers != null;
+  // fetch(Request) with no override headers → rebuild the Request so we don't drop
+  // its own headers. When init.headers IS given, fetch uses THOSE, so inject there.
+  if (input instanceof Request && !hasInitHeaders) {
+    const h = new Headers(input.headers);
+    h.set('traceparent', tr.header);
+    return { input: new Request(input, { headers: h }), init, traceId: tr.traceId };
+  }
+  const h = new Headers((init?.headers as HeadersInit | undefined) ?? undefined);
+  h.set('traceparent', tr.header);
+  return { input, init: { ...(init || {}), headers: h }, traceId: tr.traceId };
+}