@genn-inc/cluebase-frontend-sdk 0.0.1

package/dist/instrumentation/network.js

@@ -0,0 +1,502 @@
+import { propagation, trace, } from "@opentelemetry/api";
+import { CompositePropagator, W3CTraceContextPropagator, } from "@opentelemetry/core";
+import { FetchInstrumentation } from "@opentelemetry/instrumentation-fetch";
+import { XMLHttpRequestInstrumentation, } from "@opentelemetry/instrumentation-xml-http-request";
+import { shouldPropagateTraceHeaders } from "@opentelemetry/sdk-trace-web";
+import { CLUEBASE_SDK_REQUEST_HEADER } from "../exporter/client.js";
+import { generateInteractionId, generateRequestId, generateRequestSpanId, generateTraceId, } from "../exporter/event-id.js";
+import { FRONTEND_EVENT_NAME } from "../provider/contracts.js";
+import { stripQueryFromUrl } from "./common.js";
+import { createRequestMeta, deriveFailureTypeFromStatus, getXhrResponseBody, headersToRecord, parseXhrHeaders, } from "./network-request.js";
+import { setResponseSpanAttributes } from "./network-span-attributes.js";
+const NETWORK_TRACER_NAME = "@genn-inc/cluebase-frontend-sdk/network";
+const networkMetaBySpan = new WeakMap();
+const xhrTraceContextBySpan = new WeakMap();
+const pendingRequestLifecycles = new Map();
+let activeCapture = null;
+let fetchInstrumentation = null;
+let xhrInstrumentation = null;
+let cluebaseNetworkPropagatorRegistered = false;
+const REQUEST_LIFECYCLE_ORPHAN_TIMEOUT_MS = 30000;
+// OTel fetch waits 300ms for browser resource timing before ending spans.
+const FETCH_SPAN_END_SETTLE_MS = 350;
+const pendingFetchSpanEndWaits = new Set();
+class ManagedFetchInstrumentation extends FetchInstrumentation {
+    teardown() {
+        this.disable();
+        const currentFetch = globalThis.fetch;
+        if (typeof currentFetch.__unwrap === "function") {
+            this._unwrap(globalThis, "fetch");
+        }
+    }
+}
+const normalizeTracePropagationOrigin = (value) => {
+    const trimmed = value.trim();
+    if (!trimmed)
+        return null;
+    try {
+        return new URL(trimmed).origin.toLowerCase();
+    }
+    catch {
+        return trimmed.toLowerCase();
+    }
+};
+const escapeRegExp = (value) => {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+};
+const urlPrefixPatterns = (prefixes) => {
+    return prefixes
+        .filter(Boolean)
+        .map((prefix) => new RegExp(`^${escapeRegExp(prefix)}`));
+};
+const tracePropagationPatterns = (origins) => {
+    return [...origins].map((origin) => new RegExp(`^${escapeRegExp(origin)}(?:/|$)`));
+};
+const hasSdkTransportHeader = (headers) => {
+    return Object.keys(headers).some((key) => key.toLowerCase() === CLUEBASE_SDK_REQUEST_HEADER.toLowerCase());
+};
+const shouldIgnoreUrl = (capture, url) => {
+    if (!url)
+        return false;
+    return capture.ignoreUrlPrefixes.some((prefix) => prefix && url.startsWith(prefix));
+};
+const toTraceHeaders = (capture, traceContext) => {
+    const observationContext = capture.context.getObservationContext?.() ?? null;
+    const headers = {
+        "x-cluebase-trace-id": traceContext.traceId,
+        "x-cluebase-request-id": traceContext.requestId,
+        "x-cluebase-request-span-id": traceContext.requestSpanId,
+    };
+    if (traceContext.parentSpanId) {
+        headers["x-cluebase-parent-span-id"] = traceContext.parentSpanId;
+    }
+    if (traceContext.interactionId) {
+        headers["x-cluebase-interaction-id"] = traceContext.interactionId;
+    }
+    if (traceContext.originFrontendInteractionId) {
+        headers["x-cluebase-origin-frontend-interaction-id"] =
+            traceContext.originFrontendInteractionId;
+    }
+    if (observationContext?.sessionId) {
+        headers["x-cluebase-session-id"] = observationContext.sessionId;
+    }
+    if (observationContext?.anonymousId) {
+        headers["x-cluebase-anonymous-id"] = observationContext.anonymousId;
+    }
+    if (observationContext?.userId) {
+        headers["x-cluebase-user-id"] = observationContext.userId;
+    }
+    if (observationContext?.organizationId) {
+        headers["x-cluebase-organization-id"] = observationContext.organizationId;
+    }
+    if (observationContext?.tabId) {
+        headers["x-cluebase-tab-id"] = observationContext.tabId;
+    }
+    return headers;
+};
+const traceContextFromMeta = (meta) => ({
+    traceId: meta.traceId,
+    parentSpanId: meta.parentSpanId,
+    requestId: meta.requestId,
+    requestSpanId: meta.requestSpanId,
+    interactionId: meta.interactionId,
+    interactionInitiator: meta.interactionInitiator,
+    interactionStartEventKind: meta.interactionStartEventKind,
+    originFrontendInteractionId: meta.originFrontendInteractionId,
+});
+const CLUEBASE_NETWORK_PROPAGATION_FIELDS = [
+    "x-cluebase-trace-id",
+    "x-cluebase-request-id",
+    "x-cluebase-request-span-id",
+    "x-cluebase-parent-span-id",
+    "x-cluebase-interaction-id",
+    "x-cluebase-origin-frontend-interaction-id",
+    "x-cluebase-session-id",
+    "x-cluebase-anonymous-id",
+    "x-cluebase-user-id",
+    "x-cluebase-organization-id",
+    "x-cluebase-tab-id",
+];
+class CluebaseNetworkTextMapPropagator {
+    inject(otelContext, carrier, setter) {
+        const capture = activeCapture;
+        if (!capture || capture.context.getConsent() === "denied")
+            return;
+        const span = trace.getSpan(otelContext);
+        if (!span)
+            return;
+        const existingMeta = networkMetaBySpan.get(span);
+        const traceContext = existingMeta !== undefined
+            ? traceContextFromMeta(existingMeta)
+            : createOtelRequestTraceContext(capture, span);
+        xhrTraceContextBySpan.set(span, traceContext);
+        for (const [key, value] of Object.entries(toTraceHeaders(capture, traceContext))) {
+            setter.set(carrier, key, value);
+        }
+    }
+    extract(otelContext, _carrier, _getter) {
+        return otelContext;
+    }
+    fields() {
+        return CLUEBASE_NETWORK_PROPAGATION_FIELDS;
+    }
+}
+const cluebaseNetworkPropagator = new CompositePropagator({
+    propagators: [
+        new W3CTraceContextPropagator(),
+        new CluebaseNetworkTextMapPropagator(),
+    ],
+});
+export const createCluebaseNetworkPropagator = () => cluebaseNetworkPropagator;
+const ensureCluebaseNetworkPropagator = () => {
+    if (cluebaseNetworkPropagatorRegistered)
+        return;
+    cluebaseNetworkPropagatorRegistered = propagation.setGlobalPropagator(cluebaseNetworkPropagator);
+};
+const readSpanAttributes = (span) => {
+    const attributes = span.attributes;
+    return attributes && typeof attributes === "object" ? attributes : {};
+};
+const readSpanStringAttribute = (span, keys) => {
+    const attributes = readSpanAttributes(span);
+    for (const key of keys) {
+        const value = attributes[key];
+        if (typeof value === "string" && value.length > 0)
+            return value;
+    }
+    return null;
+};
+const readSpanStartTimeMs = (span) => {
+    const startTime = span.startTime;
+    if (Array.isArray(startTime) &&
+        typeof startTime[0] === "number" &&
+        typeof startTime[1] === "number") {
+        return startTime[0] * 1000 + startTime[1] / 1000000;
+    }
+    if (startTime instanceof Date) {
+        return startTime.getTime();
+    }
+    if (typeof startTime === "number" && Number.isFinite(startTime)) {
+        return startTime;
+    }
+    return null;
+};
+const readOtelRequestUrl = (span) => readSpanStringAttribute(span, ["url.full", "http.url"]);
+const readOtelRequestMethod = (span) => readSpanStringAttribute(span, ["http.request.method", "http.method"]);
+const isRequestObject = (request) => typeof Request !== "undefined" && request instanceof Request;
+const createOtelRequestTraceContext = (capture, span) => {
+    const rawUrl = readOtelRequestUrl(span);
+    const base = capture.createRequestTraceContext({
+        method: readOtelRequestMethod(span),
+        urlKey: rawUrl ? stripQueryFromUrl(rawUrl) : null,
+    });
+    const spanContext = span.spanContext();
+    const parentSpanContext = span.parentSpanContext;
+    const spanTraceId = typeof spanContext.traceId === "string" && spanContext.traceId.length > 0
+        ? spanContext.traceId
+        : base.traceId;
+    const spanId = typeof spanContext.spanId === "string" && spanContext.spanId.length > 0
+        ? spanContext.spanId
+        : null;
+    return {
+        ...base,
+        traceId: spanTraceId,
+        parentSpanId: parentSpanContext?.spanId ?? base.parentSpanId,
+        requestSpanId: spanId ?? base.requestSpanId,
+    };
+};
+const fetchInstrumentationMethod = (request, span) => {
+    const method = request.method ?? readOtelRequestMethod(span) ?? "GET";
+    return method.toUpperCase();
+};
+const fetchInstrumentationHeaders = (request) => isRequestObject(request)
+    ? headersToRecord(request.headers)
+    : headersToRecord(request.headers);
+const fetchInstrumentationBody = (request) => isRequestObject(request) ? request.body : (request.body ?? null);
+const injectFetchCorrelationHeaders = (capture, request, meta) => {
+    if (!shouldPropagateTraceHeaders(meta.rawUrl, tracePropagationPatterns(capture.tracePropagationOrigins))) {
+        return;
+    }
+    const headers = toTraceHeaders(capture, traceContextFromMeta(meta));
+    if (isRequestObject(request)) {
+        for (const [key, value] of Object.entries(headers)) {
+            request.headers.set(key, value);
+        }
+        return;
+    }
+    const nextHeaders = new Headers(request.headers);
+    for (const [key, value] of Object.entries(headers)) {
+        nextHeaders.set(key, value);
+    }
+    request.headers = nextHeaders;
+};
+const createFetchMetaFromOtelRequest = (capture, span, request) => {
+    const rawUrl = readOtelRequestUrl(span);
+    if (!rawUrl || shouldIgnoreUrl(capture, rawUrl))
+        return null;
+    const requestHeaders = fetchInstrumentationHeaders(request);
+    if (hasSdkTransportHeader(requestHeaders))
+        return null;
+    const traceContext = createOtelRequestTraceContext(capture, span);
+    return createRequestMeta({
+        context: capture.context,
+        method: fetchInstrumentationMethod(request, span),
+        rawUrl,
+        requestHeaders,
+        body: fetchInstrumentationBody(request),
+        defaultRequestKind: "fetch",
+        traceContext,
+        startedAtMs: readSpanStartTimeMs(span) ?? Date.now(),
+        deniedKeys: capture.deniedKeys,
+    });
+};
+const createXhrMetaFromOtelSpan = (capture, span, xhr) => {
+    const responseUrl = typeof xhr.responseURL === "string" && xhr.responseURL.length > 0
+        ? xhr.responseURL
+        : null;
+    const rawUrl = readOtelRequestUrl(span) ?? responseUrl;
+    if (!rawUrl || shouldIgnoreUrl(capture, rawUrl))
+        return null;
+    return createRequestMeta({
+        context: capture.context,
+        method: readOtelRequestMethod(span) ?? "GET",
+        rawUrl,
+        requestHeaders: {},
+        body: null,
+        defaultRequestKind: "xhr",
+        traceContext: xhrTraceContextBySpan.get(span) ??
+            createOtelRequestTraceContext(capture, span),
+        startedAtMs: readSpanStartTimeMs(span) ?? Date.now(),
+        deniedKeys: capture.deniedKeys,
+    });
+};
+const emitSyntheticRequestFailedSpan = (meta, failureType, endedAtMs = Date.now()) => {
+    const tracer = activeCapture?.tracerProvider?.getTracer(NETWORK_TRACER_NAME) ??
+        trace.getTracer(NETWORK_TRACER_NAME);
+    const span = tracer.startSpan(FRONTEND_EVENT_NAME.requestFailed, {
+        startTime: meta.startedAtMs,
+    });
+    setResponseSpanAttributes(span, meta, {
+        normalizedResponseBody: null,
+        failureType,
+        durationMs: Math.max(0, endedAtMs - meta.startedAtMs),
+        observationContext: activeCapture?.context.getObservationContext?.() ?? null,
+        deniedKeys: activeCapture?.deniedKeys,
+    });
+    span.end(endedAtMs);
+    activeCapture?.context.requestFlush?.();
+};
+const clearPendingRequestLifecycle = (requestSpanId) => {
+    const pending = pendingRequestLifecycles.get(requestSpanId);
+    if (pending?.timeoutId) {
+        clearTimeout(pending.timeoutId);
+    }
+    pendingRequestLifecycles.delete(requestSpanId);
+};
+const schedulePendingRequestLifecycle = (meta) => {
+    clearPendingRequestLifecycle(meta.requestSpanId);
+    const timeoutId = setTimeout(() => {
+        const pending = pendingRequestLifecycles.get(meta.requestSpanId);
+        if (!pending)
+            return;
+        pendingRequestLifecycles.delete(meta.requestSpanId);
+        emitSyntheticRequestFailedSpan(pending.meta, "capture_lifecycle_timeout");
+    }, REQUEST_LIFECYCLE_ORPHAN_TIMEOUT_MS);
+    pendingRequestLifecycles.set(meta.requestSpanId, { meta, timeoutId });
+};
+const trackPendingRequestLifecycle = (meta) => {
+    schedulePendingRequestLifecycle(meta);
+};
+const markRequestLifecycleTerminal = (meta) => {
+    clearPendingRequestLifecycle(meta.requestSpanId);
+};
+const failOpenRequestLifecycles = (failureType) => {
+    const pending = Array.from(pendingRequestLifecycles.values());
+    for (const entry of pending) {
+        if (entry.timeoutId) {
+            clearTimeout(entry.timeoutId);
+        }
+        emitSyntheticRequestFailedSpan(entry.meta, failureType);
+    }
+    pendingRequestLifecycles.clear();
+};
+const trackFetchSpanEndWait = () => {
+    const wait = new Promise((resolve) => {
+        setTimeout(resolve, FETCH_SPAN_END_SETTLE_MS);
+    });
+    pendingFetchSpanEndWaits.add(wait);
+    void wait.finally(() => pendingFetchSpanEndWaits.delete(wait));
+};
+const waitForFetchSpanEnd = async () => {
+    if (pendingFetchSpanEndWaits.size === 0)
+        return;
+    await Promise.allSettled([...pendingFetchSpanEndWaits]);
+};
+const readFetchResponseHeaders = (result) => result instanceof Response ? headersToRecord(result.headers) : {};
+const readFetchResponseSizeBytes = (result) => {
+    if (!(result instanceof Response))
+        return undefined;
+    const contentLength = result.headers.get("content-length");
+    return contentLength && !Number.isNaN(Number(contentLength))
+        ? Number(contentLength)
+        : undefined;
+};
+const readFetchStatusCode = (result) => {
+    if (result instanceof Response)
+        return result.status;
+    const status = result.status;
+    return typeof status === "number" && status > 0 ? status : null;
+};
+const readFetchFailureType = (result, statusCode) => {
+    if (result instanceof Response)
+        return deriveFailureTypeFromStatus(result.status);
+    if (statusCode !== null)
+        return deriveFailureTypeFromStatus(statusCode);
+    return result.name || result.message || "fetch_error";
+};
+const configureFetchInstrumentation = (capture) => {
+    if (typeof globalThis.fetch !== "function")
+        return;
+    fetchInstrumentation = new ManagedFetchInstrumentation({
+        enabled: false,
+        semconvStabilityOptIn: "http/dup",
+        measureRequestSize: true,
+        ignoreNetworkEvents: false,
+        ignoreUrls: urlPrefixPatterns(capture.ignoreUrlPrefixes),
+        propagateTraceHeaderCorsUrls: tracePropagationPatterns(capture.tracePropagationOrigins),
+        requestHook: (span, request) => {
+            if (activeCapture !== capture ||
+                capture.context.getConsent() === "denied") {
+                return;
+            }
+            const meta = createFetchMetaFromOtelRequest(capture, span, request);
+            if (!meta)
+                return;
+            networkMetaBySpan.set(span, meta);
+            injectFetchCorrelationHeaders(capture, request, meta);
+            trackPendingRequestLifecycle(meta);
+        },
+        applyCustomAttributesOnSpan: (span, request, result) => {
+            if (capture.context.getConsent() === "denied")
+                return;
+            const meta = networkMetaBySpan.get(span) ??
+                createFetchMetaFromOtelRequest(capture, span, request);
+            if (!meta)
+                return;
+            networkMetaBySpan.set(span, meta);
+            const statusCode = readFetchStatusCode(result);
+            const failureType = readFetchFailureType(result, statusCode);
+            setResponseSpanAttributes(span, meta, {
+                statusCode,
+                responseHeaders: readFetchResponseHeaders(result),
+                normalizedResponseBody: null,
+                responseSizeBytes: readFetchResponseSizeBytes(result),
+                failureType,
+                durationMs: Date.now() - meta.startedAtMs,
+                observationContext: capture.context.getObservationContext?.() ?? null,
+                deniedKeys: capture.deniedKeys,
+            });
+            trackFetchSpanEndWait();
+            markRequestLifecycleTerminal(meta);
+            capture.context.requestFlush?.();
+        },
+    });
+    if (capture.tracerProvider) {
+        fetchInstrumentation.setTracerProvider(capture.tracerProvider);
+    }
+    fetchInstrumentation.enable();
+};
+const configureXhrInstrumentation = (capture) => {
+    if (!xhrInstrumentation) {
+        xhrInstrumentation = new XMLHttpRequestInstrumentation();
+    }
+    if (capture.tracerProvider) {
+        xhrInstrumentation.setTracerProvider(capture.tracerProvider);
+    }
+    const xhrConfig = {
+        enabled: true,
+        semconvStabilityOptIn: "http/dup",
+        measureRequestSize: true,
+        ignoreNetworkEvents: false,
+        ignoreUrls: urlPrefixPatterns(capture.ignoreUrlPrefixes),
+        propagateTraceHeaderCorsUrls: tracePropagationPatterns(capture.tracePropagationOrigins),
+        applyCustomAttributesOnSpan: (span, xhr) => {
+            if (capture.context.getConsent() === "denied")
+                return;
+            const meta = networkMetaBySpan.get(span) ??
+                createXhrMetaFromOtelSpan(capture, span, xhr);
+            if (!meta)
+                return;
+            networkMetaBySpan.set(span, meta);
+            trackPendingRequestLifecycle(meta);
+            const statusCode = xhr.status || null;
+            const failureType = statusCode === null
+                ? "network_error"
+                : deriveFailureTypeFromStatus(statusCode);
+            const responseHeaders = parseXhrHeaders(xhr.getAllResponseHeaders());
+            const normalizedResponseBody = getXhrResponseBody(xhr);
+            setResponseSpanAttributes(span, meta, {
+                statusCode,
+                responseHeaders,
+                normalizedResponseBody,
+                failureType,
+                durationMs: Date.now() - meta.startedAtMs,
+                observationContext: capture.context.getObservationContext?.() ?? null,
+                deniedKeys: capture.deniedKeys,
+            });
+            markRequestLifecycleTerminal(meta);
+            capture.context.requestFlush?.();
+        },
+    };
+    xhrInstrumentation.setConfig(xhrConfig);
+    xhrInstrumentation.enable();
+};
+export const startNetworkCapture = (context, options = {}) => {
+    if (activeCapture) {
+        return {
+            stop: () => undefined,
+        };
+    }
+    const capture = {
+        context,
+        tracerProvider: options.tracerProvider,
+        deniedKeys: options.deniedKeys ?? [],
+        ignoreUrlPrefixes: options.ignoreUrlPrefixes ?? [],
+        tracePropagationOrigins: new Set((options.tracePropagationOrigins ?? [])
+            .map(normalizeTracePropagationOrigin)
+            .filter((origin) => Boolean(origin))),
+        createRequestTraceContext: options.createRequestTraceContext ??
+            (() => ({
+                traceId: generateTraceId(),
+                parentSpanId: null,
+                requestId: generateRequestId(),
+                requestSpanId: generateRequestSpanId(),
+                interactionId: generateInteractionId(),
+                interactionInitiator: null,
+                interactionStartEventKind: null,
+            })),
+    };
+    activeCapture = capture;
+    ensureCluebaseNetworkPropagator();
+    if (typeof globalThis.fetch === "function") {
+        configureFetchInstrumentation(capture);
+    }
+    if (typeof globalThis.XMLHttpRequest !== "undefined") {
+        configureXhrInstrumentation(capture);
+    }
+    return {
+        flush: async () => {
+            await waitForFetchSpanEnd();
+        },
+        stop: () => {
+            if (activeCapture !== capture)
+                return;
+            failOpenRequestLifecycles("capture_stopped");
+            activeCapture = null;
+            fetchInstrumentation?.teardown();
+            xhrInstrumentation?.disable();
+            fetchInstrumentation = null;
+            xhrInstrumentation = null;
+        },
+    };
+};

