@obtrace/browser 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present Obtrace
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,85 @@
+# obtrace-sdk-browser
+
+Browser SDK for Obtrace with frontend wrappers.
+
+## Install
+
+```bash
+npm install @obtrace/sdk-browser
+# or
+bun add @obtrace/sdk-browser
+```
+
+## Quickstart
+
+### Simplified setup
+
+The API key resolves `tenant_id`, `project_id`, `app_id`, and `env` automatically on the server side, so only three fields are needed:
+
+```ts
+import { initBrowserSDK } from "@obtrace/sdk-browser/browser";
+
+const sdk = initBrowserSDK({
+  apiKey: "obt_live_...",
+  ingestBaseUrl: "https://ingest.obtrace.io",
+  serviceName: "web-app",
+});
+```
+
+### Full configuration
+
+For advanced use cases you can override the resolved values explicitly:
+
+```ts
+import { initBrowserSDK, SemanticMetrics } from "@obtrace/sdk-browser/browser";
+
+const sdk = initBrowserSDK({
+  apiKey: "<API_KEY>",
+  ingestBaseUrl: "https://inject.obtrace.ai",
+  serviceName: "web-app",
+  tenantId: "tenant-prod",
+  projectId: "project-prod",
+  appId: "web",
+  env: "prod"
+});
+
+sdk.metric(SemanticMetrics.webVitalLcp, 2400, "ms", {
+  route: "/checkout",
+});
+
+sdk.span({
+  name: "ui.checkout.submit",
+  attrs: {
+    "feature.name": "checkout",
+    "ui.action": "submit",
+  },
+});
+```
+
+## Canonical metrics and custom spans
+
+- Use `SemanticMetrics` whenever possible so dashboards, explorer and AI work against the global metric catalog.
+- Browser vitals still emit built-in aliases internally, but the platform normalizes them to canonical names such as `web.vital.lcp` and `web.vital.inp`.
+- Custom spans use `sdk.span({ name, attrs, statusCode, statusMessage })`.
+
+## Frontend wrappers
+
+- Vite
+- React
+- Next (browser side)
+- Vue
+- Angular
+- Svelte
+
+## Examples
+
+- `examples/browser/example.ts`
+- `examples/react-vite/main.tsx`
+- `examples/vue-vite/main.ts`
+
+## Docs
+
+- `docs/getting-started.md`
+- `docs/browser.md`
+- `docs/security.md`
+- `docs/troubleshooting.md`

package/dist/auto.js

