@strada.sh/light 0.1.0 → 0.2.0

package/dist/index.js

@@ -1,28 +1,45 @@
 /**
- * `@strada.sh/light`: a zero-dependency, drop-in subset of `@strada.sh/sdk`.
+ * `@strada.sh/light`: a zero-dependency, explicit-only subset of `@strada.sh/sdk`.
  *
  * Switch by changing the import path. Same function names, same option
- * names, same `otel_logs` rows (`event.name`, `custom.*`, `exception.*`,
- * `strada.user.identify`), so every Strada query works unchanged. What the
- * light build does not support is not exported or not accepted, so a switch
- * that relies on it fails at compile time instead of silently dropping data.
- * `index.test.ts` type-checks this file against the full SDK to keep both in
- * sync.
+ * names, same rows in `otel_logs` / `otel_traces` (`event.name`, `custom.*`,
+ * `exception.*`, `strada.user.identify`, `pageview`), so every Strada query
+ * works unchanged. What the light build does not support is not exported or
+ * not accepted, so a switch that relies on it fails at compile time instead
+ * of silently dropping data. `index.test.ts` type-checks every export against
+ * the full SDK to keep both in sync.
  *
- * It builds OTLP JSON log records by hand and POSTs them with `fetch` to
- * `/v1/logs`. `initStrada()` installs nothing global: no OTel providers, no
- * process handlers, no resource detectors (no hostname, OS username, or
- * command args). Only what you pass is sent. The flush timer is unref'd, so
- * call `flush()` before a short-lived process exits.
+ * Explicit only: nothing is captured unless you call it. `initStrada()`
+ * installs nothing global: no OTel providers, no process or window error
+ * handlers, no fetch patching, no resource detectors (no hostname, OS
+ * username, or command args). Records are built as OTLP JSON by hand and
+ * POSTed with `fetch` to `/v1/logs` and `/v1/traces`. The flush timer is
+ * unref'd, so call `flush()` before a short-lived process exits.
+ *
+ * Span parenting across `await` uses AsyncLocalStorage when the runtime
+ * exposes `process.getBuiltinModule` (Node 20.16+, Bun, Workers with
+ * nodejs_compat). Elsewhere (browsers) only synchronous nesting works, the
+ * same limitation as the full browser SDK.
  *
  * Every function follows "telemetry never throws": failures are returned as
- * values and logged once with console.warn.
+ * values and logged once with console.warn. `startSpan()` rethrows the
+ * callback's own error, like the full SDK.
  */
 import { ATTR } from "./attrs.js";
+/** Same values as OTel SpanStatusCode. */
+export const SpanStatusCode = { UNSET: 0, OK: 1, ERROR: 2 };
 // OTel SeverityNumber values, inlined to avoid importing @opentelemetry/api-logs.
-const INFO_SEVERITY = 9;
-const ERROR_SEVERITY = 17;
+const SEVERITY = {
+    trace: [1, "TRACE"],
+    debug: [5, "DEBUG"],
+    info: [9, "INFO"],
+    warn: [13, "WARN"],
+    error: [17, "ERROR"],
+    fatal: [21, "FATAL"],
+};
+const SPAN_KIND_INTERNAL = 1;
 const MAX_QUEUE_SIZE = 2048;
+const MAX_LOG_STRING_LENGTH = 16_384;
 let state;
 let tags = {};
 const warned = new Set();
@@ -44,6 +61,46 @@ function isDevMode() {
         return false;
     }
 }
+// ---------------------------------------------------------------------------
+// Active span context
+// ---------------------------------------------------------------------------
+const asyncStorage = (() => {
+    try {
+        const hooks = globalThis.process?.getBuiltinModule?.("node:async_hooks");
+        return hooks ? new hooks.AsyncLocalStorage() : undefined;
+    }
+    catch {
+        return undefined;
+    }
+})();
+let syncActiveSpan;
+function getActiveSpan() {
+    return asyncStorage ? asyncStorage.getStore() : syncActiveSpan;
+}
+function runWithActiveSpan(active, fn) {
+    if (asyncStorage)
+        return asyncStorage.run(active, fn);
+    const previous = syncActiveSpan;
+    syncActiveSpan = active;
+    try {
+        return fn();
+    }
+    finally {
+        syncActiveSpan = previous;
+    }
+}
+// ---------------------------------------------------------------------------
+// Encoding helpers
+// ---------------------------------------------------------------------------
+function randomHex(bytes) {
+    const values = crypto.getRandomValues(new Uint8Array(bytes));
+    return Array.from(values, (value) => {
+        return value.toString(16).padStart(2, "0");
+    }).join("");
+}
+function nowUnixNano() {
+    return `${BigInt(Date.now()) * 1000000n}`;
+}
 function toAnyValue(value) {
     if (typeof value === "string")
         return { stringValue: value };
@@ -60,6 +117,60 @@ function toKeyValues(record) {
         return [{ key, value: toAnyValue(value) }];
     });
 }
