@heystack/otel 0.4.2 → 0.5.0

package/dist/workers.js

@@ -8,12 +8,14 @@
 // ships its own OTLP/JSON-over-fetch span exporter so it runs on Workers/Edge
 // where the Node SDK cannot.
 import { context, trace, SpanKind, SpanStatusCode, } from "@opentelemetry/api";
-import { suppressTracing } from "@opentelemetry/core";
+import { suppressTracing, isTracingSuppressed } from "@opentelemetry/core";
 import { ROOT_CONTEXT } from "@opentelemetry/api";
 import { Resource } from "@opentelemetry/resources";
 import { BasicTracerProvider, SimpleSpanProcessor, } from "@opentelemetry/sdk-trace-base";
 import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
 import { buildExporterConfig } from "./core.js";
+import { isSelfSpanAttrs, safeHostname } from "./self-span.js";
+import { instrumentEnv } from "./workers-bindings.js";
 // `ExportResult` / `ExportResultCode` mirror `@opentelemetry/core`. We define
 // them inline (structurally identical) rather than import them: core is only a
 // transitive dep of sdk-trace-base and isn't reliably resolvable, and keeping it
@@ -115,6 +117,11 @@ function readableSpanToOtlp(span) {
         startTimeUnixNano: hrTimeToUnixNano(span.startTime),
         endTimeUnixNano: hrTimeToUnixNano(span.endTime),
         attributes: toKeyValues(span.attributes),
+        events: span.events.map((ev) => ({
+            timeUnixNano: hrTimeToUnixNano(ev.time),
+            name: ev.name,
+            attributes: toKeyValues((ev.attributes ?? {})),
+        })),
         status: toStatus(span.status),
     };
 }
@@ -138,6 +145,36 @@ export function serializeSpans(spans) {
     };
 }
 // ---------------------------------------------------------------------------
+// W3C traceparent + CORS expose-header helpers (FR5 tap→server correlation)
+// ---------------------------------------------------------------------------
+const TRACEPARENT_RE = /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
+/** Parse a W3C `traceparent`. Returns null for malformed or all-zero ids. */
+export function parseTraceparent(header) {
+    if (!header)
+        return null;
+    const m = TRACEPARENT_RE.exec(header.trim());
+    if (!m)
+        return null;
+    const traceId = m[1];
+    const spanId = m[2];
+    const flags = m[3];
+    if (traceId === "0".repeat(32) || spanId === "0".repeat(16))
+        return null;
+    return { traceId, spanId, traceFlags: parseInt(flags, 16) };
+}
+/** Add `value` to Access-Control-Expose-Headers without duplicating it. */
+export function appendExposeHeader(headers, value) {
+    const existing = headers.get("access-control-expose-headers");
+    if (!existing) {
+        headers.set("access-control-expose-headers", value);
+        return;
+    }
+    const present = existing.split(",").map((s) => s.trim().toLowerCase());
+    if (!present.includes(value.toLowerCase())) {
+        headers.set("access-control-expose-headers", `${existing}, ${value}`);
+    }
+}
+// ---------------------------------------------------------------------------
 // Self-span filtering (feedback-loop guard)
 //
 // On Next/OpenNext the host auto-instruments outbound `fetch`, so the exporter's