@@ -0,0 +1,126 @@
+import { initBrowserSDK } from "./browser/index";
+let _sdk = null;
+let _observer = null;
+function readWindowConfig() {
+    if (typeof window !== "undefined" && window.__OBTRACE_CONFIG__) {
+        const cfg = window.__OBTRACE_CONFIG__;
+        return {
+            apiKey: cfg.apiKey,
+            ingestBaseUrl: cfg.ingestBaseUrl,
+            serviceName: cfg.serviceName,
+            appId: cfg.appId,
+            env: cfg.env,
+        };
+    }
+    return {};
+}
+function readMetaTag(name) {
+    if (typeof document === "undefined")
+        return undefined;
+    const el = document.querySelector(`meta[name="${name}"]`);
+    return el?.getAttribute("content") || undefined;
+}
+function readMetaConfig() {
+    return {
+        apiKey: readMetaTag("obtrace-api-key"),
+        ingestBaseUrl: readMetaTag("obtrace-ingest-url"),
+        serviceName: readMetaTag("obtrace-service-name"),
+        appId: readMetaTag("obtrace-app-id"),
+        env: readMetaTag("obtrace-env"),
+    };
+}
+function resolveEnvVar(key) {
+    if (typeof globalThis !== "undefined" && "process" in globalThis) {
+        const val = globalThis.process.env[key];
+        if (val)
+            return val;
+    }
+    return undefined;
+}
+function readEnvConfig() {
+    const prefixes = ["VITE_", "NEXT_PUBLIC_", "REACT_APP_", ""];
+    let apiKey;
+    let ingestBaseUrl;
+    let serviceName;
+    let appId;
+    let env;
+    for (const p of prefixes) {
+        apiKey = apiKey || resolveEnvVar(`${p}OBTRACE_API_KEY`);
+        ingestBaseUrl = ingestBaseUrl || resolveEnvVar(`${p}OBTRACE_INGEST_BASE_URL`);
+        serviceName = serviceName || resolveEnvVar(`${p}OBTRACE_SERVICE_NAME`);
+        appId = appId || resolveEnvVar(`${p}OBTRACE_APP_ID`);
+        env = env || resolveEnvVar(`${p}OBTRACE_ENV`);
+    }
+    env = env || resolveEnvVar("NODE_ENV");
+    return { apiKey, ingestBaseUrl, serviceName, appId, env };
+}
+function merge(...sources) {
+    const merged = {};
+    for (const src of sources) {
+        for (const k of Object.keys(src)) {
+            if (!merged[k] && src[k]) {
+                merged[k] = src[k];
+            }
+        }
+    }
+    if (!merged.apiKey || !merged.ingestBaseUrl)
+        return null;
+    return {
+        apiKey: merged.apiKey,
+        ingestBaseUrl: merged.ingestBaseUrl,
+        serviceName: merged.serviceName || "web-app",
+        appId: merged.appId,
+        env: merged.env || "production",
+    };
+}
+function detectConfig() {
+    return merge(readWindowConfig(), readMetaConfig(), readEnvConfig());
+}
+function initFromConfig(config) {
+    if (_sdk)
+        return;
+    _sdk = initBrowserSDK(config);
+    teardownObserver();
+}
+function teardownObserver() {
+    if (_observer) {
+        _observer.disconnect();
+        _observer = null;
+    }
+}
+function setupDeferredInit() {
+    if (typeof document === "undefined" || typeof MutationObserver === "undefined")
+        return;
+    _observer = new MutationObserver(() => {
+        const config = merge(readWindowConfig(), readMetaConfig(), readEnvConfig());
+        if (config) {
+            initFromConfig(config);
+        }
+    });
+    const head = document.head || document.documentElement;
+    _observer.observe(head, { childList: true });
+    setTimeout(() => {
+        if (!_sdk) {
+            teardownObserver();
+        }
+    }, 5000);
+}
+function autoInit() {
+    if (typeof window === "undefined")
+        return;
+    if (_sdk)
+        return;
+    const config = detectConfig();
+    if (config) {
+        initFromConfig(config);
+        return;
+    }
+    console.warn("[obtrace] No configuration found. Provide config via window.__OBTRACE_CONFIG__, " +
+        '<meta name="obtrace-api-key">, or build-time env vars (VITE_OBTRACE_API_KEY, etc). ' +
+        "Deferring initialization until config appears.");
+    setupDeferredInit();
+}
+autoInit();
+export function getObtrace() {
+    return _sdk;
+}

package/dist/browser/breadcrumbs.js

@@ -0,0 +1,41 @@
+const MAX_BREADCRUMBS = 100;
+const buffer = [];
+export function addBreadcrumb(crumb) {
+    buffer.push(crumb);
+    if (buffer.length > MAX_BREADCRUMBS) {
+        buffer.shift();
+    }
+}
+export function getBreadcrumbs() {
+    return buffer.slice();
+}
+export function clearBreadcrumbs() {
+    buffer.length = 0;
+}
+export function getElementSelector(el) {
+    if (!el)
+        return "";
+    let sel = el.tagName.toLowerCase();
+    if (el.id)
+        sel += `#${el.id}`;
+    else if (el.className && typeof el.className === "string") {
+        sel += `.${el.className.trim().split(/\s+/).slice(0, 2).join(".")}`;
+    }
+    return sel;
+}
+export function installClickBreadcrumbs() {
+    if (typeof document === "undefined")
+        return () => { };
+    const handler = (ev) => {
+        const target = ev.target;
+        addBreadcrumb({
+            timestamp: Date.now(),
+            category: "ui.click",
+            message: getElementSelector(target),
+            level: "info",
+            data: { x: ev.clientX, y: ev.clientY },
+        });
+    };
+    document.addEventListener("click", handler, true);
+    return () => document.removeEventListener("click", handler, true);
+}

