@reliantlabs/forge-web-runtime 0.12.0 → 0.13.1

package/dist/telemetry.d.ts

@@ -1,4 +1,8 @@
 import { type AttributionTouch } from "./attribution.js";
+import { type BenignErrorClassifier } from "./benign-errors.js";
+export { clientResourceAttributes, type ForgeDesktopInfo, viewportAttributes, } from "./client-context.js";
+export { cookiesPersist, installSessionCookieFallback, RUM_SESSION_COOKIE, RUM_SESSION_STORAGE_KEY, } from "./session-cookie-fallback.js";
+export { type BenignErrorClassifier, type BenignErrorKind, classifyBenignError, FILTERED_ERRORS_ACTION, } from "./benign-errors.js";
 /** Where the browser ships telemetry: this origin's `/_otel`. */
 export declare const DEFAULT_INGEST_PATH = "/_otel";
 /**
@@ -95,6 +99,18 @@ export interface BrowserTelemetryConfig {
      * site attributing acquisition to the campaign that first brought a visitor.
      */
     attributionTouch?: AttributionTouch;
+    /**
+     * Decides which errors are benign browser noise: kept out of the error
+     * pipeline and counted as `forge.errors_filtered` actions instead
+     * (benign-errors.ts). Default classifyBenignError: an AbortError, and the
+     * browser's generic "Failed to fetch" TypeError; never a ConnectError. It
+     * applies to what the SDK records from unhandled rejections, uncaught
+     * errors, console.error and reportException; the app's own handlers see
+     * every event unchanged. For an unhandled rejection or uncaught error it is
+     * handed `{ name, message }` as the SDK recorded them, not the original
+     * value. Pass `() => null` to record everything.
+     */
+    classifyBenignError?: BenignErrorClassifier;
 }
 /**
  * Turn on visitor attribution for a page that started telemetry with
@@ -115,9 +131,11 @@ export declare function enableAttribution(options?: {
 export declare function initBrowserTelemetry(config: BrowserTelemetryConfig): Promise<boolean>;
 /**
  * The options passed to HyperDX.init. Exported for tests and for apps that
- * want to see exactly what is configured — it is pure.
+ * want to see exactly what is configured — it is pure. `clientAttributes`
+ * are the page's own client resource attributes (client-context.ts:
+ * browser.* client hints, app.desktop.*); the config's keys win over them.
  */
-export declare function buildSdkOptions(config: BrowserTelemetryConfig, ingestUrl: string, pageOrigin: string): Record<string, unknown>;
+export declare function buildSdkOptions(config: BrowserTelemetryConfig, ingestUrl: string, pageOrigin: string, clientAttributes?: Record<string, string>): Record<string, unknown>;
 /** Elements a replay never records: their pixels stay in the browser. */
 export declare const REPLAY_BLOCK_SELECTOR = "img, picture, video, audio, iframe, object, embed";
 /** Where a replay sampling decision is held for the tab's session. */
