@monoscopetech/browser 0.8.0 → 0.9.0

package/dist/router.d.ts

@@ -1,12 +1,12 @@
-type EmitFn = (name: string, attrs: Record<string, string | number>) => void;
+type NavFn = (from: string, to: string, method: string) => void;
 export declare class SPARouter {
-    private emit;
+    private onNavigation;
     private currentUrl;
     private _active;
     private origPushState;
     private origReplaceState;
     private popstateHandler;
-    constructor(emit: EmitFn);
+    constructor(onNavigation: NavFn);
     start(): void;
     stop(): void;
 }

package/dist/router.js

@@ -1,12 +1,12 @@
 import { addBreadcrumb } from "./breadcrumbs";
 export class SPARouter {
-    constructor(emit) {
+    constructor(onNavigation) {
         this.currentUrl = "";
         this._active = false;
         this.origPushState = null;
         this.origReplaceState = null;
         this.popstateHandler = null;
-        this.emit = emit;
+        this.onNavigation = onNavigation;
     }
     start() {
         if (typeof window === "undefined" || this._active)
@@ -23,12 +23,7 @@ export class SPARouter {
                     return;
                 this.currentUrl = to;
                 addBreadcrumb({ type: "navigation", message: `${from} → ${to}`, data: { method } });
-                this.emit("navigation", {
-                    "navigation.from": from,
-                    "navigation.to": to,
-                    "navigation.method": method,
-                    "page.title": document.title,
-                });
+                this.onNavigation(from, to, method);
             }
             catch (e) {
                 try {

package/dist/tracing.d.ts

@@ -1,9 +1,18 @@
 import { MonoscopeConfig, MonoscopeUser } from "./types";
 import { Span } from "@opentelemetry/api";
+export type MonoscopeKind = "page_load" | "navigation" | "interaction" | "network" | "resource" | "web_vital" | "error" | "long_task" | "custom";
+export declare function shortPath(url: string): string;
+export declare function describeElement(el: EventTarget | Element | null | undefined): string;
+/**
+ * RFC4122 v4 id with a fallback for non-secure contexts (HTTP / file:// /
+ * older Safari/Edge) where `crypto.randomUUID` is undefined.
+ */
+export declare function newId(): string;
 export declare class OpenTelemetryManager {
     private config;
     private sessionId;
     private tabId;
+    private pageviewId;
     private provider;
     private processor;
     private longTaskObserver;
@@ -11,18 +20,36 @@ export declare class OpenTelemetryManager {
     private _enabled;
     private _configured;
     private _firstExportLogged;
-    private pageSpan;
-    private pageContext;
-    private endPageSpanHandler;
+    private routeSpan;
+    private routeContext;
+    private routeIdleTimer;
+    private flushOnHideHandler;
+    private visibilityHandler;
     onExportStatus: ((ok: boolean) => void) | null;
+    onSpanStart: (() => void) | null;
     constructor(config: MonoscopeConfig, sessionId: string, tabId: string);
     private createProvider;
     private commonAttrs;
     private applyCommonAttrs;
     configure(): void;
-    private startPageSpan;
-    getPageContext(): import("@opentelemetry/api").Context | null;
-    private withPageContext;
+    getPageviewId(): string;
+    rotatePageview(): string;
+    /**
+     * Open a short-lived route.change root span for an SPA navigation. Closes
+     * any previous route span, rotates pageview.id, and publishes the span as
+     * the active context so async work started in the same Zone (fetch/XHR)
+     * inherits it as parent. Auto-closes after ROUTE_IDLE_MS or on next nav.
+     */
+    startRouteChange(from: string, to: string, method: string): void;
+    endRouteChange(): void;
+    /**
+     * Flush pending spans before the JS context is destroyed. Critical for
+     * MPAs where every navigation unloads the page, and still valuable for
+     * SPAs at tab close. pagehide is preferred over beforeunload (fires for
+     * bfcache eviction and mobile backgrounding; beforeunload does not).
+     */
+    private installFlushOnHide;
+    private withActiveContext;
     emitSpan(name: string, attrs: Record<string, string | number | boolean>, configure?: (span: Span) => void): void;
     private observeLongTasks;
     private observeResourceTiming;

package/dist/tracing.js

@@ -12,18 +12,71 @@ import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
 import { context, SpanStatusCode, trace } from "@opentelemetry/api";
 const MONOSCOPE_TRACER = "monoscope";
+const ROUTE_IDLE_MS = 3000;
+// Display-label helpers. These derive a human-readable label ("what happened?")
+// from raw span attributes so trace viewers don't have to reinvent the wheel.
+export function shortPath(url) {
+    try {
+        const u = new URL(url, typeof location !== "undefined" ? location.href : "http://_");
+        return u.pathname + (u.search ? "?…" : "");
+    }
+    catch {
+        return url.slice(0, 80);
+    }
+}
+export function describeElement(el) {
+    const e = el;
+    if (!e || !e.tagName)
+        return "?";
+    const aria = e.getAttribute?.("aria-label");
+    if (aria)
+        return aria;
+    const text = (e.textContent || "").trim().replace(/\s+/g, " ").slice(0, 40);
+    if (text)
+        return text;
+    const id = e.id ? `#${e.id}` : "";
+    const cls = (e.getAttribute?.("class") || "").split(" ").filter(Boolean)[0];
+    return `${e.tagName.toLowerCase()}${id}${cls ? `.${cls}` : ""}`;
+}
+/**
+ * RFC4122 v4 id with a fallback for non-secure contexts (HTTP / file:// /
+ * older Safari/Edge) where `crypto.randomUUID` is undefined.
+ */
+export function newId() {
+    try {
+        if (typeof crypto !== "undefined" && crypto.randomUUID)
+            return crypto.randomUUID();
+    }
+    catch { /* fall through */ }
+    const b = new Uint8Array(16);
+    try {
+        crypto.getRandomValues(b);
+    }
+    catch {
+        for (let i = 0; i < 16; i++)
+            b[i] = (Math.random() * 256) | 0;
+    }
+    b[6] = (b[6] & 0x0f) | 0x40;
+    b[8] = (b[8] & 0x3f) | 0x80;
+    const h = Array.from(b, x => x.toString(16).padStart(2, "0")).join("");
+    return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
+}
 export class OpenTelemetryManager {
     constructor(config, sessionId, tabId) {
+        this.pageviewId = "";
         this.processor = null;
         this.longTaskObserver = null;
         this.resourceObserver = null;
         this._enabled = true;
         this._configured = false;
         this._firstExportLogged = false;
-        this.pageSpan = null;
-        this.pageContext = null;
-        this.endPageSpanHandler = null;
+        this.routeSpan = null;
+        this.routeContext = null;
+        this.routeIdleTimer = null;
+        this.flushOnHideHandler = null;
+        this.visibilityHandler = null;
         this.onExportStatus = null;
+        this.onSpanStart = null;
         this.config = config;
         this.sessionId = sessionId;
         this.tabId = tabId;
@@ -66,19 +119,32 @@ export class OpenTelemetryManager {
         });
         const processor = new BatchSpanProcessor(wrappedExporter);
         this.processor = processor;
+        // Count every span at start — covers auto-instrumentations, internal
+        // emitSpan, and manual APIs uniformly. onEnd would undercount dropped
+        // spans; onStart reflects telemetry volume the SDK actually observed.
+        const countingProcessor = {
+            onStart: () => { try {
+                self.onSpanStart?.();
+            }
+            catch { /* never throw from processor */ } },
+            onEnd: () => { },
+            shutdown: () => Promise.resolve(),
+            forceFlush: () => Promise.resolve(),
+        };
         return new WebTracerProvider({
             resource: resourceFromAttributes({
                 [ATTR_SERVICE_NAME]: serviceName,
                 "x-api-key": apiKey,
                 ...resourceAttributes,
             }),
-            spanProcessors: [processor],
+            spanProcessors: [processor, countingProcessor],
         });
     }
     commonAttrs() {
         const attrs = {
             "session.id": this.sessionId,
             "tab.id": this.tabId,
+            "pageview.id": this.pageviewId,
             "page.url": location.href,
             "page.title": document.title,
         };
@@ -100,13 +166,29 @@ export class OpenTelemetryManager {
         if (typeof window === "undefined" || this._configured)
             return;
         this._configured = true;
+        // Sticky per-tab sampling decision so MPA navigations and SPA reloads don't
+        // produce half-traced sessions. sessionStorage is tab-scoped.
         const rate = Math.max(0, Math.min(1, this.config.sampleRate ?? 1));
-        if (Math.random() >= rate) {
+        let sampled;
+        try {
+            const cached = sessionStorage.getItem("monoscope-sampled");
+            if (cached === "1" || cached === "0")
+                sampled = cached === "1";
+            else {
+                sampled = Math.random() < rate;
+                sessionStorage.setItem("monoscope-sampled", sampled ? "1" : "0");
+            }
+        }
+        catch {
+            sampled = Math.random() < rate;
+        }
+        if (!sampled) {
             this._enabled = false;
             if (this.config.debug)
                 console.log("MonoscopeOTel: sampled out");
             return;
         }
+        this.pageviewId = newId();
         this.provider.register({
             contextManager: new ZoneContextManager(),
             propagator: new W3CTraceContextPropagator(),
@@ -118,45 +200,155 @@ export class OpenTelemetryManager {
             /^https?:\/\/(?:[^\/]+\.)?monoscope\.tech\//,
         ];
         const addAttrs = (span) => this.applyCommonAttrs(span);
+        const stamp = (span, kind, label) => {
+            this.applyCommonAttrs(span);
+            span.setAttribute("monoscope.kind", kind);
+            if (label)
+                span.setAttribute("monoscope.display.label", label);
+        };
+        // User interactions: default to click/submit only. Tracing every keydown/
+        // mouseover would flood the backend; consumers can override via
+        // instrumentations config to opt into more.
+        const userInteraction = this.config.enableUserInteraction !== false
+            ? [new UserInteractionInstrumentation({
+                    eventNames: ["click", "submit"],
+                    shouldPreventSpanCreation: (eventType, element, span) => {
+                        stamp(span, "interaction", `${eventType} · ${describeElement(element)}`);
+                        return false;
+                    },
+                })]
+            : [];
         registerInstrumentations({
             tracerProvider: this.provider,
             instrumentations: [
                 ...(this.config.instrumentations || []),
                 new DocumentLoadInstrumentation({
                     ignoreNetworkEvents: !this.config.enableNetworkEvents,
-                    applyCustomAttributesOnSpan: { documentLoad: addAttrs },
+                    applyCustomAttributesOnSpan: {
+                        documentLoad: (span) => stamp(span, "page_load", `Page · ${shortPath(location.href)}`),
+                        resourceFetch: (span) => stamp(span, "resource"),
+                    },
                 }),
                 new XMLHttpRequestInstrumentation({
-                    propagateTraceHeaderCorsUrls: headerUrls, ignoreUrls, applyCustomAttributesOnSpan: addAttrs,
+                    propagateTraceHeaderCorsUrls: headerUrls, ignoreUrls,
+                    applyCustomAttributesOnSpan: (span, xhr) => {
+                        const url = xhr.responseURL;
+                        stamp(span, "network", url ? `XHR · ${shortPath(url)}` : undefined);
+                    },
                 }),
                 new FetchInstrumentation({
-                    propagateTraceHeaderCorsUrls: headerUrls, ignoreUrls, applyCustomAttributesOnSpan: addAttrs,
+                    propagateTraceHeaderCorsUrls: headerUrls, ignoreUrls,
+                    applyCustomAttributesOnSpan: (span, request) => {
+                        let url;
+                        let method = "GET";
+                        if (typeof request === "string")
+                            url = request;
+                        else if (request && typeof request.url === "string") {
+                            url = request.url;
+                            method = request.method || "GET";
+                        }
+                        else if (request && typeof request.method === "string") {
+                            method = request.method;
+                        }
+                        stamp(span, "network", url ? `${method} · ${shortPath(url)}` : undefined);
+                    },
                 }),
-                ...(this.config.enableUserInteraction ? [new UserInteractionInstrumentation()] : []),
+                ...userInteraction,
             ],
         });
-        this.startPageSpan();
-        this.observeLongTasks();
-        this.observeResourceTiming();
+        if (this.config.captureLongTasks !== false)
+            this.observeLongTasks();
+        if (this.config.captureResourceTiming)
+            this.observeResourceTiming();
+        this.installFlushOnHide();
     }
-    startPageSpan() {
-        const tracer = trace.getTracer(MONOSCOPE_TRACER);
-        this.pageSpan = tracer.startSpan("browser.session", { attributes: this.commonAttrs() });
-        this.pageContext = trace.setSpan(context.active(), this.pageSpan);
-        this.endPageSpanHandler = () => { this.pageSpan?.end(); this.pageSpan = null; };
-        window.addEventListener("pagehide", this.endPageSpanHandler);
-        window.addEventListener("beforeunload", this.endPageSpanHandler);
+    getPageviewId() { return this.pageviewId; }
+    rotatePageview() {
+        this.pageviewId = newId();
+        return this.pageviewId;
+    }
+    /**
+     * Open a short-lived route.change root span for an SPA navigation. Closes
+     * any previous route span, rotates pageview.id, and publishes the span as
+     * the active context so async work started in the same Zone (fetch/XHR)
+     * inherits it as parent. Auto-closes after ROUTE_IDLE_MS or on next nav.
+     */
+    startRouteChange(from, to, method) {
+        try {
+            this.endRouteChange();
+            this.rotatePageview();
+            const tracer = trace.getTracer(MONOSCOPE_TRACER);
+            const span = tracer.startSpan("route.change", {
+                attributes: {
+                    "navigation.from": from,
+                    "navigation.to": to,
+                    "navigation.method": method,
+                    "monoscope.kind": "navigation",
+                    "monoscope.display.label": `Nav · ${shortPath(from)} → ${shortPath(to)}`,
+                },
+            });
+            this.applyCommonAttrs(span);
+            this.routeSpan = span;
+            this.routeContext = trace.setSpan(context.active(), span);
+            this.routeIdleTimer = setTimeout(() => {
+                try {
+                    this.endRouteChange();
+                }
+                catch (e) {
+                    if (this.config.debug)
+                        console.warn("Monoscope: route idle close failed", e);
+                }
+            }, ROUTE_IDLE_MS);
+        }
+        catch (e) {
+            if (this.config.debug)
+                console.warn("Monoscope: startRouteChange failed", e);
+            this.routeSpan = null;
+            this.routeContext = null;
+            this.routeIdleTimer = null;
+        }
+    }
+    endRouteChange() {
+        if (this.routeIdleTimer) {
+            clearTimeout(this.routeIdleTimer);
+            this.routeIdleTimer = null;
+        }
+        this.routeSpan?.end();
+        this.routeSpan = null;
+        this.routeContext = null;
+    }
+    /**
+     * Flush pending spans before the JS context is destroyed. Critical for
+     * MPAs where every navigation unloads the page, and still valuable for
+     * SPAs at tab close. pagehide is preferred over beforeunload (fires for
+     * bfcache eviction and mobile backgrounding; beforeunload does not).
+     */
+    installFlushOnHide() {
+        const flush = () => {
+            try {
+                this.endRouteChange();
+                this.processor?.forceFlush().catch(() => { });
+            }
+            catch (e) {
+                if (this.config.debug)
+                    console.warn("Monoscope: flush on hide failed", e);
+            }
+        };
+        this.flushOnHideHandler = flush;
+        this.visibilityHandler = () => { if (document.visibilityState === "hidden")
+            flush(); };
+        window.addEventListener("pagehide", this.flushOnHideHandler);
+        document.addEventListener("visibilitychange", this.visibilityHandler);
     }
-    getPageContext() { return this.pageContext; }
-    withPageContext(fn) {
-        if (this.pageContext)
-            return context.with(this.pageContext, fn);
+    withActiveContext(fn) {
+        if (this.routeContext)
+            return context.with(this.routeContext, fn);
         return fn();
     }
     emitSpan(name, attrs, configure) {
         try {
             const tracer = trace.getTracer(MONOSCOPE_TRACER);
-            this.withPageContext(() => tracer.startActiveSpan(name, (span) => {
+            this.withActiveContext(() => tracer.startActiveSpan(name, (span) => {
                 this.applyCommonAttrs(span);
                 for (const [k, v] of Object.entries(attrs))
                     span.setAttribute(k, v);
@@ -181,6 +373,8 @@ export class OpenTelemetryManager {
                         const attrs = {
                             "longtask.duration": entry.duration,
                             "longtask.name": entry.name,
+                            "monoscope.kind": "long_task",
+                            "monoscope.display.label": `Long task · ${Math.round(entry.duration)}ms`,
                         };
                         const attr = entry.attribution;
                         if (attr?.[0]?.containerSrc)
@@ -214,12 +408,15 @@ export class OpenTelemetryManager {
                         continue;
                     try {
                         const re = entry;
+                        const base = re.name.split("?")[0].split("/").pop() || re.name;
                         this.emitSpan("resource", {
                             "resource.name": re.name,
                             "resource.duration": re.duration,
                             "resource.type": re.initiatorType,
                             "resource.transferSize": re.transferSize,
                             "resource.encodedBodySize": re.encodedBodySize,
+                            "monoscope.kind": "resource",
+                            "monoscope.display.label": `${re.initiatorType} · ${base}`,
                         });
                     }
                     catch (e) {
@@ -236,7 +433,7 @@ export class OpenTelemetryManager {
     }
     startSpan(name, fn) {
         const tracer = trace.getTracer(MONOSCOPE_TRACER);
-        return this.withPageContext(() => tracer.startActiveSpan(name, (span) => {
+        return this.withActiveContext(() => tracer.startActiveSpan(name, (span) => {
             this.applyCommonAttrs(span);
             try {
                 const result = fn(span);
@@ -266,14 +463,15 @@ export class OpenTelemetryManager {
     async shutdown() {
         this.longTaskObserver?.disconnect();
         this.resourceObserver?.disconnect();
-        if (this.endPageSpanHandler && typeof window !== "undefined") {
-            this.endPageSpanHandler();
-            window.removeEventListener("pagehide", this.endPageSpanHandler);
-            window.removeEventListener("beforeunload", this.endPageSpanHandler);
-            this.endPageSpanHandler = null;
+        this.endRouteChange();
+        if (this.flushOnHideHandler) {
+            window.removeEventListener("pagehide", this.flushOnHideHandler);
+            this.flushOnHideHandler = null;
+        }
+        if (this.visibilityHandler) {
+            document.removeEventListener("visibilitychange", this.visibilityHandler);
+            this.visibilityHandler = null;
         }
-        this.pageSpan = null;
-        this.pageContext = null;
         this._configured = false;
         await this.provider.shutdown();
     }

package/dist/types.d.ts

@@ -16,6 +16,8 @@ export type MonoscopeConfig = {
     replaySampleRate?: number;
     enabled?: boolean;
     resourceTimingThresholdMs?: number;
+    captureResourceTiming?: boolean;
+    captureLongTasks?: boolean;
     enableUserInteraction?: boolean;
 };
 export type MonoscopeUser = {

package/dist/web-vitals.js

@@ -13,12 +13,17 @@ export class WebVitalsCollector {
             const report = (m) => {
                 if (!this._enabled)
                     return;
+                // CLS is unitless; the others are milliseconds.
+                const unit = m.name === "CLS" ? "" : "ms";
+                const value = m.name === "CLS" ? m.value.toFixed(3) : Math.round(m.value);
                 this.emit(`web-vital.${m.name}`, {
                     "vital.name": m.name,
                     "vital.value": m.value,
                     "vital.rating": m.rating,
                     "vital.id": m.id,
                     "vital.navigationType": m.navigationType,
+                    "monoscope.kind": "web_vital",
+                    "monoscope.display.label": `${m.name} · ${value}${unit} (${m.rating})`,
                 });
             };
             [onCLS, onINP, onLCP, onFCP, onTTFB].forEach(fn => fn(report));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monoscopetech/browser",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",