package/dist/browser/clicks.js

@@ -0,0 +1,68 @@
+import { addBreadcrumb, getElementSelector } from "./breadcrumbs";
+const RAGE_THRESHOLD = 3;
+const RAGE_WINDOW_MS = 1000;
+const DEAD_CLICK_TIMEOUT_MS = 2000;
+const INTERACTIVE_TAGS = new Set(["A", "BUTTON", "INPUT", "SELECT", "TEXTAREA", "SUMMARY", "DETAILS"]);
+export function installClickTracking(tracer, sessionId) {
+    if (typeof document === "undefined")
+        return () => { };
+    const recent = [];
+    let pendingDeadCheck = null;
+    let networkAfterClick = false;
+    const networkListener = () => { networkAfterClick = true; };
+    const handler = (ev) => {
+        const target = ev.target;
+        if (!target)
+            return;
+        const selector = getElementSelector(target);
+        const now = Date.now();
+        recent.push({ selector, timestamp: now });
+        while (recent.length > 0 && now - recent[0].timestamp > RAGE_WINDOW_MS) {
+            recent.shift();
+        }
+        const sameElement = recent.filter(e => e.selector === selector);
+        if (sameElement.length >= RAGE_THRESHOLD) {
+            recent.length = 0;
+            addBreadcrumb({ timestamp: now, category: "ui.rage_click", message: selector, level: "warn" });
+            const span = tracer.startSpan("browser.rage_click", {
+                attributes: { "click.selector": selector, "click.count": sameElement.length, "session.id": sessionId },
+            });
+            span.end();
+        }
+        const isInteractive = INTERACTIVE_TAGS.has(target.tagName) ||
+            target.hasAttribute("onclick") ||
+            target.hasAttribute("role") ||
+            target.contentEditable === "true" ||
+            target.closest("a, button, [onclick], [role='button']") !== null;
+        if (!isInteractive) {
+            networkAfterClick = false;
+            if (pendingDeadCheck)
+                clearTimeout(pendingDeadCheck);
+            pendingDeadCheck = setTimeout(() => {
+                if (!networkAfterClick) {
+                    addBreadcrumb({ timestamp: now, category: "ui.dead_click", message: selector, level: "warn" });
+                    const span = tracer.startSpan("browser.dead_click", {
+                        attributes: { "click.selector": selector, "session.id": sessionId },
+                    });
+                    span.end();
+                }
+                pendingDeadCheck = null;
+            }, DEAD_CLICK_TIMEOUT_MS);
+        }
+    };
+    document.addEventListener("click", handler, true);
+    window.addEventListener("fetch", networkListener);
+    const origXhrSend = XMLHttpRequest.prototype.send;
+    const xhrWrapper = function (...args) {
+        networkAfterClick = true;
+        return origXhrSend.apply(this, args);
+    };
+    XMLHttpRequest.prototype.send = xhrWrapper;
+    return () => {
+        document.removeEventListener("click", handler, true);
+        window.removeEventListener("fetch", networkListener);
+        XMLHttpRequest.prototype.send = origXhrSend;
+        if (pendingDeadCheck)
+            clearTimeout(pendingDeadCheck);
+    };
+}

package/dist/browser/console.js