@@ -137,6 +155,15 @@ interface DecisionStore {
 export declare function decideReplay(config: Pick<BrowserTelemetryConfig, "replay" | "replaySampleRate">, store: DecisionStore | null, random: () => number): boolean;
 /** `url` without its query string and fragment. */
 export declare function stripUrlQuery(url: string): string;
+/**
+ * The name a fetch/XHR span gets: `<METHOD> /<package>.<Service>/<Method>`,
+ * the server span's name with the method in front, when the URL is a
+ * Connect/gRPC procedure. Empty for any other URL, which keeps the SDK's
+ * `HTTP <METHOD>`: an arbitrary path can hold values (ids, tokens, emails) no
+ * pattern recognises reliably, and a span name must be neither sensitive nor
+ * unbounded. Empty too when `url` cannot be parsed. Exported for tests.
+ */
+export declare function spanRouteName(method: string, url: string): string;
 /**
  * resolveIngestUrl turns the configured endpoint into the absolute URL the SDK
  * is given, or null when telemetry is off. A path resolves against the page

package/dist/telemetry.js

@@ -52,6 +52,27 @@
 // SDK has no session sampler, so the decision is made here, once, and held in
 // sessionStorage for the tab's session.
 //
+// ── One session per visit, even where cookies are dropped ────────────────
+//
+// The SDK keeps its session id only in the `__rum_sid` cookie and mints a new
+// one whenever it cannot read that cookie back, which it checks every minute.
+// An origin that drops cookies (an Electron renderer on a custom scheme such
+// as `app://`) therefore got a new session every minute. Before init, the
+// runtime probes whether cookies persist and, when they do not, keeps that one
+// cookie in localStorage with the same 15-minute inactivity and 4-hour limits
+// (session-cookie-fallback.ts). Origins whose cookies work are untouched.
+//
+// ── No session until the page has been seen ──────────────────────────────
+//
+// A page loaded in the background (a desktop window opened hidden, a tab
+// restored behind another) starts no session at all: the SDK is not loaded
+// until the document is first visible. Started hidden, it would mint a session
+// made only of background fetch spans, with nothing on screen to record, and
+// the recorder would hold no replay for it. Until then reportException returns
+// false (the caller logs to the console) and track() calls are held, bounded,
+// as they are while the SDK loads. A page that never becomes visible sends
+// nothing.
+//
 // ── Network URLs carry no query string ───────────────────────────────────
 //
 // fetch/XHR spans record the request URL, and a query string is where tokens,
@@ -60,6 +81,25 @@
 // The SDK's own `location.href` attribute (the page URL, stamped on every span)
 // has no client-side hook; the ingest side scrubs it.
 //
+// ── Network spans are named by what they called ──────────────────────────
+//
+// HyperDX names every fetch/XHR span `HTTP <METHOD>`, so a trace a browser
+// starts is titled "HTTP POST" whatever it did. The same hook renames it to
+// the procedure when it is a Connect/gRPC call (`POST /pkg.v1.Service/Method`,
+// the server span's name with the method in front; spanRouteName). Any other
+// URL keeps `HTTP <METHOD>`: a free-form path can carry ids and tokens, and
+// the span name is exported unscrubbed.
+//
+// ── Client context ───────────────────────────────────────────────────────
+//
+// The page reports what only it can know about its client — client hints
+// (browser.brands/platform/mobile), its viewport and screen (app.viewport.*,
+// app.screen.*) and, inside a desktop app, the app's versions from the
+// `window.forgeDesktop` preload bridge (app.desktop.*) — sanitized
+// (client-context.ts). Browser, OS and device type are NOT page claims: the
+// ingest side derives them from the request's User-Agent and Sec-CH-UA
+// headers and overwrites any the page sent.
+//
 // ── Loading ──────────────────────────────────────────────────────────────
 //
 // The SDK is ~600 KB minified (rrweb and the OTel web stack are bundled in
@@ -71,9 +111,15 @@
 // endpoint, and it never throws.
 import { trace } from "@opentelemetry/api";
 import { captureAttribution, detectAppClient, takeIdentifyProps, } from "./attribution.js";
+import { classifyBenignError, FilteredErrorCounter, } from "./benign-errors.js";
+import { pageClientResourceAttributes, watchViewport, } from "./client-context.js";
 import { setExceptionReporter } from "./error-reporter.js";
-import { registerTelemetryStartup } from "./telemetry-gate.js";
+import { installSessionCookieFallback } from "./session-cookie-fallback.js";
+import { registerRumSession, registerTelemetryStartup, rumSessionId, } from "./telemetry-gate.js";
 import { isTelemetryDisabled, setTelemetrySink, } from "./track.js";
+export { clientResourceAttributes, viewportAttributes, } from "./client-context.js";
+export { cookiesPersist, installSessionCookieFallback, RUM_SESSION_COOKIE, RUM_SESSION_STORAGE_KEY, } from "./session-cookie-fallback.js";
+export { classifyBenignError, FILTERED_ERRORS_ACTION, } from "./benign-errors.js";
 /** Where the browser ships telemetry: this origin's `/_otel`. */
 export const DEFAULT_INGEST_PATH = "/_otel";
 /**
@@ -153,14 +199,20 @@ export function initBrowserTelemetry(config) {
 }
 async function start(config, ingest) {
     try {
+        await firstVisible();
         const hdx = resolveClient(await import("@hyperdx/browser"));
         if (!hdx || isTelemetryDisabled()) {
             setTelemetrySink(null);
             return false;
         }
         const replay = decideReplay(config, sessionStorageOrNull(), Math.random);
-        hdx.init(buildSdkOptions({ ...config, replay }, ingest, window.location.origin));
-        tapSdkInputs();
+        // Before init: the SDK reads its session cookie as it starts.
+        keepSessionWithoutCookies();
+        hdx.init(buildSdkOptions({ ...config, replay }, ingest, window.location.origin, pageClientResourceAttributes()));
+        // After init: both hook what the SDK RECORDS, never what the app sees.
+        const benign = benignFilter(config, hdx);
+        filterSdkErrorSpans(benign);
+        tapSdkInputs(benign);
         // Every span carries where it came from and which visitor made it; the
         // product-event view reads these as app.client and visitor.id.
         // With attribution deferred (attribution: false), visitor.id joins them
@@ -175,10 +227,21 @@ async function start(config, ingest) {
             globals["visitor.id"] = captureVisitor(config);
         }
         hdx.setGlobalAttributes?.(globals);
+        // The viewport and screen ride on every span, refreshed on resize
+        // (client-context.ts): the SDK's global attributes are a span processor
+        // that stamps the current set on each span as it starts, so a span carries
+        // the size of the moment it began (proved against the real SDK in
+        // scripts/browser-telemetry-smoke.mjs). Device, OS and browser are
+        // derived at ingest.
+        const stopViewport = watchViewport((attrs) => hdx.setGlobalAttributes?.(attrs));
         runningClient = hdx;
         runningConfig = config;
+        // The session id rides on every Connect call as baggage (trace.ts) and on
+        // every fetch/XHR span (sessionAttribute), joining backend traces to the
+        // session that caused them.
+        registerRumSession(() => hdx.getSessionId?.());
         setExceptionReporter((error, attributes) => {
-            if (alreadyRecorded(error)) {
+            if (alreadyRecorded(error) || benign.filtered(error, "reportException")) {
                 return;
             }
             hdx.recordException(error, attributes);
@@ -198,6 +261,8 @@ async function start(config, ingest) {
                 // Back to "no SDK": reportException returns false, so a caller falls
                 // back to console.error and the error does not vanish.
                 setExceptionReporter(null);
+                registerRumSession(null);
+                stopViewport();
                 hdx.stopSessionRecorder?.();
             },
         });
@@ -205,11 +270,34 @@ async function start(config, ingest) {
     }
     catch (err) {
         // Blocked chunk, ad-blocker, SDK throw: telemetry must never break the app.
+        // A startup that failed after the hooks went in takes them out again.
+        removeBenignFilter();
         console.debug("[telemetry] disabled:", err);
         setTelemetrySink(null);
         return false;
     }
 }
+/**
+ * Resolves once the document is visible: at once for a visible page or one
+ * with no Page Visibility API, otherwise at its first visibilitychange to
+ * visible. See "No session until the page has been seen" in the header.
+ */
+function firstVisible() {
+    if (typeof document === "undefined" ||
+        document.visibilityState !== "hidden" ||
+        typeof document.addEventListener !== "function") {
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+        const onChange = () => {
+            if (document.visibilityState !== "hidden") {
+                document.removeEventListener("visibilitychange", onChange);
+                resolve();
+            }
+        };
+        document.addEventListener("visibilitychange", onChange);
+    });
+}
 // ── One failure, one record ──────────────────────────────────────────────
 //
 // The SDK records an Error that reaches window "error", window