+function truncate(value) {
+    if (value.length <= MAX_LOG_STRING_LENGTH)
+        return value;
+    return `${value.slice(0, MAX_LOG_STRING_LENGTH)}… [truncated ${value.length - MAX_LOG_STRING_LENGTH} chars]`;
+}
+function formatLogValue(value) {
+    if (typeof value === "string")
+        return truncate(value);
+    if (value instanceof Error)
+        return truncate(value.stack || value.message);
+    if (value === undefined)
+        return "undefined";
+    if (typeof value === "bigint" || typeof value === "symbol" || typeof value === "function")
+        return String(value);
+    try {
+        const seen = new WeakSet();
+        const json = JSON.stringify(value, (_key, nested) => {
+            if (typeof nested === "bigint")
+                return nested.toString();
+            if (typeof nested === "object" && nested !== null) {
+                if (seen.has(nested))
+                    return "[Circular]";
+                seen.add(nested);
+            }
+            return nested;
+        });
+        return truncate(json ?? String(value));
+    }
+    catch {
+        return truncate(String(value));
+    }
+}
+function isPlainObject(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/** One plain object = structured log (fields become attributes). Anything else = console-style body. */
+function normalizeLogInput(args) {
+    const [first] = args;
+    if (args.length === 1 && isPlainObject(first)) {
+        const attributes = Object.fromEntries(Object.entries(first).flatMap(([key, value]) => {
+            if (value == null)
+                return [];
+            if (typeof value === "number" || typeof value === "boolean")
+                return [[key, value]];
+            return [[key, formatLogValue(value)]];
+        }));
+        const message = attributes.message;
+        return { body: typeof message === "string" ? message : formatLogValue(first), attributes };
+    }
+    return { body: args.map(formatLogValue).join(" "), attributes: {} };
+}
 function normalizeError(value) {
     if (value instanceof Error)
         return value;
@@ -73,67 +184,122 @@ function normalizeError(value) {
         return new Error("Unknown error");
     }
 }
-async function send(current, records) {
+function matchesAny(value, patterns) {
+    return (patterns ?? []).some((pattern) => {
+        return typeof pattern === "string" ? value.includes(pattern) : pattern.test(value);
+    });
+}
+function currentUserId() {
+    const userId = state?.options.userId;
+    return typeof userId === "function" ? userId() : userId;
+}
+// ---------------------------------------------------------------------------
+// Queue and export
+// ---------------------------------------------------------------------------
+async function post({ current, path, body }) {
     try {
-        const response = await fetch(`${current.endpoint}/v1/logs`, {
+        const response = await fetch(`${current.endpoint}${path}`, {
             method: "POST",
             headers: {
                 "content-type": "application/json",
                 ...(current.options.token ? { authorization: `Bearer ${current.options.token}` } : {}),
             },
-            body: JSON.stringify({
-                resourceLogs: [
-                    {
-                        resource: { attributes: current.resource },
-                        scopeLogs: [{ scope: { name: "strada" }, logRecords: records }],
-                    },
-                ],
-            }),
+            body: JSON.stringify(body),
         });
         if (!response.ok)
-            return failure(`Strada ingest responded ${response.status}`);
+            return failure(`Strada ingest ${path} responded ${response.status}`);
         return undefined;
     }
     catch (cause) {
-        return failure("Strada ingest request failed", cause);
+        return failure(`Strada ingest ${path} request failed`, cause);
     }
 }
-/** Queue one log record. Shared by track, identifyUser, and captureException. */
-function emit({ operation, name, body, severity, attributes, }) {
+async function send({ current, logs, spans, }) {
+    const scopeNames = [...new Set(logs.map((log) => log.scope))];
+    const scopeLogs = scopeNames.map((name) => {
+        return {
+            scope: { name },
+            logRecords: logs.filter((log) => log.scope === name).map((log) => log.record),
+        };
+    });
+    const results = await Promise.all([
+        logs.length > 0
+            ? post({ current, path: "/v1/logs", body: { resourceLogs: [{ resource: { attributes: current.resource }, scopeLogs }] } })
+            : undefined,
+        spans.length > 0
+            ? post({
+                current,
+                path: "/v1/traces",
+                body: {
+                    resourceSpans: [{ resource: { attributes: current.resource }, scopeSpans: [{ scope: { name: "strada" }, spans }] }],
+                },
+            })
+            : undefined,
+    ]);
+    return results.find((result) => {
+        return result instanceof Error;
+    });
+}
+/** Returns the live state only when exporting, so callers can skip building records. */
+function exportingState(operation) {
     if (!state) {
         warnOnce(`${operation} called before initStrada(). Nothing was sent.`);
         return undefined;
     }
-    const current = state;
-    if (!current.exporting)
-        return undefined;
-    if (current.queue.length >= MAX_QUEUE_SIZE)
-        return failure("Queue full, dropping telemetry");
-    const userId = typeof current.options.userId === "function" ? current.options.userId() : current.options.userId;
-    const time = `${BigInt(Date.now()) * 1000000n}`;
-    current.queue.push({
-        timeUnixNano: time,
-        observedTimeUnixNano: time,
-        severityNumber: severity,
-        severityText: severity === ERROR_SEVERITY ? "ERROR" : "INFO",
-        body: { stringValue: body },
-        eventName: name,
-        attributes: toKeyValues({ [ATTR["user.id"]]: userId, ...attributes }),
-    });
+    return state.exporting ? state : undefined;
+}
+function scheduleFlush(current) {
     if (!current.timer) {
+        const delay = Math.min(current.options.telemetry?.logs?.scheduledDelayMillis ?? 5000, current.options.telemetry?.traces?.scheduledDelayMillis ?? 5000);
         current.timer = setInterval(() => {
             void flush();
-        }, current.options.telemetry?.logs?.scheduledDelayMillis ?? 5000);
+        }, delay);
         // Never keep a CLI or daemon alive just to send telemetry.
         if (typeof current.timer === "object" && typeof current.timer.unref === "function") {
             current.timer.unref();
         }
     }
-    if (current.queue.length >= (current.options.telemetry?.logs?.maxExportBatchSize ?? 512)) {
+    const logsFull = current.logs.length >= (current.options.telemetry?.logs?.maxExportBatchSize ?? 512);
+    const spansFull = current.spans.length >= (current.options.telemetry?.traces?.maxExportBatchSize ?? 512);
+    if (logsFull || spansFull)
         void flush();
-    }
+}
+function emitLog({ operation, scope = "strada", body, severity, eventName, attributes, }) {
+    const current = exportingState(operation);
+    if (!current)
+        return undefined;
+    if (current.logs.length >= MAX_QUEUE_SIZE)
+        return failure("Log queue full, dropping telemetry");
+    const [severityNumber, severityText] = SEVERITY[severity];
+    const active = getActiveSpan();
+    const time = nowUnixNano();
+    current.logs.push({ scope, record: {
+            timeUnixNano: time,
+            observedTimeUnixNano: time,
+            severityNumber,
+            severityText,
+            body: { stringValue: body },
+            ...(eventName ? { eventName } : {}),
+            ...(active ? { traceId: active.traceId, spanId: active.spanId } : {}),
+            attributes: toKeyValues({ [ATTR["user.id"]]: currentUserId(), ...attributes }),
+        } });
+    scheduleFlush(current);
     return undefined;
 }
+function emitSpan(span) {
+    const current = exportingState("span.end()");
+    if (!current)
+        return;
+    if (current.spans.length >= MAX_QUEUE_SIZE) {
+        warnOnce("Span queue full, dropping telemetry");
+        return;
+    }
+    current.spans.push(span);
+    scheduleFlush(current);
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
 export function initStrada(options) {
     try {
         if (state) {
@@ -160,7 +326,8 @@ export function initStrada(options) {
                 [ATTR["vcs.ref.head.name"]]: options.releaseBranch,
                 [ATTR["deployment.id"]]: options.deploymentId ?? options.releaseCommit,
             }),
-            queue: [],
+            logs: [],
+            spans: [],
             inflight: Promise.resolve(undefined),
             timer: undefined,
         };
@@ -176,11 +343,11 @@ export function track(name, properties) {
         const custom = Object.fromEntries(Object.entries(properties ?? {}).map(([key, value]) => {
             return [`custom.${key}`, value];
         }));
-        return emit({
+        return emitLog({
             operation: "track()",
-            name,
             body: name,
-            severity: INFO_SEVERITY,
+            severity: "info",
+            eventName: name,
             attributes: { [ATTR["event.name"]]: name, ...custom },
         });
     }
@@ -192,11 +359,11 @@ export function track(name, properties) {
 export function identifyUser(user) {
     try {
         const name = ATTR["strada.user.identify"];
-        return emit({
+        return emitLog({
             operation: "identifyUser()",
-            name,
             body: name,
-            severity: INFO_SEVERITY,
+            severity: "info",
+            eventName: name,
             attributes: {
                 [ATTR["event.name"]]: name,
                 [ATTR["user.id"]]: user.id,
@@ -221,27 +388,41 @@ export function identifyUser(user) {
 export function setTags(next) {
     tags = { ...tags, ...next };
 }
-/**
- * Report a handled error as an issue. No ignoreErrors, denyUrls, or
- * beforeSend in the light build; KnownError instances are skipped like in
- * the full SDK.
- */
+/** Report an error as an issue. Applies KnownError, ignoreErrors, denyUrls, and beforeSend. */
 export function captureException(error, opts) {
     try {
         const normalized = normalizeError(error);
+        const options = state?.options;
         if (normalized.name === "KnownError" || normalized.constructor?.name === "KnownError")
             return undefined;
-        const fingerprintValue = Reflect.get(normalized, "fingerprint");
+        if (matchesAny(normalized.message || "", options?.ignoreErrors))
+            return undefined;
+        if (matchesAny(normalized.stack || "", options?.denyUrls))
+            return undefined;
+        const prepared = (() => {
+            if (!options?.beforeSend)
+                return normalized;
+            try {
+                return options.beforeSend(normalized);
+            }
+            catch (thrown) {
+                warnOnce(`beforeSend threw, sending the original error instead: ${normalizeError(thrown).message}`);
+                return normalized;
+            }
+        })();
+        if (!prepared)
+            return undefined;
+        const fingerprintValue = Reflect.get(prepared, "fingerprint");
         const fingerprint = opts?.fingerprint ?? (Array.isArray(fingerprintValue) ? fingerprintValue : undefined);
-        return emit({
+        return emitLog({
             operation: "captureException()",
-            name: "exception",
-            body: normalized.message,
-            severity: ERROR_SEVERITY,
+            body: prepared.message,
+            severity: "error",
+            eventName: "exception",
             attributes: {
-                [ATTR["exception.type"]]: normalized.name || "Error",
-                [ATTR["exception.message"]]: normalized.message || "",
-                [ATTR["exception.stacktrace"]]: normalized.stack ?? "",
+                [ATTR["exception.type"]]: prepared.name || "Error",
+                [ATTR["exception.message"]]: prepared.message || "",
+                [ATTR["exception.stacktrace"]]: prepared.stack ?? "",
                 [ATTR["exception.mechanism.type"]]: opts?.mechanism ?? "generic",
                 [ATTR["exception.mechanism.handled"]]: String(opts?.handled ?? true),
                 [ATTR["exception.fingerprint"]]: fingerprint ? JSON.stringify(fingerprint) : undefined,
@@ -254,17 +435,183 @@ export function captureException(error, opts) {
         return failure("captureException() failed", cause);
     }
 }
+/** Console-style logger that sends to `otel_logs`. Not exception capture: use captureException() for issues. */
+export function getLogger(name = "strada") {
+    const method = (severity) => {
+        return (...args) => {
+            try {
+                const { body, attributes } = normalizeLogInput(args);
+                void emitLog({ operation: `logger.${severity}()`, scope: name, body, severity, attributes });
+            }
+            catch (cause) {
+                void failure(`logger.${severity}() failed`, cause);
+            }
+        };
+    };
+    return {
+        trace: method("trace"),
+        debug: method("debug"),
+        info: method("info"),
+        warn: method("warn"),
+        error: method("error"),
+        fatal: method("fatal"),
+    };
+}
+function createSpan(options) {
+    const parent = getActiveSpan();
+    const traceId = parent?.traceId ?? randomHex(16);
+    const spanId = randomHex(8);
+    const startTimeUnixNano = nowUnixNano();
+    let name = options.name;
+    let ended = false;
+    let status = { code: SpanStatusCode.UNSET };
+    const attributes = {
+        [ATTR["user.id"]]: currentUserId(),
+        ...options.attributes,
+    };
+    const events = [];
+    const span = {
+        spanContext() {
+            return { traceId, spanId, traceFlags: 1 };
+        },
+        setAttribute(key, value) {
+            attributes[key] = value;
+            return span;
+        },
+        setAttributes(next) {
+            Object.assign(attributes, next);
+            return span;
+        },
+        addEvent(eventName, eventAttributes) {
+            events.push({ timeUnixNano: nowUnixNano(), name: eventName, attributes: toKeyValues(eventAttributes ?? {}) });
+            return span;
+        },
+        setStatus(next) {
+            status = next;
+            return span;
+        },
+        updateName(next) {
+            name = next;
+            return span;
+        },
+        recordException(exception) {
+            const error = normalizeError(exception);
+            span.addEvent("exception", {
+                [ATTR["exception.type"]]: error.name || "Error",
+                [ATTR["exception.message"]]: error.message || "",
+                [ATTR["exception.stacktrace"]]: error.stack ?? "",
+            });
+        },
+        isRecording() {
+            return !ended;
+        },
+        end() {
+            if (ended)
+                return;
+            ended = true;
+            emitSpan({
+                traceId,
+                spanId,
+                ...(parent ? { parentSpanId: parent.spanId } : {}),
+                name,
+                kind: SPAN_KIND_INTERNAL,
+                startTimeUnixNano,
+                endTimeUnixNano: nowUnixNano(),
+                attributes: toKeyValues(attributes),
+                events,
+                status,
+            });
+        },
+        [Symbol.dispose]() {
+            span.end();
+        },
+    };
+    return span;
+}
+/** Create a detached span. Call `span.end()` or use `using`. It does not parent later spans. */
+export function startInactiveSpan(options) {
+    return createSpan(options);
+}
+/**
+ * Run `callback` inside an active span that auto-ends. Spans, logs, events,
+ * and errors created inside are parented to it. A thrown error is recorded on
+ * the span and rethrown.
+ */
+export function startSpan(options, callback) {
+    const span = createSpan(options);
+    const onError = (error) => {
+        span.recordException(normalizeError(error));
+        span.setStatus({ code: SpanStatusCode.ERROR });
+        span.end();
+    };
+    const result = (() => {
+        try {
+            return runWithActiveSpan(span.spanContext(), () => {
+                return callback(span);
+            });
+        }
+        catch (error) {
+            onError(error);
+            throw error;
+        }
+    })();
+    if (result instanceof Promise) {
+        return result.then((value) => {
+            span.end();
+            return value;
+        }, (error) => {
+            onError(error);
+            throw error;
+        });
+    }
+    span.end();
+    return result;
+}
+/** Server-side pageview span. Feeds the same analytics views as browser pageviews. */
+export function trackPageview(opts) {
+    try {
+        const url = (() => {
+            try {
+                return opts.url ? new URL(opts.url) : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        })();
+        const span = createSpan({
+            name: "pageview",
+            attributes: {
+                ...opts.attributes,
+                [ATTR["url.path"]]: opts.path || url?.pathname || "/",
+                [ATTR["pageview.source"]]: "server",
+                // Analytics views require a non-empty session.id.
+                [ATTR["session.id"]]: opts.sessionId ?? `server:${crypto.randomUUID()}`,
+                ...(url ? { [ATTR["url.full"]]: url.href } : {}),
+                ...(opts.query || url?.search ? { [ATTR["url.query"]]: opts.query || url?.search || "" } : {}),
+                ...(opts.referrer ? { [ATTR["http.request.header.referer"]]: opts.referrer } : {}),
+                ...(opts.userId ? { [ATTR["user.id"]]: opts.userId } : {}),
+            },
+        });
+        span.end();
+        return undefined;
+    }
+    catch (cause) {
+        return failure("trackPageview() failed", cause);
+    }
+}
 export function flush() {
     const current = state;
     if (!current)
         return Promise.resolve(undefined);
-    if (current.queue.length === 0)
+    if (current.logs.length === 0 && current.spans.length === 0)
         return current.inflight;
-    const records = current.queue;
-    current.queue = [];
+    const logs = current.logs;
+    const spans = current.spans;
+    current.logs = [];
+    current.spans = [];
     // Chain sends so flush() resolves only after every earlier batch is done.
     current.inflight = current.inflight.then(() => {
-        return send(current, records);
+        return send({ current, logs, spans });
     });
     return current.inflight;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strada.sh/light",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Zero-dependency Strada SDK subset for product events, user profiles, and handled errors. Drop-in for @strada.sh/sdk: same names, same options, no OpenTelemetry.",
   "keywords": [
     "strada",

package/src/attrs.ts

@@ -22,4 +22,10 @@ export const ATTR = {
   "exception.mechanism.type": "exception.mechanism.type",
   "exception.mechanism.handled": "exception.mechanism.handled",
   "exception.fingerprint": "exception.fingerprint",
+  "session.id": "session.id",
+  "url.path": "url.path",
+  "url.query": "url.query",
+  "url.full": "url.full",
+  "http.request.header.referer": "http.request.header.referer",
+  "pageview.source": "pageview.source",
 } as const;