@@ -0,0 +1,58 @@
+import { addBreadcrumb } from "./breadcrumbs";
+const LEVEL_MAP = {
+    debug: "debug",
+    log: "info",
+    info: "info",
+    warn: "warn",
+    error: "error",
+};
+let patched = false;
+let originals = {};
+export function installConsoleCapture(tracer, sessionId) {
+    if (patched || typeof console === "undefined")
+        return () => { };
+    patched = true;
+    const methods = ["debug", "log", "info", "warn", "error"];
+    originals = {};
+    for (const method of methods) {
+        const original = console[method].bind(console);
+        originals[method] = original;
+        const level = LEVEL_MAP[method];
+        console[method] = (...args) => {
+            original(...args);
+            let message;
+            let attrs = {};
+            if (args.length === 1 && typeof args[0] === "object" && args[0] !== null && !Array.isArray(args[0])) {
+                const obj = args[0];
+                message = String(obj.msg || obj.message || JSON.stringify(obj));
+                for (const [k, v] of Object.entries(obj)) {
+                    if (k === "msg" || k === "message")
+                        continue;
+                    if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") {
+                        attrs[k] = v;
+                    }
+                }
+            }
+            else {
+                message = args.map(a => typeof a === "string" ? a : JSON.stringify(a)).join(" ");
+            }
+            addBreadcrumb({ timestamp: Date.now(), category: `console.${method}`, message, level, data: attrs });
+            const span = tracer.startSpan("browser.console", {
+                attributes: {
+                    "log.severity": level.toUpperCase(),
+                    "log.message": message.slice(0, 1024),
+                    "session.id": sessionId,
+                    ...attrs,
+                },
+            });
+            span.end();
+        };
+    }
+    return () => {
+        for (const [method, original] of Object.entries(originals)) {
+            console[method] = original;
+        }
+        originals = {};
+        patched = false;
+    };
+}

package/dist/browser/errors.js

@@ -0,0 +1,51 @@
+import { SpanStatusCode } from "@opentelemetry/api";
+import { addBreadcrumb, getBreadcrumbs } from "./breadcrumbs";
+export function installBrowserErrorHooks(tracer, sessionId) {
+    if (typeof window === "undefined") {
+        return () => undefined;
+    }
+    const onError = (ev) => {
+        addBreadcrumb({ timestamp: Date.now(), category: "error", message: ev.message || "window.error", level: "error" });
+        const breadcrumbs = getBreadcrumbs();
+        const span = tracer.startSpan("browser.error", {
+            attributes: {
+                "error.message": ev.message || "window.error",
+                "error.file": ev.filename || "",
+                "error.line": ev.lineno || 0,
+                "error.column": ev.colno || 0,
+                "breadcrumbs.count": breadcrumbs.length,
+                "breadcrumbs.json": JSON.stringify(breadcrumbs.slice(-20)),
+                ...(sessionId ? { "session.id": sessionId } : {}),
+            },
+        });
+        span.setStatus({ code: SpanStatusCode.ERROR, message: ev.message });
+        if (ev.error instanceof Error) {
+            span.recordException(ev.error);
+        }
+        span.end();
+    };
+    const onRejection = (ev) => {
+        const reason = typeof ev.reason === "string" ? ev.reason : JSON.stringify(ev.reason ?? {});
+        addBreadcrumb({ timestamp: Date.now(), category: "error", message: reason, level: "error" });
+        const breadcrumbs = getBreadcrumbs();
+        const span = tracer.startSpan("browser.unhandledrejection", {
+            attributes: {
+                "error.message": reason,
+                "breadcrumbs.count": breadcrumbs.length,
+                "breadcrumbs.json": JSON.stringify(breadcrumbs.slice(-20)),
+                ...(sessionId ? { "session.id": sessionId } : {}),
+            },
+        });
+        span.setStatus({ code: SpanStatusCode.ERROR, message: reason });
+        if (ev.reason instanceof Error) {
+            span.recordException(ev.reason);
+        }
+        span.end();
+    };
+    window.addEventListener("error", onError);
+    window.addEventListener("unhandledrejection", onRejection);
+    return () => {
+        window.removeEventListener("error", onError);
+        window.removeEventListener("unhandledrejection", onRejection);
+    };
+}