@heystack/otel 0.11.0 → 0.11.1

package/README.md

@@ -376,6 +376,7 @@ stop();
 | `flushEveryEvents` | `number?` | Max buffered events before an early flush (default 200). |
 | `tracing` | `boolean?` | Opt in to **browser distributed tracing** (default off). Emits a real CLIENT span per outbound `fetch` and propagates W3C trace context, so browser→backend calls show as one connected trace + a service-map edge. Independent of replay. |
 | `traceSampleRate` | `number?` | Head sample rate for browser tracing (0–1, default 1 when `tracing` is on). Lower it to cap span volume/cost on busy apps. |
+| `tracePropagationTargets` | `(string \| RegExp)[]?` | Cross-origin backends allowed to receive the `traceparent` header (same-origin always is). Trace context is **never** sent to any other origin, so third-party calls (Clerk, Stripe, analytics) aren't broken by an unexpected CORS preflight. Match by substring/RegExp against the URL, e.g. `["api.myapp.com"]`. **A listed backend must allow `traceparent`/`tracestate` in its CORS `Access-Control-Allow-Headers`.** |
 | `errors` | `boolean?` | Capture uncaught browser errors (`window.onerror` + `unhandledrejection`) as logs. **On by default** — set `false` to disable. Independent of replay/tracing. |
 | `captureConsole` | `'error' \| 'warn' \| false` | Capture `console` output as logs. `'error'` (default) captures `console.error`; `'warn'` captures `console.warn` **and** `console.error`; `false` disables it. Rate-capped + recursion-guarded. |
 | `version` | `string?` | Release identifier → the `service.version` resource attribute on exported browser logs (release attribution / suspect release). |
