@heystack/otel 0.11.0 → 0.12.0

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,16 @@ 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.
+
+**Remote kill-switch (safety valve).** Browser tracing can also be disabled **from the server**, without an app redeploy — a way to stop it fleet-wide if it ever misbehaves in the wild. It is **fail-open**: if the server config is unreachable or omits the flag, tracing stays on (absent flag = enabled), so the switch can only ever *disable*, never accidentally turn a working app off.
 
 ### Browser error & console collection
 
@@ -413,6 +419,8 @@ await instrumentWeb({
 
 It's the **same cost-safe design** as tracing/replay: logs POST to `/v1/logs` through the *original* `fetch` (captured before any patching) so the exporter never traces its own upload — no self-export loop. Console capture is **recursion-guarded** (anything logged on the export path is never re-captured) and **rate-capped** (max ~60 records/minute; the overflow is dropped and counted, with one summary log emitted when the cap lifts) so a runaway `console.error` in a render loop can't flood ingest. Errors show up in the console **Logs** tab and correlate to their session replay and trace.
 
+Like tracing, error / console capture has a **remote kill-switch**: it can be disabled **from the server** without an app redeploy, and is **fail-open** (if the server config is unreachable or omits the flag, capture stays on — absent flag = enabled).
+
 ### In-app bug reports (`reportBug`)
 
 Let users report a bug from inside your app. `reportBug` is a headless API — **no widget, you own the UX** — that files a structured report and auto-attaches the context a triager needs: the current URL, user agent, replay `session_id`, active `trace_id`, `release` / `build`, and the **last few captured browser errors** (so you see what was going wrong on the page right before the report). The report also appears on the Logs timeline (`event.name=user.bug_report`).

package/dist/web.d.ts

@@ -17,6 +17,19 @@ export interface RecorderConfig {
     enabled: boolean;
     sample_rate: number;
     masking_mode: "strict" | "relaxed";
+    /**
+     * Server-side kill-switch for browser distributed tracing. Absent/`true` = enabled
+     * (**fail-open**); set `false` server-side to remotely disable browser tracing
+     * WITHOUT an app redeploy — the safety valve for the 2026-07-03 cross-origin
+     * `traceparent` outage. See `tracingActive`.
+     */
+    tracing_enabled?: boolean;
+    /**
+     * Server-side kill-switch for browser error / console capture. Absent/`true` =
+     * enabled (**fail-open**); set `false` server-side to remotely disable it without
+     * an app redeploy. See `errorCaptureActive`.
+     */
+    errors_enabled?: boolean;
 }
 /** Pure: decide once per session whether to record. rng defaults to Math.random. */
 export declare function shouldRecord(cfg: RecorderConfig, rng?: () => number): boolean;
@@ -89,6 +102,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
@@ -104,6 +129,21 @@ export interface InstrumentWebOptions {
      */
     captureConsole?: "error" | "warn" | false;
 }
+/**
+ * Pure: is browser distributed tracing active for this run? Requires BOTH the app
+ * to have opted in (`opts.tracing`) AND the server-side kill-switch to not be off
+ * (`cfg.tracing_enabled`). **Fail-open**: an absent/`true` flag counts as enabled, so
+ * an old or unreachable `/v1/replay/config` never silently disables tracing. Split out
+ * as a tiny exported predicate so the gating decision is unit-testable without booting
+ * rrweb (which `instrumentWeb` imports). See `RecorderConfig.tracing_enabled`.
+ */
+export declare function tracingActive(opts: Pick<InstrumentWebOptions, "tracing">, cfg: Pick<RecorderConfig, "tracing_enabled">): boolean;
+/**
+ * Pure: is browser error / console capture active for this run? On by default
+ * (`opts.errors !== false`) AND gated by the server-side kill-switch
+ * (`cfg.errors_enabled`). **Fail-open**: an absent/`true` flag counts as enabled.
+ */
+export declare function errorCaptureActive(opts: Pick<InstrumentWebOptions, "errors">, cfg: Pick<RecorderConfig, "errors_enabled">): boolean;
 /** Entry point: fetch config, decide sampling, start rrweb, stream chunks.
  *  Returns a stop() function. Safe to call in any browser; no-ops on the server. */
 export declare function instrumentWeb(opts: InstrumentWebOptions): Promise<() => void>;
@@ -128,9 +168,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 +229,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

@@ -81,6 +81,25 @@ export class ReplayTransport {
 }
 const DEFAULT_FLUSH_MS = 5000;
 const DEFAULT_FLUSH_EVENTS = 200;
+/**
+ * Pure: is browser distributed tracing active for this run? Requires BOTH the app
+ * to have opted in (`opts.tracing`) AND the server-side kill-switch to not be off
+ * (`cfg.tracing_enabled`). **Fail-open**: an absent/`true` flag counts as enabled, so
+ * an old or unreachable `/v1/replay/config` never silently disables tracing. Split out
+ * as a tiny exported predicate so the gating decision is unit-testable without booting
+ * rrweb (which `instrumentWeb` imports). See `RecorderConfig.tracing_enabled`.
+ */
+export function tracingActive(opts, cfg) {
+    return !!opts.tracing && cfg.tracing_enabled !== false;
+}
+/**
+ * Pure: is browser error / console capture active for this run? On by default
+ * (`opts.errors !== false`) AND gated by the server-side kill-switch
+ * (`cfg.errors_enabled`). **Fail-open**: an absent/`true` flag counts as enabled.
+ */
+export function errorCaptureActive(opts, cfg) {
+    return opts.errors !== false && cfg.errors_enabled !== false;
+}
 /** Entry point: fetch config, decide sampling, start rrweb, stream chunks.
  *  Returns a stop() function. Safe to call in any browser; no-ops on the server. */
 export async function instrumentWeb(opts) {
@@ -113,7 +132,9 @@ export async function instrumentWeb(opts) {
     //    a real CLIENT span per outbound fetch + propagates W3C context to the backend.
     let stopTracing = () => { };
     let fetchPatched = false;
-    if (opts.tracing) {
+    // Gated by the server kill-switch (cfg.tracing_enabled) as well as the app opt-in —
+    // fail-open, so an unreachable/old config can't disable tracing. See tracingActive.
+    if (tracingActive(opts, cfg)) {
         const exporter = new BrowserTraceExporter({
             endpoint, apiKey: opts.apiKey, service: opts.service, fetchImpl: originalFetch,
             resourceAttributes: releaseAttrs,
@@ -124,6 +145,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);
@@ -156,7 +178,9 @@ export async function instrumentWeb(opts) {
     // 2b. Browser error / console log collection — ON by default, INDEPENDENT of both
     //     tracing and replay sampling. Exports OTLP logs to /v1/logs via the original fetch.
     let stopErrors = () => { };
-    if (opts.errors !== false) {
+    // Gated by the server kill-switch (cfg.errors_enabled) as well as the opts.errors
+    // default — fail-open. See errorCaptureActive.
+    if (errorCaptureActive(opts, cfg)) {
         const unpatchErrors = startErrorCapture({
             exporter: logsExporter,
             sessionId,
@@ -196,7 +220,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 +321,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 +474,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.12.0",
   "description": "Runtime-aware OpenTelemetry tracing that exports to Heystack (Node, Next.js, Workers).",
   "license": "MIT",
   "type": "module",