package/dist/instrumentation/page.d.ts

@@ -0,0 +1,2 @@
+import type { CaptureModuleContext, CaptureStopHandle } from "../provider/types.js";
+export declare const startPageCapture: (context: CaptureModuleContext) => CaptureStopHandle;

package/dist/instrumentation/page.js

@@ -0,0 +1,56 @@
+import { getCurrentPageSnapshot } from "./location.js";
+export const startPageCapture = (context) => {
+    if (typeof window === "undefined" || typeof document === "undefined") {
+        return { stop: () => undefined };
+    }
+    let pageEnteredAtMs = Date.now();
+    // Page-view events are emitted from OTel navigation/document-load signals.
+    // This module only keeps Cluebase-specific time-on-page evidence.
+    const handlePageLeave = () => {
+        if (context.getConsent() === "denied") {
+            return;
+        }
+        const snapshot = getCurrentPageSnapshot();
+        context.onEvent({
+            type: "page_leave",
+            occurredAtMs: Date.now(),
+            payload: {
+                viewId: context.getViewId(),
+                screenKey: snapshot.screenKey,
+                path: snapshot.path,
+                urlCanonical: snapshot.urlCanonical,
+                timeOnPageMs: Math.max(0, Date.now() - pageEnteredAtMs),
+            },
+        });
+        pageEnteredAtMs = Date.now();
+    };
+    const visibilityHandler = () => {
+        if (document.visibilityState !== "hidden") {
+            return;
+        }
+        try {
+            handlePageLeave();
+        }
+        catch (error) {
+            context.onInternalError("capture/page:visibilitychange", error);
+        }
+    };
+    const pageHideHandler = () => {
+        try {
+            handlePageLeave();
+        }
+        catch (error) {
+            context.onInternalError("capture/page:pagehide", error);
+        }
+    };
+    document.addEventListener("visibilitychange", visibilityHandler, true);
+    window.addEventListener("pagehide", pageHideHandler, true);
+    window.addEventListener("beforeunload", pageHideHandler, true);
+    return {
+        stop: () => {
+            document.removeEventListener("visibilitychange", visibilityHandler, true);
+            window.removeEventListener("pagehide", pageHideHandler, true);
+            window.removeEventListener("beforeunload", pageHideHandler, true);
+        },
+    };
+};

package/dist/instrumentation/performance.d.ts

@@ -0,0 +1,2 @@
+import type { CaptureModuleContext, CaptureStopHandle } from "../provider/types.js";
+export declare const startPerformanceCapture: (context: CaptureModuleContext) => CaptureStopHandle;