@@ -147,87 +184,157 @@ export function serializeSpans(spans) {
 // targets the ingest origin, so an upstream instrumentation that ignores
 // suppression still can't feed the loop.
 // ---------------------------------------------------------------------------
+// `safeHostname` / `isSelfSpanAttrs` live in the shared, runtime-agnostic
+// `./self-span.js` module (also used by `/node`). They are pure string logic
+// with no runtime imports, so importing them keeps this entry WinterCG-safe.
+function isSelfSpan(span, ingestHost) {
+    return isSelfSpanAttrs(span.attributes, ingestHost);
+}
 /**
- * Parse the hostname (no port) out of a URL, lower-cased; empty string if it
- * can't be parsed. We compare on hostname rather than `host` so that an ingest
- * URL like `ingest.heystack.dev` matches a captured span attribute of
- * `ingest.heystack.dev:443` (and vice-versa).
+ * Test-only helper: run the self-span attribute check directly against a plain
+ * attribute bag + ingest hostname, without constructing a ReadableSpan. The
+ * `ingestHost` should be a bare hostname (lower-case, no port), matching what
+ * the exporter derives via `safeHostname(cfg.url)`.
  */
-function safeHostname(url) {
+export function isSelfSpanForTest(attrs, ingestHost) {
+    return isSelfSpanAttrs(attrs, ingestHost);
+}
+// ---------------------------------------------------------------------------
+// Outbound fetch auto-instrumentation (CLIENT child spans + traceparent)
+//
+// Patches globalThis.fetch ONCE (guarded), capturing the platform fetch the
+// instant before replacing it. Each outbound call made inside a traced request
+// (an active span is present, tracing is not suppressed, and the target is not
+// the ingest host) gets a CLIENT child span AND a W3C `traceparent` injected
+// into a CLONE of the request — so a downstream Heystack-instrumented service
+// continues the SAME trace (distributed tracing).
+//
+// Why patch-once + ALS rather than a per-request global swap: under workerd a
+// single isolate serves concurrent requests, so swapping globalThis.fetch per
+// request (install/restore in a finally) would race across overlapping requests.
+// Task 2's AsyncLocalStorage context manager makes `context.active()` reflect the
+// CURRENT request's active span across awaits, so ONE global wrapper can decide
+// per-call which request (if any) the subrequest belongs to.
+//
+// `_originalFetch` is the captured platform fetch. The exporter's own POST uses
+// it directly (see `export()`), so an export is never re-entered by this wrapper
+// (belt; the wrapper also bails on suppressed contexts + ingest-host targets —
+// suspenders). Reading `safeHostname` / the self-span host concept keeps the
+// self-span guardrail satisfied and the path WinterCG-safe (pure string logic).
+// ---------------------------------------------------------------------------
+let _fetchInstrumented = false;
+let _originalFetch;
+let _fetchWrapper;
+/** Resolve the absolute URL of an outbound fetch arg (string | URL | Request). */
+function outboundUrl(input) {
+    if (typeof input === "string")
+        return input;
+    if (input instanceof URL)
+        return input.href;
+    if (input instanceof Request)
+        return input.url;
     try {
-        return new URL(url).hostname.toLowerCase();
+        return String(input.url ?? input);
     }
     catch {
         return "";
     }
 }
+/** Resolve the HTTP method of an outbound fetch arg. */
+function outboundMethod(input, init) {
+    if (init?.method)
+        return init.method;
+    if (input instanceof Request)
+        return input.method;
+    return "GET";
+}
 /**
- * Strip a trailing `:port` from a bare host attribute and lower-case it, so a
- * host-only attr like `ingest.heystack.dev:443` compares equal to the ingest
- * hostname. IPv6 literals (`[::1]:443`) keep their bracketed form. Returns ""
- * for anything that isn't a non-empty string.
- */
-function hostnameOf(hostAttr) {
-    if (typeof hostAttr !== "string" || hostAttr === "")
-        return "";
-    const v = hostAttr.trim();
-    // Bracketed IPv6, optionally with a port: `[::1]` or `[::1]:443`.
-    if (v.startsWith("[")) {
-        const close = v.indexOf("]");
-        if (close !== -1)
-            return v.slice(0, close + 1).toLowerCase();
-        return v.toLowerCase();
-    }
-    // Strip a single trailing :port (host:port). A bare hostname has no colon.
-    const colon = v.lastIndexOf(":");
-    if (colon !== -1 && v.indexOf(":") === colon) {
-        return v.slice(0, colon).toLowerCase();
-    }
-    return v.toLowerCase();
-}
-/** Attributes that carry a full HTTP URL on a CLIENT/SERVER span. */
-const HTTP_URL_ATTRS = ["url.full", "http.url"];
-/** Host-only attributes (host[:port], no scheme/path). */
-const HTTP_HOST_ATTRS = [
-    "server.address",
-    "net.peer.name",
-    "net.peer.hostname",
-    "http.host",
-    "peer.address",
-];
-/**
- * True if `span` looks like a request to the configured ingest origin — i.e. it
- * is (or could be) the exporter's own self-trace. For full-URL attributes we
- * parse the URL and compare its `.hostname` (case-insensitive, port stripped) so
- * a sibling domain like `myingest.heystack.dev` is NOT a false positive and an
- * explicit port like `ingest.heystack.dev:443` IS matched. For host-only attrs
- * we strip any `:port` and compare hostname equality.
+ * Return an [input, init] pair with `traceparent` injected, WITHOUT mutating the
+ * caller's Request/Headers. For a Request input we build a fresh Request copying
+ * it; for string/URL we clone the init headers.
  */
-function isSelfSpanAttrs(attrs, ingestHost) {
-    if (!ingestHost)
-        return false;
-    for (const key of HTTP_URL_ATTRS) {
-        const v = attrs[key];
-        if (typeof v === "string" && safeHostname(v) === ingestHost)
-            return true;
-    }
-    for (const key of HTTP_HOST_ATTRS) {
-        if (hostnameOf(attrs[key]) === ingestHost)
-            return true;
+function injectTraceparent(input, init, traceparent) {
+    if (input instanceof Request) {
+        const headers = new Headers(init?.headers ?? input.headers);
+        headers.set("traceparent", traceparent);
+        return [new Request(input, { ...(init ?? {}), headers }), undefined];
     }
-    return false;
+    const headers = new Headers(init?.headers);
+    headers.set("traceparent", traceparent);
+    return [input, { ...(init ?? {}), headers }];
 }
-function isSelfSpan(span, ingestHost) {
-    return isSelfSpanAttrs(span.attributes, ingestHost);
+/**
+ * Patch `globalThis.fetch` exactly once to emit a CLIENT child span + inject
+ * `traceparent` for outbound subrequests. `ingestHost` is the bare ingest
+ * hostname (lower-case, no port) so the exporter's own uploads are never traced.
+ */
+function ensureFetchInstrumentation(ingestHost) {
+    if (_fetchInstrumented)
+        return;
+    _fetchInstrumented = true;
+    // Capture the platform fetch the instant before replacing it (cost guardrail:
+    // "capture original before patching"). The exporter reuses this captured
+    // reference, so its POST is never routed back through the wrapper.
+    const originalFetch = globalThis.fetch.bind(globalThis);
+    _originalFetch = originalFetch;
+    const wrapper = async (input, init) => {
+        const active = context.active();
+        // Passthrough UNCHANGED when there is nothing to parent to (no active span,
+        // e.g. a fetch outside a traced request) or tracing is suppressed (the
+        // exporter's own POST, or anything under suppressTracing).
+        if (isTracingSuppressed(active) || !trace.getSpan(active)) {
+            return originalFetch(input, init);
+        }
+        const target = outboundUrl(input);
+        const host = safeHostname(target);
+        // No parseable host, or the ingest host itself (self-span) → don't trace.
+        if (!host || host === ingestHost) {
+            return originalFetch(input, init);
+        }
+        const method = outboundMethod(input, init);
+        const span = trace.getTracer("heystack").startSpan(`${method} ${host}`, {
+            kind: SpanKind.CLIENT,
+            attributes: {
+                "http.request.method": method,
+                "url.full": target,
+                "server.address": host,
+            },
+        }, active);
+        const sc = span.spanContext();
+        const traceparent = `00-${sc.traceId}-${sc.spanId}-01`;
+        const [reqInput, reqInit] = injectTraceparent(input, init, traceparent);
+        try {
+            const response = await originalFetch(reqInput, reqInit);
+            span.setAttribute("http.response.status_code", response.status);
+            return response;
+        }
+        catch (error) {
+            span.recordException(error instanceof Error ? error : new Error(String(error)));
+            span.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+        finally {
+            span.end();
+        }
+    };
+    _fetchWrapper = wrapper;
+    globalThis.fetch = _fetchWrapper;
 }
 /**
- * Test-only helper: run the self-span attribute check directly against a plain
- * attribute bag + ingest hostname, without constructing a ReadableSpan. The
- * `ingestHost` should be a bare hostname (lower-case, no port), matching what
- * the exporter derives via `safeHostname(cfg.url)`.
+ * Reset the outbound-fetch instrumentation: restore the captured platform fetch
+ * (only when our wrapper is still the installed global) and clear the guard.
+ * Internal/testing helper.
  */
-export function isSelfSpanForTest(attrs, ingestHost) {
-    return isSelfSpanAttrs(attrs, ingestHost);
+export function __resetFetchInstrumentation() {
+    if (_fetchWrapper && globalThis.fetch === _fetchWrapper && _originalFetch) {
+        globalThis.fetch = _originalFetch;
+    }
+    _fetchInstrumented = false;
+    _originalFetch = undefined;
+    _fetchWrapper = undefined;
 }
 // ---------------------------------------------------------------------------
 // Exporter
@@ -297,9 +404,12 @@ export class HeystackSpanExporter {
         // The POST runs inside a tracing-suppressed context so that host fetch
         // auto-instrumentation (e.g. Next/OpenNext) does NOT create a CLIENT span
         // for it — which would otherwise be exported and re-captured, a sustained
-        // feedback loop.
+        // feedback loop. As a belt-and-suspenders second layer it also uses the
+        // CAPTURED platform fetch (when our outbound-fetch wrapper is installed), so
+        // the export can never be re-entered by that wrapper regardless of context.
+        const doFetch = _originalFetch ?? fetch;
         const p = context
-            .with(suppressTracing(context.active()), () => fetch(this.url, { method: "POST", headers: this.headers, body }))
+            .with(suppressTracing(context.active()), () => doFetch(this.url, { method: "POST", headers: this.headers, body }))
             .then((res) => {
             if (res.ok) {
                 resultCallback({ code: ExportResultCode.SUCCESS });
@@ -421,31 +531,51 @@ export function createTracerProvider(config) {
 // Global tracer provider registration (for host frameworks, e.g. Next.js)
 // ---------------------------------------------------------------------------
 let _provider = null;
-// ---------------------------------------------------------------------------
-// Context manager registration (makes suppressTracing() actually work)
-//
-// `context.with(...)` is a NO-OP unless a ContextManager is registered with the
-// global OTel API. Without one, `suppressTracing(context.active())` produces a
-// context that is never made active, so the exporter's POST is NOT suppressed
-// in production and host fetch auto-instrumentation can re-trace it (feedback
-// loop). We therefore register a manager exactly ONCE in `ensureGlobalProvider`.
-//
-// We register a dependency-free SYNCHRONOUS stack manager (below). Deliberately
-// NOT AsyncLocalStorageContextManager: that statically imports `node:async_hooks`,
-// which would break `import "@heystack/otel/workers"` on a bare workerd without
-// `nodejs_compat` (and on other WinterCG runtimes) — defeating the whole point of
-// this entry being node-builtin-free. The sync manager covers the critical path:
-// the exporter's POST runs synchronously inside the suppressed `context.with`, so
-// `suppressTracing` takes effect. Trade-off: no cross-`await` context propagation,
-// so deep nested-span parenting is limited on the edge (documented).
-// ---------------------------------------------------------------------------
+/** Read the ALS global lazily — at call time, not module load time. */
+function getALS() {
+    return globalThis.AsyncLocalStorage;
+}
 /**
- * A minimal SYNCHRONOUS, stack-based ContextManager — the registered manager for
- * the /workers entry (no `node:async_hooks`, so it works on any WinterCG runtime).
- * It makes `context.with()` propagate synchronously, which is enough for the
- * exporter's `suppressTracing` to take effect and for the belt-and-suspenders
- * self-span filter — but it does NOT carry context across `await` boundaries (so
- * cross-`await` parent linking and per-request isolation are best-effort).
+ * An AsyncLocalStorage-backed ContextManager for the /workers entry. When the
+ * runtime exposes `globalThis.AsyncLocalStorage` (workerd and Node do), this
+ * manager is preferred over `SyncStackContextManager` because it propagates
+ * context across `await` boundaries — child spans created after an `await`
+ * inside a handler are correctly parented to the request's root span.
+ *
+ * WinterCG-safe: it does NOT import `node:async_hooks`; instead it uses the
+ * ALS global that the runtime exposes. Falls back to `SyncStackContextManager`
+ * when the global is absent (Deno, Bun without globals, etc.).
+ */
+export class AlsContextManager {
+    _als;
+    constructor() {
+        const ALS = getALS();
+        if (!ALS)
+            throw new Error("AlsContextManager: globalThis.AsyncLocalStorage is not available in this runtime");
+        this._als = new ALS();
+    }
+    active() {
+        return this._als.getStore() ?? ROOT_CONTEXT;
+    }
+    with(ctx, fn, thisArg, ...args) {
+        return this._als.run(ctx, () => fn.call(thisArg, ...args));
+    }
+    bind(_ctx, target) {
+        return target;
+    }
+    enable() {
+        return this;
+    }
+    disable() {
+        return this;
+    }
+}
+/**
+ * A minimal SYNCHRONOUS, stack-based ContextManager — the fallback for the
+ * /workers entry when `globalThis.AsyncLocalStorage` is absent (any WinterCG
+ * runtime without the global). It makes `context.with()` propagate
+ * synchronously, which is enough for the exporter's `suppressTracing` to take
+ * effect — but it does NOT carry context across `await` boundaries.
  */
 export class SyncStackContextManager {
     _stack = [];
@@ -478,20 +608,19 @@ let _contextManagerRegistered = false;
  * `context.with(suppressTracing(...))` in the exporter is actually honoured —
  * otherwise suppression is a no-op and the exporter's POST can be re-traced.
  *
- * We register a synchronous, dependency-free stack manager. This keeps the
- * /workers entry WinterCG-safe (no `node:async_hooks` import → works on bare
- * workerd WITHOUT nodejs_compat, Deno, Bun, etc.). It fully covers the critical
- * path (the export fetch runs synchronously inside the suppressed `context.with`,
- * and per-request root spans). Trade-off: it does not propagate context across
- * `await` boundaries, so deep nested-span parenting is limited on the edge — an
- * acceptable, documented limitation (workerd has no async context manager by
- * default regardless).
+ * When `globalThis.AsyncLocalStorage` is available (workerd, Node), we register
+ * an `AlsContextManager` that propagates context across `await` boundaries —
+ * child spans created after an `await` are correctly parented to the root span.
+ * When absent we fall back to `SyncStackContextManager`, which covers the
+ * critical suppression path synchronously but does not carry context across
+ * `await` boundaries.
  */
 function ensureContextManager() {
     if (_contextManagerRegistered)
         return;
     _contextManagerRegistered = true;
-    context.setGlobalContextManager(new SyncStackContextManager().enable());
+    const mgr = getALS() ? new AlsContextManager() : new SyncStackContextManager();
+    context.setGlobalContextManager(mgr.enable());
 }
 /** Reset the context-manager registration guard. Internal/testing helper. */
 export function __resetContextManager() {
@@ -522,6 +651,10 @@ function ensureGlobalProvider(config) {
     // the exporter actually takes effect — without one, `context.with` is a no-op
     // and suppression silently does nothing in production.
     ensureContextManager();
+    // Patch globalThis.fetch (once) so outbound subrequests get CLIENT child spans
+    // + `traceparent` injection (distributed tracing). The exporter's own POST uses
+    // the captured original fetch, so it is never re-entered by this wrapper.
+    ensureFetchInstrumentation(_provider.heystackExporter.ingestHost);
     return _provider;
 }
 /**
@@ -628,6 +761,17 @@ export function instrument(handler, config) {
                 return originalFetch(req, env, ctx);
             const { provider, tracer } = s;
             const url = new URL(req.url);
+            // FR5: continue an inbound W3C traceparent so tap→server is one trace.
+            const parent = parseTraceparent(req.headers.get("traceparent"));
+            let startCtx = context.active();
+            if (parent) {
+                startCtx = trace.setSpanContext(startCtx, {
+                    traceId: parent.traceId,
+                    spanId: parent.spanId,
+                    traceFlags: parent.traceFlags,
+                    isRemote: true,
+                });
+            }
             const span = tracer.startSpan(`${req.method} ${url.pathname}`, {
                 kind: SpanKind.SERVER,
                 attributes: {
@@ -636,16 +780,92 @@ export function instrument(handler, config) {
                     "url.path": url.pathname,
                     "server.address": url.host,
                 },
-            });
+            }, startCtx);
+            // A1 enrichment: identity, request id, client ip, geo.
+            // All attributes are set only when non-empty to keep spans lean.
+            const userInfo = config.getUser?.(req);
+            if (userInfo?.id)
+                span.setAttribute("enduser.id", userInfo.id);
+            if (userInfo?.session)
+                span.setAttribute("session.id", userInfo.session);
+            const reqId = userInfo?.requestId ?? req.headers.get("cf-ray") ?? "";
+            if (reqId)
+                span.setAttribute("http.request.id", reqId);
+            const clientIp = req.headers.get("CF-Connecting-IP") ?? "";
+            if (clientIp)
+                span.setAttribute("client.address", clientIp);
+            // Cloudflare geo — only present on the real CF runtime; read defensively.
+            const cf = req.cf;
+            if (cf) {
+                if (typeof cf.country === "string" && cf.country)
+                    span.setAttribute("geo.country", cf.country);
+                if (typeof cf.region === "string" && cf.region)
+                    span.setAttribute("geo.region", cf.region);
+                if (typeof cf.city === "string" && cf.city)
+                    span.setAttribute("geo.city", cf.city);
+                if (cf.asn != null)
+                    span.setAttribute("geo.asn", String(cf.asn));
+            }
+            // FR5: response header carrying THIS span's trace + span id.
+            const sc = span.spanContext();
+            const traceparent = `00-${sc.traceId}-${sc.spanId}-01`;
+            // Instrument bindings when requested — wrap env BEFORE handing to the
+            // handler so binding calls made inside `originalFetch` (which runs inside
+            // `context.with` below) correctly parent to the root span via ALS.
+            let handlerEnv = env;
+            if (config.instrumentBindings) {
+                const binTracer = trace.getTracer("heystack");
+                handlerEnv = instrumentEnv(env, {
+                    startSpan: (name, attrs) => binTracer.startSpan(name, { attributes: attrs }, context.active()),
+                    select: config.instrumentBindings,
+                });
+            }
             try {
-                const response = await context.with(trace.setSpan(context.active(), span), () => originalFetch(req, env, ctx));
+                const response = await context.with(trace.setSpan(startCtx, span), () => originalFetch(req, handlerEnv, ctx));
+                const headers = new Headers(response.headers);
+                headers.set("traceparent", traceparent);
+                appendExposeHeader(headers, "traceparent");
                 span.setAttribute("http.response.status_code", response.status);
-                span.setStatus({
-                    code: response.status >= 500 ? SpanStatusCode.ERROR : SpanStatusCode.UNSET,
+                const finalize = () => {
+                    span.setStatus({
+                        code: response.status >= 500 ? SpanStatusCode.ERROR : SpanStatusCode.UNSET,
+                    });
+                    span.end();
+                    drain(provider, ctx);
+                };
+                // No body to stream → finalize now (redirects, 204/304, etc.).
+                if (!response.body) {
+                    finalize();
+                    return new Response(null, {
+                        status: response.status,
+                        statusText: response.statusText,
+                        headers,
+                    });
+                }
+                // FR1: keep the span open until the streamed body drains; the first
+                // chunk records time-to-first-byte. `finished` guards double-finalize.
+                let firstByte = false;
+                let finished = false;
+                const monitor = new TransformStream({
+                    transform(chunk, controller) {
+                        if (!firstByte) {
+                            firstByte = true;
+                            span.addEvent("first_byte");
+                        }
+                        controller.enqueue(chunk);
+                    },
+                    flush() {
+                        if (finished)
+                            return;
+                        finished = true;
+                        finalize();
+                    },
+                });
+                return new Response(response.body.pipeThrough(monitor), {
+                    status: response.status,
+                    statusText: response.statusText,
+                    headers,
                 });
-                span.end();
-                drain(provider, ctx);
-                return response;
             }
             catch (error) {
                 span.recordException(error instanceof Error ? error : new Error(String(error)));
@@ -724,3 +944,29 @@ export function instrument(handler, config) {
     }
     return wrapped;
 }
+export async function withSpan(name, attrsOrFn, maybeFn) {
+    const attrs = typeof attrsOrFn === "function" ? undefined : attrsOrFn;
+    const fn = (typeof attrsOrFn === "function" ? attrsOrFn : maybeFn);
+    const tracer = trace.getTracer("heystack");
+    const span = tracer.startSpan(name, attrs ? { attributes: attrs } : undefined);
+    const ctx = trace.setSpan(context.active(), span);
+    try {
+        return await context.with(ctx, () => fn(span));
+    }
+    catch (err) {
+        span.recordException(err);
+        span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+        throw err;
+    }
+    finally {
+        span.end();
+    }
+}
+/**
+ * Add a named event (with optional attributes) to the currently-active span.
+ * No-op when no span is active.
+ */
+export function addEvent(name, attrs) {
+    const span = trace.getSpan(context.active());
+    span?.addEvent(name, attrs);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heystack/otel",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Runtime-aware OpenTelemetry tracing that exports to Heystack (Node, Next.js, Workers).",
   "license": "MIT",
   "type": "module",