@heystack/otel 0.11.1 → 0.12.0

package/README.md

@@ -400,6 +400,8 @@ await instrumentWeb({
 
 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
 
 `instrumentWeb` captures **uncaught browser errors** out of the box — no extra setup. Any `window.onerror` / unhandled promise rejection becomes an OTLP **log** (`event.name=browser.error`, `ERROR` severity) carrying the OTel `exception.type` / `exception.message` / `exception.stacktrace` semconv attributes, the page `url.full`, the `session_id` (so it correlates to the session replay), and — when `tracing` is on — the active `trace_id` / `span_id`. `console.error` is captured too by default.
@@ -417,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;
@@ -116,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>;

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,
@@ -157,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,

package/package.json

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