@heystack/otel 0.17.0 → 0.19.0

package/dist/web.js

@@ -3,6 +3,8 @@ import { DEFAULT_ENDPOINT, releaseResourceAttributes } from "./core.js";
 // bundle. Used to skip tracing our OWN telemetry POSTs (the self-export loop that
 // caused the June 2026 cost incident); see CLAUDE.md → "Cost guardrails".
 import { safeHostname } from "./self-span.js";
+// Pure, import-free URL redaction shared with the server entries.
+import { makeUrlRedactor, redactUrl } from "./redact.js";
 /** Pure: decide once per session whether to record. rng defaults to Math.random. */
 export function shouldRecord(cfg, rng = Math.random) {
     if (!cfg.enabled)
@@ -100,6 +102,72 @@ export function tracingActive(opts, cfg) {
 export function errorCaptureActive(opts, cfg) {
     return opts.errors !== false && cfg.errors_enabled !== false;
 }
+const MASK_ATTR = "data-hs-mask";
+const UNMASK_ATTR = "data-hs-unmask";
+/** True if the NEAREST `data-hs-mask` / `data-hs-unmask` marker on `element` or
+ *  an ancestor is `data-hs-unmask` (so a `data-hs-mask` nested inside an unmasked
+ *  region re-masks). */
+function isRevealed(element) {
+    const marked = element?.closest?.(`[${MASK_ATTR}],[${UNMASK_ATTR}]`);
+    return !!marked && !!marked.hasAttribute?.(UNMASK_ATTR);
+}
+function isPasswordInput(element) {
+    const type = (element?.type ?? element?.getAttribute?.("type") ?? "").toString().toLowerCase();
+    return type === "password";
+}
+const stars = (text) => "*".repeat(text.length);
+/**
+ * Pure: the rrweb privacy options for a masking mode. Anything other than an
+ * explicit `"relaxed"` is treated as `"strict"` (fail-closed).
+ *
+ * - **strict** (default): ALL text and ALL input values are masked
+ *   (`maskTextSelector: "*"` + `maskAllInputs`). Mark an element with
+ *   `data-hs-unmask` to record it (and its descendants) in cleartext; a nested
+ *   `data-hs-mask` re-masks. Password inputs are ALWAYS masked, even inside a
+ *   `data-hs-unmask` region.
+ * - **relaxed**: text is recorded except inside `data-hs-mask`; input values are
+ *   recorded except passwords (rrweb's default).
+ *
+ * Both modes drop `data-hs-block` elements entirely (recorded as a placeholder
+ * box). Masking applies to text nodes and input values only — element ATTRIBUTES
+ * (`title`, `alt`, `placeholder`, `aria-label`, link `href`s) are not masked by
+ * rrweb, so use `data-hs-block` for regions whose attributes are sensitive.
+ */
+export function replayPrivacyOptions(mode) {
+    const strict = mode !== "relaxed";
+    if (!strict) {
+        return {
+            maskAllInputs: false,
+            maskTextSelector: `[${MASK_ATTR}]`,
+            blockSelector: "[data-hs-block]",
+            // rrweb only calls these for nodes it already decided to mask
+            // (`data-hs-mask` text / password inputs) — always mask them.
+            maskInputFn: (text) => stars(text),
+            maskTextFn: (text) => stars(text),
+        };
+    }
+    return {
+        maskAllInputs: true,
+        // "*" matches every element, so rrweb routes ALL text through maskTextFn
+        // (rrweb 2.0.1 checks `el.closest(maskTextSelector)` for mutations and
+        // `el.matches(...)` / ancestor checks for snapshots).
+        maskTextSelector: "*",
+        blockSelector: "[data-hs-block]",
+        maskInputFn: (text, element) => !isPasswordInput(element) && isRevealed(element) ? text : stars(text),
+        maskTextFn: (text, element) => (isRevealed(element) ? text : stars(text)),
+    };
+}
+/** rrweb Meta events (`type: 4`) carry the page `href`: return a copy with it redacted. */
+const META = 4;
+export function redactReplayEvent(event, redact = redactUrl) {
+    const e = event;
+    if (e && e.type === META && e.data && typeof e.data.href === "string") {
+        const href = redact(e.data.href);
+        if (href !== e.data.href)
+            return { ...e, data: { ...e.data, href } };
+    }
+    return event;
+}
 /** A caller-owned session UUID allows product activity to correlate with replay. */
 export function resolveWebSessionId(candidate) {
     if (candidate === undefined)
@@ -136,6 +204,8 @@ export async function instrumentWeb(opts) {
     const sessionId = resolveWebSessionId(opts.sessionId);
     // service.version / service.build for release attribution on exported browser logs.
     const releaseAttrs = releaseResourceAttributes({ version: opts.version, build: opts.build });
+    // One URL redactor for everything this run records (spans, logs, replay).
+    const redact = makeUrlRedactor(opts);
     // 2. Browser distributed tracing (opt-in) — INDEPENDENT of replay sampling. Emits
     //    a real CLIENT span per outbound fetch + propagates W3C context to the backend.
     let stopTracing = () => { };
@@ -154,6 +224,7 @@ export async function instrumentWeb(opts) {
             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)
+            redactUrl: redact,
         });
         fetchPatched = true;
         const traceFlush = setInterval(() => void exporter.flush(), opts.flushIntervalMs ?? DEFAULT_FLUSH_MS);
@@ -181,7 +252,7 @@ export async function instrumentWeb(opts) {
     registerBugSession({
         endpoint, apiKey: opts.apiKey, service: opts.service, sessionId,
         fetchImpl: originalFetch, activeTrace, recentErrors, logsExporter,
-        version: opts.version, build: opts.build,
+        version: opts.version, build: opts.build, redactUrl: redact,
     });
     // 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.
@@ -195,6 +266,7 @@ export async function instrumentWeb(opts) {
             captureConsole: opts.captureConsole ?? "error",
             activeTrace,
             recent: recentErrors,
+            redactUrl: redact,
         });
         const logFlush = setInterval(() => void logsExporter.flush(), opts.flushIntervalMs ?? DEFAULT_FLUSH_MS);
         const onHideLogs = () => { if (document.visibilityState === "hidden")
@@ -214,16 +286,11 @@ export async function instrumentWeb(opts) {
     if (!shouldRecord(cfg))
         return () => { stopTracing(); stopErrors(); registerBugSession(null); };
     const { record } = await import("rrweb");
-    // An element marked `data-hs-unmask` (or any descendant of one) is recorded in
-    // cleartext; everything else is masked. rrweb 2.0.1's real opt-out hooks are
-    // `maskInputFn`/`maskTextFn` — there is no `unmaskTextSelector` option.
-    // Signatures (from rrweb-snapshot 2.0.1):
-    //   MaskInputFn = (text: string, element: HTMLElement) => string
-    //   MaskTextFn  = (text: string, element: HTMLElement | null) => string
-    // `maskTextFn`'s element can be null, so the `?.closest?.` chain is guarded.
-    const reveal = (text, element) => !!element?.closest?.("[data-hs-unmask]");
-    const maskInputFn = (text, element) => reveal(text, element) ? text : "*".repeat(text.length);
-    const maskTextFn = (text, element) => reveal(text, element) ? text : "*".repeat(text.length);
+    // Strict (the default, and the fallback for any unknown/missing mode) masks ALL
+    // text and input values; `data-hs-unmask` opts an element back in. rrweb 2.0.1
+    // has no `unmaskTextSelector`, so the opt-out is implemented in
+    // `maskTextFn`/`maskInputFn` — see replayPrivacyOptions.
+    const privacy = replayPrivacyOptions(cfg.masking_mode);
     const transport = new ReplayTransport({ endpoint, apiKey: opts.apiKey, fetchImpl: originalFetch, sessionId });
     // 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
@@ -244,7 +311,7 @@ export async function instrumentWeb(opts) {
         const errs = errorCount;
         errorCount = 0;
         void transport.send(events, {
-            url: location.href, errorCount: errs, userId: opts.userId, browser, device,
+            url: redact(location.href), errorCount: errs, userId: opts.userId, browser, device,
             traceIds: traces.drain(),
         }, keepalive);
     };
@@ -256,17 +323,13 @@ export async function instrumentWeb(opts) {
             // nearest keyframe ≤ a target time instead of loading the whole session.
             if (isCheckout)
                 flush();
-            buffer.push(event);
+            buffer.push(redactReplayEvent(event, redact));
             if (buffer.length >= (opts.flushEveryEvents ?? DEFAULT_FLUSH_EVENTS))
                 flush();
         },
         // A ~60s keyframe cadence bounds how many chunks the player must fetch to seek.
         checkoutEveryNms: 60_000,
-        maskAllInputs: cfg.masking_mode === "strict",
-        maskTextSelector: "[data-hs-mask]",
-        blockSelector: "[data-hs-block]",
-        maskInputFn,
-        maskTextFn,
+        ...privacy,
     });
     const interval = setInterval(() => flush(), opts.flushIntervalMs ?? DEFAULT_FLUSH_MS);
     const onHide = () => { if (document.visibilityState === "hidden")
@@ -460,11 +523,13 @@ function fetchMethod(input, init) {
     return m.toUpperCase();
 }
 function pathOf(url) {
+    // Relative URLs (no base) fall back to the raw string minus query/fragment, so a
+    // span NAME never carries a secret the url.full redaction removed.
     try {
         return new URL(url).pathname;
     }
     catch {
-        return url;
+        return url.split(/[?#]/)[0] ?? url;
     }
 }
 /** Patch window.fetch to emit a real CLIENT span per outbound call, inject that
@@ -475,6 +540,7 @@ export function patchFetchForTracing(o) {
         return () => { };
     const orig = window.fetch.bind(window);
     const rng = o.rng ?? Math.random;
+    const redact = o.redactUrl ?? redactUrl;
     window.fetch = ((input, init) => {
         const url = fetchUrl(input);
         // Never trace our own telemetry POSTs (trace export, replay upload, config) —
@@ -502,7 +568,7 @@ export function patchFetchForTracing(o) {
         const emit = (statusCode, error) => {
             if (!sampled)
                 return;
-            o.onSpan({ traceId, spanId, name: `${method} ${pathOf(url)}`, startMs, endMs: Date.now(), method, url, statusCode, error });
+            o.onSpan({ traceId, spanId, name: `${method} ${pathOf(url)}`, startMs, endMs: Date.now(), method, url: redact(url), statusCode, error });
         };
         return orig(input, { ...init, headers }).then((res) => { emit(res.status, res.status >= 400); return res; }, (err) => { emit(0, true); throw err; });
     });
@@ -647,6 +713,7 @@ export function startErrorCapture(o) {
     if (typeof window === "undefined")
         return () => { };
     const now = o.now ?? Date.now;
+    const redact = o.redactUrl ?? redactUrl;
     const gate = new RateGate(o.rateCap ?? 60, o.rateWindowMs ?? 60_000, now);
     // Re-entrancy flag: if capturing a record ends up invoking a patched console
     // (or any path that re-enters here), we drop the nested call — this is what
@@ -677,7 +744,7 @@ export function startErrorCapture(o) {
             o.recent?.push({ message: e.message, type: e.type, timestamp: now() });
             const attrs = {
                 "event.name": "browser.error",
-                "url.full": location.href,
+                "url.full": redact(location.href),
                 session_id: o.sessionId,
                 "exception.message": e.message,
             };
@@ -740,7 +807,7 @@ export function startErrorCapture(o) {
                     attributes: {
                         "event.name": "browser.console",
                         "console.level": level,
-                        "url.full": location.href,
+                        "url.full": redact(location.href),
                         session_id: o.sessionId,
                     },
                     traceId: active?.traceId,
@@ -778,7 +845,7 @@ export function buildBugReportPayload(s, report) {
         message: report.message,
         email: report.email,
         context: report.context,
-        url: typeof location !== "undefined" ? location.href : undefined,
+        url: typeof location !== "undefined" ? (s.redactUrl ?? redactUrl)(location.href) : undefined,
         user_agent: typeof navigator !== "undefined" ? navigator.userAgent : undefined,
         session_id: s.sessionId,
         trace_id: active?.traceId,
@@ -821,7 +888,7 @@ export async function reportBug(report) {
         body: message,
         attributes: {
             "event.name": "user.bug_report",
-            "url.full": typeof location !== "undefined" ? location.href : "",
+            "url.full": typeof location !== "undefined" ? (s.redactUrl ?? redactUrl)(location.href) : "",
             session_id: s.sessionId,
             ...(report.email ? { "user.email": report.email } : {}),
         },

package/dist/workers-bindings.d.ts

@@ -1,4 +1,5 @@
 import { SpanKind, type Span } from "@opentelemetry/api";
+import type { BindingKind } from "./workers-coverage.js";
 export interface InstrumentBindingsOpts {
     /**
      * Factory that creates and starts a new child span. Called at binding method
@@ -8,7 +9,17 @@ export interface InstrumentBindingsOpts {
      * For integration: pass `(name, attrs, kind) => tracer.startSpan(name, { attributes: attrs, kind }, context.active())`.
      * For unit tests: inject a fake so no global provider is required.
      */
-    startSpan: (name: string, attrs: Record<string, unknown>, kind?: SpanKind) => Span;
+    startSpan?: (name: string, attrs: Record<string, unknown>, kind?: SpanKind) => Span;
+    /**
+     * Callback-scoped span runner (native mode). When present, every wrapper runs
+     * its operation inside it and `startSpan` is never called. Must throw/reject
+     * only what `fn` throws.
+     */
+    withSpan?: <T>(name: string, attrs: Record<string, unknown>, kind: SpanKind | undefined, fn: (span: Span) => T | Promise<T>) => Promise<T>;
+    /** Skip bindings whose {@link BindingKind} this returns false for. */
+    kindFilter?: (kind: BindingKind) => boolean;
+    /** Use Cloudflare-native span names (`ai_run`, `vectorize_<op>`, `workflow_<op>`, ...). */
+    nativeNames?: boolean;
     /**
      * `true`  → auto-detect and wrap every supported Cloudflare binding.
      * `string[]` → only wrap bindings whose env key is listed.
@@ -21,6 +32,19 @@ export interface InstrumentBindingsOpts {
  * wrappers in workers.ts.
  */
 export declare function runWithSpan<T>(span: Span, fn: () => Promise<T>): Promise<T>;
+/** Plain string keys from a string / string[] argument (anything else yields none). */
+export declare function keysOf(value: unknown): string[];
+/** Resolves once every in-flight key hash has attached its attribute and ended its span. */
+export declare function settlePendingKeyHashes(): Promise<void>;
+/**
+ * Like {@link runWithSpan} for operations that carry user-controlled keys. The
+ * hash is computed concurrently with the call and attached under `attr` before
+ * the span ends; it can neither delay the call's result nor change its error.
+ * If hashing is impossible the attribute is omitted (never the raw key).
+ */
+export declare function runWithSpanKeyed<T>(span: Span, attr: string, keys: readonly string[], fn: () => Promise<T>, countAttr?: string): Promise<T>;
+/** Trace a call without replacing synchronous, Promise, or custom thenable results. */
+export declare function runWithSpanPreservingReturn<T>(span: Span, fn: () => T): T;
 /** Internal proxy builder shared with the class-level wrappers in workers.ts. */
 export declare function makeProxy(target: any, handlers: Record<string, Function>): any;
 /**
@@ -61,4 +85,17 @@ export declare function injectTraceparentArgs(args: any[], traceparent: string):
  * @param opts - `startSpan` factory (now accepts optional `SpanKind`) + `select` filter.
  * @returns A shallow copy of `env` with selected bindings replaced by proxies.
  */
-export declare function instrumentEnv<E extends Record<string, unknown>>(env: E, opts: InstrumentBindingsOpts): E;
+export declare function instrumentEnv<E extends Record<string, unknown>>(env: E, rawOpts: InstrumentBindingsOpts): E;
+/**
+ * Wrap a Postgres/MySQL client (postgres.js, pg, mysql2, ...) created from a
+ * Hyperdrive binding so each `query` / `unsafe` / `execute` call, and each
+ * tagged-template call when the client itself is callable (postgres.js
+ * `sql\`select 1\``), emits a `hyperdrive_query` span. `db.query.text` is
+ * recorded raw (template strings are joined with `?`; ingest sanitises). The
+ * ORIGINAL return value is passed through untouched; the span ends when it
+ * settles. Uses the request's native tracer when present, else the global one.
+ */
+export declare function wrapSqlClient<C extends object>(client: C, opts?: {
+    name?: string;
+    dbSystem?: "postgresql" | "mysql";
+}): C;