@@ -390,11 +391,14 @@ await instrumentWeb({
   apiKey: import.meta.env.VITE_HEYSTACK_API_KEY,
   service: "my-web-app",
   tracing: true,
-  traceSampleRate: 0.25, // sample 25% of requests — tune for cost
+  traceSampleRate: 0.25,                      // sample 25% of requests — tune for cost
+  tracePropagationTargets: ["api.myapp.com"], // cross-origin backend(s) to trace through
 });
 ```
 
-It's **cost-aware and safe by design**: off unless you opt in; head-sampled (an unsampled request still propagates `traceparent` with the sampled flag cleared, so the backend makes the same keep/drop decision — no orphaned server spans); and the exporter posts through the *original* `fetch`, never tracing its own upload (no self-export loop). Spans post to `/v1/traces` cross-origin with no CORS setup on your side.
+**Trace headers go to same-origin + your allow-list only — never third parties.** The `traceparent` header is added only to same-origin requests and to URLs matching `tracePropagationTargets`. This is a safety guarantee: injecting `traceparent` on a *cross-origin* request forces a CORS preflight, and a third party that doesn't list the header (Clerk, Stripe, most APIs) **rejects it — breaking that request**. So calls to your own **cross-origin** backend need it added to `tracePropagationTargets`, **and** that backend must allow `traceparent`/`tracestate` in its CORS `Access-Control-Allow-Headers`. Same-origin backends need neither (no CORS involved).
+
+Otherwise it's **cost-aware and safe by design**: off unless you opt in; head-sampled (an unsampled request still propagates `traceparent` with the sampled flag cleared, so the backend makes the same keep/drop decision — no orphaned server spans); and the exporter posts through the *original* `fetch`, never tracing its own upload (no self-export loop). Spans post to `/v1/traces` cross-origin with no CORS setup on your side.
 
 ### Browser error & console collection
 

package/dist/web.d.ts

@@ -89,6 +89,18 @@ export interface InstrumentWebOptions {
     /** Head sample rate for browser tracing (0–1, default 1 when `tracing` is on).
      *  Lower it to control span volume/cost on high-traffic apps. */
     traceSampleRate?: number;
+    /**
+     * Cross-origin backend URLs that may receive the `traceparent` header, in
+     * addition to same-origin (which always does). Trace context is NEVER sent to an
+     * origin outside this list, so third-party calls (Clerk, Stripe, analytics, CDNs)
+     * are not broken by an unexpected CORS preflight. Match by substring or RegExp
+     * against the request URL, e.g. `["api.myapp.com"]`.
+     *
+     * IMPORTANT: a listed backend MUST allow `traceparent` (and `tracestate`) in its
+     * CORS `Access-Control-Allow-Headers`, or its own requests will be preflight-
+     * rejected too. Same-origin calls need no CORS and are unaffected.
+     */
+    tracePropagationTargets?: (string | RegExp)[];
     /**
      * Capture uncaught browser errors (`window.onerror` + `unhandledrejection`) and
      * export them as OTLP logs (`event.name=browser.error`, ERROR severity, with
@@ -128,9 +140,24 @@ export declare class ActiveTraceRef {
         spanId: string;
     } | undefined;
 }
+/**
+ * Decide whether to attach trace headers (`traceparent`) to an outbound request.
+ * Same-origin is always propagated; a CROSS-origin request is propagated ONLY if
+ * its URL matches an explicit target.
+ *
+ * This is critical for correctness: adding the non-safelisted `traceparent` header
+ * to a cross-origin request forces a CORS preflight, and any third party that
+ * doesn't list the header in Access-Control-Allow-Headers (Clerk, Stripe, most
+ * APIs) rejects it — breaking the request. So we never send trace context to an
+ * origin the app didn't opt in. Mirrors OTel-web's `propagateTraceHeaderCorsUrls`
+ * / Sentry's `tracePropagationTargets`. Targets match against the full request URL
+ * (string substring or RegExp).
+ */
+export declare function shouldPropagateTrace(url: string, targets?: ReadonlyArray<string | RegExp>): boolean;
 /** Patch window.fetch to inject traceparent on outgoing calls and record the
- *  trace id for correlation. Returns an unpatch function. */
-export declare function patchFetchForCorrelation(collector: TraceIdCollector): () => void;
+ *  trace id for correlation. Returns an unpatch function. `propagateTargets` are
+ *  cross-origin backends allowed to receive trace headers (same-origin always is). */
+export declare function patchFetchForCorrelation(collector: TraceIdCollector, propagateTargets?: ReadonlyArray<string | RegExp>): () => void;
 /** One recorded browser CLIENT span (an outbound fetch). */
 export interface BrowserClientSpan {
     traceId: string;
@@ -174,6 +201,9 @@ export interface TracingPatchOpts {
     collector?: TraceIdCollector;
     /** Optional: publish the current span context so captured errors can reference it. */
     activeTrace?: ActiveTraceRef;
+    /** Cross-origin backends allowed to receive trace headers (same-origin always is).
+     *  Third-party / non-listed cross-origin calls are passed through untouched. */
+    propagateTargets?: ReadonlyArray<string | RegExp>;
     rng?: () => number;
 }
 /** Patch window.fetch to emit a real CLIENT span per outbound call, inject that

package/dist/web.js

@@ -124,6 +124,7 @@ export async function instrumentWeb(opts) {
             ingestHost,
             collector: traces, // real trace ids also tag the replay session (better correlation)
             activeTrace, // so a captured error can reference the in-flight span
+            propagateTargets: opts.tracePropagationTargets, // same-origin + these only (never third parties)
         });
         fetchPatched = true;
         const traceFlush = setInterval(() => void exporter.flush(), opts.flushIntervalMs ?? DEFAULT_FLUSH_MS);
@@ -196,7 +197,7 @@ export async function instrumentWeb(opts) {
     // Only patch fetch for replay correlation if tracing didn't already patch it
     // (tracing's patch injects real context AND feeds `traces`). Avoids double-wrapping
     // window.fetch. Uses the original fetch for uploads (self-span suppression).
-    const unpatch = fetchPatched ? () => { } : patchFetchForCorrelation(traces);
+    const unpatch = fetchPatched ? () => { } : patchFetchForCorrelation(traces, opts.tracePropagationTargets);
     let buffer = [];
     let errorCount = 0;
     const browser = navigator.userAgent;
@@ -297,13 +298,50 @@ export class ActiveTraceRef {
     set(traceId, spanId) { this.cur = { traceId, spanId }; }
     get() { return this.cur; }
 }
+/**
+ * Decide whether to attach trace headers (`traceparent`) to an outbound request.
+ * Same-origin is always propagated; a CROSS-origin request is propagated ONLY if
+ * its URL matches an explicit target.
+ *
+ * This is critical for correctness: adding the non-safelisted `traceparent` header
+ * to a cross-origin request forces a CORS preflight, and any third party that
+ * doesn't list the header in Access-Control-Allow-Headers (Clerk, Stripe, most
+ * APIs) rejects it — breaking the request. So we never send trace context to an
+ * origin the app didn't opt in. Mirrors OTel-web's `propagateTraceHeaderCorsUrls`
+ * / Sentry's `tracePropagationTargets`. Targets match against the full request URL
+ * (string substring or RegExp).
+ */
+export function shouldPropagateTrace(url, targets = []) {
+    const base = typeof location !== "undefined" ? location.href : undefined;
+    let href;
+    try {
+        const u = new URL(url, base);
+        if (typeof location !== "undefined" && u.origin === location.origin)
+            return true;
+        href = u.href;
+    }
+    catch {
+        return true; // relative/opaque with no base ⇒ same-origin (safe to propagate)
+    }
+    for (const t of targets) {
+        if (typeof t === "string" ? href.includes(t) : t.test(href))
+            return true;
+    }
+    return false;
+}
 /** Patch window.fetch to inject traceparent on outgoing calls and record the
- *  trace id for correlation. Returns an unpatch function. */
-export function patchFetchForCorrelation(collector) {
+ *  trace id for correlation. Returns an unpatch function. `propagateTargets` are
+ *  cross-origin backends allowed to receive trace headers (same-origin always is). */
+export function patchFetchForCorrelation(collector, propagateTargets = []) {
     if (typeof window === "undefined" || !window.fetch)
         return () => { };
     const orig = window.fetch.bind(window);
     window.fetch = ((input, init) => {
+        // Only attach trace context to same-origin / allow-listed backends — never a
+        // third party (that would break its CORS preflight). See shouldPropagateTrace.
+        if (!shouldPropagateTrace(fetchUrl(input), propagateTargets)) {
+            return orig(input, init);
+        }
         const traceId = randHex(16);
         const spanId = randHex(8);
         collector.add(traceId);
@@ -413,6 +451,11 @@ export function patchFetchForTracing(o) {
         // the original fetch; this is the belt-and-suspenders host-match guard.
         if (o.ingestHost && safeHostname(url) === o.ingestHost)
             return orig(input, init);
+        // Third-party / non-allow-listed cross-origin: don't trace AND don't inject a
+        // header — a `traceparent` on a cross-origin request forces a CORS preflight the
+        // third party rejects (the Clerk/Stripe outage class). Pass through untouched.
+        if (!shouldPropagateTrace(url, o.propagateTargets))
+            return orig(input, init);
         const sampled = rng() < o.sampleRate;
         const traceId = randHex(16);
         const spanId = randHex(8);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heystack/otel",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "description": "Runtime-aware OpenTelemetry tracing that exports to Heystack (Node, Next.js, Workers).",
   "license": "MIT",
   "type": "module",