@@ -238,35 +326,238 @@ function noteSeen(value) {
         seenBySdk.add(value);
     }
 }
-function tapSdkInputs() {
+function tapSdkInputs(benign) {
     if (tapped) {
         return;
     }
     tapped = true;
     const wrapped = console.error;
-    console.error = function (...args) {
+    const tap = function (...args) {
         for (const arg of args) {
-            if (arg instanceof Error) {
-                noteSeen(arg);
+            try {
+                if (arg instanceof Error) {
+                    noteSeen(arg);
+                }
+            }
+            catch {
+                // A revoked Proxy: not ours to inspect; forward it untouched.
             }
         }
-        return wrapped.apply(this, args);
+        // The call always goes on to the SDK and the console, exactly as without
+        // this tap. Only the verdict on the SDK's RECORD of it is decided here,
+        // where the real arguments are: the SDK opens its console.error span
+        // synchronously inside wrapped(), and filterSdkErrorSpans reads it.
+        const previous = consoleVerdict;
+        consoleVerdict = benignKindsOf(benign, args);
+        try {
+            return wrapped.apply(this, args);
+        }
+        finally {
+            consoleVerdict = previous;
+        }
+    };
+    console.error = tap;
+    const onError = (e) => noteSeen(e.error);
+    const onRejection = (e) => noteSeen(e.reason);
+    window.addEventListener("error", onError, true);
+    window.addEventListener("unhandledrejection", onRejection, true);
+    benignTeardown.push(() => {
+        if (console.error === tap) {
+            console.error = wrapped;
+        }
+        window.removeEventListener?.("error", onError, true);
+        window.removeEventListener?.("unhandledrejection", onRejection, true);
+        tapped = false;
+    });
+}
+/**
+ * The kind of every exception in a console.error call when ALL of them are
+ * benign, or null to record the call: no exception, one real one, or an
+ * argument that cannot even be inspected (a throwing Symbol.toStringTag
+ * getter, a revoked Proxy).
+ */
+function benignKindsOf(benign, args) {
+    const kinds = [];
+    for (const arg of args) {
+        let exception;
+        try {
+            exception = isExceptionLike(arg);
+        }
+        catch {
+            return null;
+        }
+        if (!exception) {
+            continue;
+        }
+        const kind = benign.classify(arg);
+        if (kind === null) {
+            return null;
+        }
+        kinds.push(kind);
+    }
+    return kinds.length > 0 ? kinds : null;
+}
+function benignFilter(config, hdx) {
+    const classify = config.classifyBenignError ?? classifyBenignError;
+    const counter = new FilteredErrorCounter((name, attributes) => {
+        if (!isTelemetryDisabled()) {
+            hdx.addAction?.(name, attributes);
+        }
+    });
+    const onPageHide = () => counter.flush();
+    const onVisibility = () => {
+        if (document.visibilityState === "hidden") {
+            counter.flush();
+        }
+    };
+    if (typeof window.addEventListener === "function") {
+        window.addEventListener("pagehide", onPageHide);
+    }
+    if (typeof document !== "undefined") {
+        document.addEventListener("visibilitychange", onVisibility);
+    }
+    benignTeardown.push(() => {
+        window.removeEventListener?.("pagehide", onPageHide);
+        if (typeof document !== "undefined") {
+            document.removeEventListener("visibilitychange", onVisibility);
+        }
+    });
+    const kindOf = (error) => {
+        try {
+            return classify(error) || null;
+        }
+        catch {
+            // A classifier that throws keeps the error.
+            return null;
+        }
+    };
+    return {
+        classify: kindOf,
+        note: (kind, source) => counter.note(kind, source),
+        filtered(error, source) {
+            const kind = kindOf(error);
+            if (!kind) {
+                return false;
+            }
+            counter.note(kind, source);
+            return true;
+        },
     };
-    window.addEventListener("error", (e) => noteSeen(e.error), true);
-    window.addEventListener("unhandledrejection", (e) => noteSeen(e.reason), true);
+}
+/** The scope (name, version) the SDK's error capture records under. */
+const SDK_ERRORS_SCOPE = { name: "errors", version: "1" };
+/** The spans that scope opens, one per captured failure, and their source. */
+const SDK_ERROR_SPANS = {
+    onerror: "error",
+    unhandledrejection: "unhandledrejection",
+    "console.error": "console.error",
+};
+// The console tap's verdict on the call now inside the SDK's wrapper: the
+// benign kinds, null to record it, undefined when no tapped call is running.
+let consoleVerdict;
+function filterSdkErrorSpans(benign) {
+    const proxy = trace.getTracerProvider();
+    const provider = (proxy.getDelegate?.() ?? proxy);
+    const tracer = provider.getTracer?.(SDK_ERRORS_SCOPE.name, SDK_ERRORS_SCOPE.version);
+    if (!tracer || typeof tracer.startSpan !== "function") {
+        // No seam: record everything, as without the filter.
+        return;
+    }
+    const original = tracer.startSpan;
+    const startSpan = function (name, ...rest) {
+        const span = original.call(this, name, ...rest);
+        const source = SDK_ERROR_SPANS[name];
+        if (!source || typeof span?.end !== "function") {
+            return span;
+        }
+        const verdict = name === "console.error" ? consoleVerdict : undefined;
+        const end = span.end;
+        span.end = function (...args) {
+            const kinds = name === "console.error"
+                ? (verdict ?? null)
+                : recordedKind(benign, span);
+            if (kinds) {
+                for (const kind of kinds) {
+                    benign.note(kind, source);
+                }
+                // Never ended, so never exported.
+                return undefined;
+            }
+            return end.apply(this, args);
+        };
+        return span;
+    };
+    tracer.startSpan = startSpan;
+    benignTeardown.push(() => {
+        if (tracer.startSpan === startSpan) {
+            tracer.startSpan = original;
+        }
+    });
+}
+/** The benign kind of the one failure a window-event span recorded, or null. */
+function recordedKind(benign, span) {
+    try {
+        const name = span.attributes?.["error.object"];
+        const message = span.attributes?.["error.message"];
+        if (typeof name !== "string" || name === "String") {
+            return null;
+        }
+        const kind = benign.classify({
+            name,
+            message: typeof message === "string" ? message : "",
+        });
+        return kind ? [kind] : null;
+    }
+    catch {
+        return null;
+    }
+}
+// What undoes the benign filter's hooks (the tracer wrap, the console tap, the
+// flush listeners), run when startup fails at any point after they went in.
+let benignTeardown = [];
+function removeBenignFilter() {
+    const undo = benignTeardown;
+    benignTeardown = [];
+    for (const fn of undo.reverse()) {
+        try {
+            fn();
+        }
+        catch {
+            // Telemetry must never break the app.
+        }
+    }
+}
+// An exception value as console.error receives it: an Error, a DOMException
+// (not an Error in every browser), or either from another realm (an iframe),
+// which fails instanceof but keeps its [object Error] / [object DOMException]
+// tag.
+function isExceptionLike(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    if (value instanceof Error) {
+        return true;
+    }
+    if (typeof DOMException !== "undefined" && value instanceof DOMException) {
+        return true;
+    }
+    const tag = Object.prototype.toString.call(value);
+    return tag === "[object Error]" || tag === "[object DOMException]";
 }
 function alreadyRecorded(error) {
     return typeof error === "object" && error !== null && seenBySdk.has(error);
 }
 /**
  * The options passed to HyperDX.init. Exported for tests and for apps that
- * want to see exactly what is configured — it is pure.
+ * want to see exactly what is configured — it is pure. `clientAttributes`
+ * are the page's own client resource attributes (client-context.ts:
+ * browser.* client hints, app.desktop.*); the config's keys win over them.
  */
-export function buildSdkOptions(config, ingestUrl, pageOrigin) {
+export function buildSdkOptions(config, ingestUrl, pageOrigin, clientAttributes = {}) {
     // `config.replay` is the FINAL decision here. initBrowserTelemetry resolves
     // replaySampleRate into it (decideReplay) before calling this.
     const replay = config.replay === true;
-    const resourceAttributes = {};
+    const resourceAttributes = { ...clientAttributes };
     if (config.serviceVersion) {
         resourceAttributes["service.version"] = config.serviceVersion;
     }
@@ -296,15 +587,20 @@ export function buildSdkOptions(config, ingestUrl, pageOrigin) {
         // everything it would have set (propagation targets, the capture switch)
         // must be restated here or it is lost.
         instrumentations: {
+            // Raw DOM events belong to replay, not distributed traces. HyperDX's
+            // default traces every mousedown/up listener (including replay's own),
+            // creating empty roots. Meaningful actions can still use manual spans;
+            // fetch/xhr and document-load instrumentation keep their real parents.
+            interactions: false,
             fetch: {
                 propagateTraceHeaderCorsUrls: targets,
                 advancedNetworkCapture: () => advancedNetworkCapture,
-                applyCustomAttributesOnSpan: stripNetworkQuery,
+                applyCustomAttributesOnSpan: finishNetworkSpan,
             },
             xhr: {
                 propagateTraceHeaderCorsUrls: targets,
                 advancedNetworkCapture: () => advancedNetworkCapture,
-                applyCustomAttributesOnSpan: stripNetworkQuery,
+                applyCustomAttributesOnSpan: finishNetworkSpan,
             },
         },
         // Polls for window.Intercom on a timer; nothing here uses Intercom.
@@ -375,6 +671,18 @@ function clampRate(rate) {
     }
     return Math.min(1, Math.max(0, rate));
 }
+/** See "One session per visit" in the header. Never throws. */
+function keepSessionWithoutCookies() {
+    try {
+        if (typeof document === "undefined") {
+            return;
+        }
+        installSessionCookieFallback(document, window.localStorage ?? null);
+    }
+    catch {
+        // localStorage access can throw (blocked storage): keep the SDK default.
+    }
+}
 function sessionStorageOrNull() {
     try {
         return window.sessionStorage;
@@ -391,7 +699,27 @@ export function stripUrlQuery(url) {
     return cut === -1 ? url : url.slice(0, cut);
 }
 // applyCustomAttributesOnSpan for both instrumentations: it runs before the
-// span ends, so the rewritten value is the one exported.
+// span ends, and after HyperDX's own `HTTP <METHOD>` rename, so the values
+// set here are the ones exported. The span carries the RUM session as
+// `session.id` (the resource's rum.sessionId says the same for the browser;
+// the attribute is what the backend's own spans carry too, so a trace is found
+// by session from either side).
+function finishNetworkSpan(span) {
+    stripNetworkQuery(span);
+    const url = span.attributes?.["url.full"] ?? span.attributes?.["http.url"];
+    const method = span.attributes?.["http.request.method"] ??
+        span.attributes?.["http.method"];
+    if (typeof url === "string" && typeof span.updateName === "function") {
+        const name = spanRouteName(typeof method === "string" ? method : "", url);
+        if (name) {
+            span.updateName(name);
+        }
+    }
+    const session = rumSessionId();
+    if (session) {
+        span.setAttribute("session.id", session);
+    }
+}
 function stripNetworkQuery(span) {
     for (const key of URL_ATTRIBUTES) {
         const value = span.attributes?.[key];
@@ -403,6 +731,31 @@ function stripNetworkQuery(span) {
         }
     }
 }
+// A Connect/gRPC procedure: `/<package>.<Service>/<Method>`, the service and
+// method PascalCase as protobuf declares them. The whole path is the route,
+// fixed by the proto, so it carries no request values.
+const RPC_PATH = /^\/[A-Za-z_]\w*(?:\.[A-Za-z_]\w*)*\.[A-Z]\w*\/[A-Z]\w*$/;
+/**
+ * The name a fetch/XHR span gets: `<METHOD> /<package>.<Service>/<Method>`,
+ * the server span's name with the method in front, when the URL is a
+ * Connect/gRPC procedure. Empty for any other URL, which keeps the SDK's
+ * `HTTP <METHOD>`: an arbitrary path can hold values (ids, tokens, emails) no
+ * pattern recognises reliably, and a span name must be neither sensitive nor
+ * unbounded. Empty too when `url` cannot be parsed. Exported for tests.
+ */
+export function spanRouteName(method, url) {
+    let path;
+    try {
+        path = new URL(url, "http://base.invalid").pathname;
+    }
+    catch {
+        return "";
+    }
+    if (!RPC_PATH.test(path)) {
+        return "";
+    }
+    return `${method.trim().toUpperCase() || "POST"} ${path}`;
+}
 /**
  * resolveIngestUrl turns the configured endpoint into the absolute URL the SDK
  * is given, or null when telemetry is off. A path resolves against the page