@heystack/otel 0.4.3 → 0.5.0

package/README.md

@@ -85,32 +85,102 @@ export default instrument(
       return new Response("ok");
     },
   },
-  { service: "my-worker" }, // apiKey defaults to env.HEYSTACK_API_KEY
+  {
+    service: "my-worker",      // apiKey defaults to env.HEYSTACK_API_KEY
+    getUser: (req) => ({
+      id: req.headers.get("x-user-id") ?? undefined,
+    }),
+    instrumentBindings: true,  // auto-trace D1/KV/R2/Vectorize
+  },
 );
 ```
 
-As of **0.3.0** `instrument()` registers the **global** tracer provider and creates the per-request SERVER span via the global tracer, so nested spans created through the global `trace.getTracer()` API (framework/library/manual) also export — you get a trace tree, not a lone SERVER span.
+`instrument()` must be the **outermost** wrapper if other middleware also wraps the handler, so the request span covers everything inside:
+
+```ts
+export default instrument(withOtherMiddleware(worker), { service: "my-worker" });
+```
+
+Set the key as a secret: `wrangler secret put HEYSTACK_API_KEY`.
 
-> **Requires `nodejs_compat` on workerd.** As of **0.3.2** the SDK registers an OpenTelemetry **ContextManager** at init (see below), backed by `AsyncLocalStorage` from `node:async_hooks`. On Cloudflare Workers that means your `wrangler.toml` must enable the Node.js compatibility flag:
+> **Requires `nodejs_compat` on workerd.** The SDK uses `AsyncLocalStorage` for per-request context isolation. Add to `wrangler.toml`:
 > ```toml
 > compatibility_flags = ["nodejs_compat"]
 > ```
-> If `node:async_hooks` is unavailable, the SDK transparently falls back to a synchronous stack-based ContextManager (no extra dependency) — suppression still works, but cross-`await` parent linking and per-request context isolation degrade to best-effort.
+> Without it the SDK falls back to a synchronous stack-based context manager — suppression still works, but cross-`await` span parenting and per-request isolation degrade to best-effort.
 
-### Why a ContextManager (0.3.2)
+### `WorkersConfig` options
 
-`context.with(...)` in OpenTelemetry is a **no-op unless a ContextManager is registered** with the global API. Before 0.3.2 the Workers path registered only a tracer provider, so `suppressTracing()` — the primary defence against the self-trace feedback loop — silently did nothing in production (the exporter's own `POST /v1/traces` could be re-traced by host fetch auto-instrumentation, looping). As of **0.3.2** the SDK registers a ContextManager exactly once at init. With `AsyncLocalStorageContextManager` (the default, on Node and on workerd under `nodejs_compat`) you also get **cross-`await` parent→child span linking** and **per-request context isolation** — concurrent requests no longer share or clobber the active span.
+| Option | Type | Notes |
+| --- | --- | --- |
+| `service` | `string` | **Required.** Service name that appears in the Heystack console. |
+| `apiKey` | `string?` | Defaults to `env.HEYSTACK_API_KEY`. |
+| `getUser` | `(req: Request) => { id?, session?, requestId? } \| undefined` | Called per request. `id` → `enduser.id`, `session` → `session.id`, `requestId` → `http.request.id` (falls back to the `cf-ray` header). |
+| `instrumentBindings` | `boolean \| string[]` | `true` = auto child spans for all detected D1/KV/R2/Vectorize bindings; `string[]` = only the named bindings. Default `false`. |
+| `waitUntil` | `(p: Promise<unknown>) => void` | Override the isolate keep-alive hook; defaults to the auto-detected `ctx.waitUntil`. |
+| `endpoint` | `string?` | Override the ingest endpoint (advanced). |
 
-`instrument()` must be the **outermost** wrapper if other middleware also wraps the handler, so the request span covers everything inside:
+### Automatic tracing
+
+`instrument()` traces the following automatically, with no additional config:
+
+- **Incoming requests (`fetch`)** — a SERVER span per request, carrying `http.request.method`, `url.full`, `url.path`, `server.address`, `http.response.status_code`, and `enduser.id`/`client.address`/geo attributes (see [Client enrichment](#client-enrichment) below). An inbound W3C `traceparent` header is continued so the client and server share one trace; a `traceparent` response header (+ `Access-Control-Expose-Headers: traceparent`) is set so downstream clients can read it.
+- **Outbound `fetch`** — each outbound subrequest while a request span is active gets a CLIENT child span (`http.request.method`, `url.full`, `server.address`, `http.response.status_code`). A W3C `traceparent` header is injected into the subrequest so a downstream Heystack-instrumented service continues the same trace (distributed tracing across services). The exporter's own ingest POST is never traced.
+- **Queue consumers (`queue`)** — a CONSUMER span per batch, with `messaging.destination.name` (queue name) and `messaging.batch.message_count`.
+- **Scheduled handlers (`scheduled`)** — an INTERNAL span per invocation, with `controller.cron`.
+- **Binding calls** (when `instrumentBindings` is set) — a child span for every D1 query (`db.statement`), KV read/write, R2 operation, and Vectorize query.
+
+### Client enrichment
+
+These attributes are set automatically on every SERVER span from request metadata:
+
+| Attribute | Source |
+| --- | --- |
+| `enduser.id` | `getUser(req).id` |
+| `session.id` | `getUser(req).session` |
+| `http.request.id` | `getUser(req).requestId` or `cf-ray` header |
+| `client.address` | `CF-Connecting-IP` header |
+| `geo.country`, `geo.region`, `geo.city`, `geo.asn` | Cloudflare `req.cf` object |
+
+### Manual spans: `withSpan` / `addEvent`
+
+Inside a traced handler, add finer-grained spans without touching the OpenTelemetry API directly:
 
 ```ts
-export default instrument(withOtherMiddleware(worker), { service: "my-worker" });
+import { instrument, withSpan, addEvent } from "@heystack/otel/workers";
+
+// Inside a fetch handler:
+const result = await withSpan("parse-payload", { "source": "body" }, async (span) => {
+  addEvent("parsing-started");
+  span.setAttribute("content-type", req.headers.get("content-type") ?? "");
+  return JSON.parse(await req.text());
+});
+
+// Without attrs:
+const data = await withSpan("call-llm", async () => {
+  return callMyAI();
+});
 ```
 
-Set the key as a secret: `wrangler secret put HEYSTACK_API_KEY`.
+`withSpan(name, attrs?, fn)` — runs `fn` inside a new child span parented to the currently-active span. The span is started before `fn` and ended in `finally`; exceptions are recorded on the span and re-thrown. The `fn` receives the live `Span` as its argument.
+
+`addEvent(name, attrs?)` — adds a named event to the currently-active span. No-op when no span is active.
+
+### Why a ContextManager
+
+`context.with(...)` in OpenTelemetry is a **no-op unless a ContextManager is registered** with the global API. Without one, `suppressTracing()` — the primary defence against the self-trace feedback loop — silently does nothing in production. As of **0.3.2** the SDK registers a ContextManager exactly once at init. With `AsyncLocalStorage` (workerd under `nodejs_compat`, Node) you also get **cross-`await` parent→child span linking** and **per-request context isolation** — concurrent requests no longer share or clobber the active span.
 
 As of **0.3.1** `instrument()` **forwards every other handler your Worker exports** — `queue`, `scheduled`, `tail`, etc. — untouched, so wrapping never drops a handler Cloudflare requires for deploy (it previously returned only `{ fetch }`, which broke Queue/Cron Workers). On top of forwarding, `queue` and `scheduled` are themselves traced when present: each gets a root span via the global tracer (`queue <queueName>` as a CONSUMER span with batch attributes; `scheduled <cron>` as an INTERNAL span with the cron attribute), flushed via `ctx.waitUntil` just like `fetch`.
 
+### Streaming responses & trace correlation (`/workers`)
+
+`instrument()` keeps the SERVER span open until the response body finishes
+streaming, so a streamed response's duration includes time-to-last-byte and the
+span carries a `first_byte` event (time-to-first-byte). It also continues an
+inbound W3C `traceparent` (so a client request and the server handler share one
+trace) and returns a `traceparent` response header — plus
+`Access-Control-Expose-Headers: traceparent` so browser clients can read it.
+
 ### Durable Objects are NOT covered by `instrument()`
 
 `instrument()` wraps the keys of the **default-export handler object** (`fetch`/`queue`/`scheduled`/… ). **Durable Objects are separate named class exports**, so spreading the handler object does not touch them — a DO's `fetch`/`alarm` methods run **untraced** even when your Worker's default export is wrapped.
@@ -204,6 +274,7 @@ As belt-and-suspenders the exporter also drops any span whose HTTP target points
 
 ## Migration / versioning
 
+- **`0.5.0`** — **`/workers`: identity enrichment, binding tracing, outbound-fetch tracing, manual span helpers.** New `WorkersConfig` options: `getUser` (attach `enduser.id`/`session.id`/`http.request.id` per request from a synchronous callback), `instrumentBindings` (auto child spans for D1/KV/R2/Vectorize — `true` = all detected, or a `string[]` to select). Outbound `fetch` calls made inside a traced handler automatically get CLIENT child spans with `traceparent` injection (distributed tracing across services). New ergonomic exports from `/workers`: `withSpan(name, attrs?, fn)` runs a function inside a named child span (auto-parented, exceptions recorded, `span.end()` in `finally`); `addEvent(name, attrs?)` adds an event to the active span. No breaking changes; all new options are optional.
 - **`0.4.3`** — **feedback-loop guard extended to the Node path (cost fix).** The self-instrumentation loop the Workers path fixed in 0.3.1/0.3.2 was still live on plain Node / Next-on-Node: the OTLP-over-`http` exporter's `POST /v1/traces` was auto-instrumented and re-exported, so ~77% of ingested spans in production were the exporter tracing itself — needless ingest + ClickHouse compute. 0.4.3 ignores ingest-host requests in the HTTP/undici auto-instrumentations **and** filters self-spans at the exporter boundary (covers caller-supplied `instrumentations` too). The hostname matcher is now a shared module used by both `/node` and `/workers`. No API change. **Action: upgrade and redeploy any Node/Next-on-Node app** — it cuts ingested span volume sharply.
 - **`0.3.5`** — **type-constraint fix (Workers).** A Worker whose `queue` consumer is typed with a concrete message body — `queue(batch: MessageBatch<MyJob>, …)`, the normal case — failed to compile against `instrument()` in 0.3.4 (`TS2345`: `MessageBatch<unknown>` not assignable to `MessageBatch<MyJob>`). The `WorkerHandler` constraint declared its entrypoints as arrow properties, whose parameters are checked **contravariantly** under `strictFunctionTypes`, so a narrowed handler wasn't assignable. 0.3.5 declares them with **method syntax** (bivariant parameters) and widens the batch to `MessageBatch<any>`, mirroring Cloudflare's own `ExportedHandler` — a typed-queue Worker now type-checks with a bare `instrument(handler, cfg)`. Runtime behaviour unchanged. Also adds a **consumer type-check gate** (`pnpm consumer-typecheck`, run in `check` and `prepublishOnly`) that compiles a fully-typed Worker against the built `dist` through the public `exports` map and asserts `satisfies ExportedHandler<Env>` — the regression that escaped in 0.3.3/0.3.4 now fails the build before publish.
 - **`0.3.4`** — **type-inference fix (Workers).** Restores `instrument()`'s ability to infer the handler's concrete `Env` type. In 0.3.3 the signature was `instrument<E = unknown, H extends WorkerHandler<E>>`, so `E` defaulted to `unknown` and was never recovered from the handler — under `strictFunctionTypes` a Worker typed `fetch(req, env: Env, ctx)` then failed to compile (`TS2345: 'Env' is not assignable to 'unknown'`) unless the caller passed `instrument<Env>(...)` explicitly. 0.3.4 infers `E` from the handler argument (`instrument<H extends WorkerHandler<any>>(...): Instrumented<EnvOf<H>, H>`), so a bare `instrument(handler, cfg)` type-checks again. Runtime behaviour is unchanged; no `0.3.3` consumer needs the explicit type arg after upgrading.

package/dist/workers-bindings.d.ts

@@ -0,0 +1,33 @@
+import { type Span } from "@opentelemetry/api";
+export interface InstrumentBindingsOpts {
+    /**
+     * Factory that creates and starts a new child span. Called at binding method
+     * invocation time (inside the traced handler scope), so `context.active()`
+     * at that moment correctly parents to the root span.
+     *
+     * For integration: pass `(name, attrs) => tracer.startSpan(name, { attributes: attrs }, context.active())`.
+     * For unit tests: inject a fake so no global provider is required.
+     */
+    startSpan: (name: string, attrs: Record<string, unknown>) => Span;
+    /**
+     * `true`  → auto-detect and wrap all D1/KV/R2/Vectorize bindings.
+     * `string[]` → only wrap bindings whose env key is listed.
+     */
+    select: boolean | string[];
+}
+/**
+ * Wrap an env object's Cloudflare bindings so that each binding operation
+ * emits a child span under the currently-active OTel context.
+ *
+ * Detects binding type by duck-typing (D1: `prepare`; KV: `get`+`put`+`list`;
+ * R2: `get`+`put`+`head`; Vectorize: `query`+`upsert`). Unrecognised bindings
+ * are passed through unchanged.
+ *
+ * Each wrapped binding is a `Proxy` over the original — non-wrapped prototype
+ * methods fall through to the real binding so no functionality is lost.
+ *
+ * @param env  - The Worker env / binding bag.
+ * @param opts - `startSpan` factory + `select` filter.
+ * @returns A shallow copy of `env` with selected bindings replaced by proxies.
+ */
+export declare function instrumentEnv<E extends Record<string, unknown>>(env: E, opts: InstrumentBindingsOpts): E;

package/dist/workers-bindings.js

@@ -0,0 +1,205 @@
+// ---------------------------------------------------------------------------
+// Cloudflare binding instrumentation for @heystack/otel/workers.
+//
+// Wraps D1, KV, R2, and Vectorize bindings with OTel child spans so that
+// every binding operation is visible as a child of the active request span.
+//
+// WinterCG-safe: no `node:*` imports. Span factory is injected so the logic
+// is pure and unit-testable without a global provider.
+// ---------------------------------------------------------------------------
+import { context, SpanStatusCode } from "@opentelemetry/api";
+import { isTracingSuppressed } from "@opentelemetry/core";
+// ---------------------------------------------------------------------------
+// Duck-type detectors — conservative; require the distinctive method set
+// exactly as documented in the task brief.
+// ---------------------------------------------------------------------------
+function isD1Like(b) {
+    return typeof b?.prepare === "function";
+}
+/** R2 is checked BEFORE KV because R2 also exposes `list`. */
+function isR2Like(b) {
+    return (typeof b?.get === "function" &&
+        typeof b?.put === "function" &&
+        typeof b?.head === "function");
+}
+function isKVLike(b) {
+    return (typeof b?.get === "function" &&
+        typeof b?.put === "function" &&
+        typeof b?.list === "function");
+}
+function isVectorizeLike(b) {
+    return (typeof b?.query === "function" &&
+        typeof b?.upsert === "function");
+}
+// ---------------------------------------------------------------------------
+// Span lifecycle helper
+// ---------------------------------------------------------------------------
+async function runWithSpan(span, fn) {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        span.recordException(err instanceof Error ? err : new Error(String(err)));
+        span.setStatus({
+            code: SpanStatusCode.ERROR,
+            message: err instanceof Error ? err.message : String(err),
+        });
+        throw err;
+    }
+    finally {
+        span.end();
+    }
+}
+// ---------------------------------------------------------------------------
+// Proxy helper — intercepts listed handlers, falls through to prototype for rest
+// ---------------------------------------------------------------------------
+function makeProxy(target, handlers) {
+    return new Proxy(target, {
+        get(t, prop, receiver) {
+            if (typeof prop === "string" && prop in handlers)
+                return handlers[prop];
+            const val = Reflect.get(t, prop, receiver);
+            return typeof val === "function" ? val.bind(t) : val;
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// D1 wrappers
+// ---------------------------------------------------------------------------
+function wrapD1Statement(stmt, sql, opts) {
+    const wrapOp = (op) => async (...args) => {
+        if (isTracingSuppressed(context.active())) {
+            return stmt[op](...args);
+        }
+        const span = opts.startSpan(`D1 ${op}`, {
+            "db.system": "d1",
+            "db.statement": sql,
+        });
+        return runWithSpan(span, () => stmt[op](...args));
+    };
+    return makeProxy(stmt, {
+        all: wrapOp("all"),
+        first: wrapOp("first"),
+        run: wrapOp("run"),
+        raw: wrapOp("raw"),
+        bind(...bindArgs) {
+            // Return a wrapped statement so the sql propagates through bind chains.
+            return wrapD1Statement(stmt.bind(...bindArgs), sql, opts);
+        },
+    });
+}
+function wrapD1(binding, opts) {
+    return makeProxy(binding, {
+        prepare(sql) {
+            return wrapD1Statement(binding.prepare(sql), sql, opts);
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// KV wrappers
+// ---------------------------------------------------------------------------
+function wrapKV(binding, opts, namespace) {
+    const wrapOp = (op, getKey) => async (...args) => {
+        if (isTracingSuppressed(context.active())) {
+            return binding[op](...args);
+        }
+        const attrs = { "kv.namespace": namespace };
+        const key = getKey?.(...args);
+        if (key !== undefined)
+            attrs["kv.key"] = key;
+        const span = opts.startSpan(`KV ${op}`, attrs);
+        return runWithSpan(span, () => binding[op](...args));
+    };
+    return makeProxy(binding, {
+        get: wrapOp("get", (key) => key),
+        put: wrapOp("put", (key) => key),
+        list: wrapOp("list"),
+        delete: wrapOp("delete", (key) => key),
+    });
+}
+// ---------------------------------------------------------------------------
+// R2 wrappers
+// ---------------------------------------------------------------------------
+function wrapR2(binding, opts, bucket) {
+    const wrapOp = (op, getKey) => async (...args) => {
+        if (isTracingSuppressed(context.active())) {
+            return binding[op](...args);
+        }
+        const attrs = { "r2.bucket": bucket };
+        const key = getKey?.(...args);
+        if (key !== undefined)
+            attrs["r2.key"] = key;
+        const span = opts.startSpan(`R2 ${op}`, attrs);
+        return runWithSpan(span, () => binding[op](...args));
+    };
+    return makeProxy(binding, {
+        get: wrapOp("get", (key) => key),
+        put: wrapOp("put", (key) => key),
+        head: wrapOp("head", (key) => key),
+        delete: wrapOp("delete", (key) => key),
+    });
+}
+// ---------------------------------------------------------------------------
+// Vectorize wrappers
+// ---------------------------------------------------------------------------
+function wrapVectorize(binding, opts, indexName) {
+    const wrapOp = (op) => async (...args) => {
+        if (isTracingSuppressed(context.active())) {
+            return binding[op](...args);
+        }
+        const span = opts.startSpan(`Vectorize ${op}`, {
+            "vectorize.index": indexName,
+        });
+        return runWithSpan(span, () => binding[op](...args));
+    };
+    return makeProxy(binding, {
+        query: wrapOp("query"),
+        upsert: wrapOp("upsert"),
+        insert: wrapOp("insert"),
+        deleteByIds: wrapOp("deleteByIds"),
+        getByIds: wrapOp("getByIds"),
+    });
+}
+// ---------------------------------------------------------------------------
+// Main export
+// ---------------------------------------------------------------------------
+/**
+ * Wrap an env object's Cloudflare bindings so that each binding operation
+ * emits a child span under the currently-active OTel context.
+ *
+ * Detects binding type by duck-typing (D1: `prepare`; KV: `get`+`put`+`list`;
+ * R2: `get`+`put`+`head`; Vectorize: `query`+`upsert`). Unrecognised bindings
+ * are passed through unchanged.
+ *
+ * Each wrapped binding is a `Proxy` over the original — non-wrapped prototype
+ * methods fall through to the real binding so no functionality is lost.
+ *
+ * @param env  - The Worker env / binding bag.
+ * @param opts - `startSpan` factory + `select` filter.
+ * @returns A shallow copy of `env` with selected bindings replaced by proxies.
+ */
+export function instrumentEnv(env, opts) {
+    const result = { ...env };
+    const { select } = opts;
+    for (const key of Object.keys(env)) {
+        // Filter: if select is an array, only wrap keys in the list.
+        if (select !== true && !select.includes(key))
+            continue;
+        const binding = env[key];
+        if (isD1Like(binding)) {
+            result[key] = wrapD1(binding, opts);
+        }
+        else if (isR2Like(binding)) {
+            // R2 before KV — R2 also has `list`, so checking `head` first avoids mis-classifying.
+            result[key] = wrapR2(binding, opts, key);
+        }
+        else if (isKVLike(binding)) {
+            result[key] = wrapKV(binding, opts, key);
+        }
+        else if (isVectorizeLike(binding)) {
+            result[key] = wrapVectorize(binding, opts, key);
+        }
+        // Unrecognised bindings are left as-is.
+    }
+    return result;
+}

package/dist/workers.d.ts

@@ -23,6 +23,11 @@ interface OtlpKeyValue {
     key: string;
     value: OtlpAnyValue;
 }
+interface OtlpSpanEvent {
+    timeUnixNano: string;
+    name: string;
+    attributes: OtlpKeyValue[];
+}
 interface OtlpSpan {
     traceId: string;
     spanId: string;
@@ -32,6 +37,7 @@ interface OtlpSpan {
     startTimeUnixNano: string;
     endTimeUnixNano: string;
     attributes: OtlpKeyValue[];
+    events: OtlpSpanEvent[];
     status: {
         code: number;
         message?: string;
@@ -54,6 +60,14 @@ interface OtlpTracesPayload {
  * hence the same resource, so we emit a single resourceSpans entry.
  */
 export declare function serializeSpans(spans: ReadableSpan[]): OtlpTracesPayload;
+/** Parse a W3C `traceparent`. Returns null for malformed or all-zero ids. */
+export declare function parseTraceparent(header: string | null): {
+    traceId: string;
+    spanId: string;
+    traceFlags: number;
+} | null;
+/** Add `value` to Access-Control-Expose-Headers without duplicating it. */
+export declare function appendExposeHeader(headers: Headers, value: string): void;
 /**
  * Test-only helper: run the self-span attribute check directly against a plain
  * attribute bag + ingest hostname, without constructing a ReadableSpan. The
@@ -61,6 +75,12 @@ export declare function serializeSpans(spans: ReadableSpan[]): OtlpTracesPayload
  * the exporter derives via `safeHostname(cfg.url)`.
  */
 export declare function isSelfSpanForTest(attrs: Record<string, unknown>, ingestHost: string): boolean;
+/**
+ * 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 declare function __resetFetchInstrumentation(): void;
 /**
  * A WinterCG-compatible OTLP/JSON span exporter. POSTs ended spans to the
  * Heystack ingest using the platform `fetch` — no Node built-ins.
@@ -68,7 +88,7 @@ export declare function isSelfSpanForTest(attrs: Record<string, unknown>, ingest
 export declare class HeystackSpanExporter implements SpanExporter {
     private readonly url;
     /** Hostname (no port) of the ingest endpoint, used to drop self-trace spans. */
-    private readonly ingestHost;
+    readonly ingestHost: string;
     private readonly headers;
     private shutdownState;
     /**
@@ -122,6 +142,23 @@ export interface WorkersConfig {
      * automatically borrows the request context's `ctx.waitUntil`.
      */
     waitUntil?: (p: Promise<unknown>) => void;
+    /**
+     * Optional hook called on each incoming request to supply identity context.
+     * Return `{ id }` to tag the SERVER span with `enduser.id`, `{ session }` for
+     * `session.id`, or `{ requestId }` to override `http.request.id` (otherwise
+     * the `cf-ray` request header is used as a fallback). Any field may be omitted.
+     */
+    getUser?: (req: Request) => {
+        id?: string;
+        session?: string;
+        requestId?: string;
+    } | undefined;
+    /**
+     * Declare which bindings to instrument with tracing (Task 5). Pass `true` to
+     * trace all bindings, or an array of binding names to trace selectively.
+     * Defaults to `false` (no binding tracing). Consumed by a later task.
+     */
+    instrumentBindings?: boolean | string[];
 }
 /**
  * A `BasicTracerProvider` with the underlying `HeystackSpanExporter` attached so
@@ -143,12 +180,31 @@ export type HeystackTracerProvider = BasicTracerProvider & {
  */
 export declare function createTracerProvider(config: HeystackOptions): HeystackTracerProvider;
 /**
- * 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 declare class AlsContextManager implements ContextManager {
+    private _als;
+    constructor();
+    active(): Context;
+    with<A extends unknown[], F extends (...args: A) => ReturnType<F>>(ctx: Context, fn: F, thisArg?: ThisParameterType<F>, ...args: A): ReturnType<F>;
+    bind<T>(_ctx: Context, target: T): T;
+    enable(): this;
+    disable(): 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 declare class SyncStackContextManager implements ContextManager {
     private _stack;
@@ -269,4 +325,22 @@ type EnvOf<H> = H extends {
     scheduled: (controller: ScheduledController, env: infer E, ctx: ExecutionContext) => unknown;
 } ? E : unknown;
 export declare function instrument<H extends WorkerHandler<any>>(handler: H, config: WorkersConfig): Instrumented<EnvOf<H>, H>;
+/**
+ * Run `fn` inside a new child span named `name`. The span is automatically
+ * parented to the currently-active span (via `context.active()`), started
+ * before `fn` and ended in `finally` — so the caller never needs to call
+ * `span.end()`. If `fn` throws, the exception is recorded on the span and
+ * the status is set to ERROR before re-throwing.
+ *
+ * Two call signatures are supported:
+ *   withSpan("name", async (span) => { ... })
+ *   withSpan("name", { attr: "value" }, async (span) => { ... })
+ */
+export declare function withSpan<T>(name: string, fn: (span: Span) => T | Promise<T>): Promise<T>;
+export declare function withSpan<T>(name: string, attrs: Record<string, string | number | boolean>, fn: (span: Span) => T | Promise<T>): Promise<T>;
+/**
+ * Add a named event (with optional attributes) to the currently-active span.
+ * No-op when no span is active.
+ */
+export declare function addEvent(name: string, attrs?: Record<string, string | number | boolean>): void;
 export type { Span };

package/dist/workers.js

@@ -8,13 +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
@@ -116,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),
     };
 }
@@ -139,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
@@ -164,6 +200,143 @@ 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 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";
+}
+/**
+ * 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 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];
+    }
+    const headers = new Headers(init?.headers);
+    headers.set("traceparent", traceparent);
+    return [input, { ...(init ?? {}), headers }];
+}
+/**
+ * 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;
+}
+/**
+ * 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 __resetFetchInstrumentation() {
+    if (_fetchWrapper && globalThis.fetch === _fetchWrapper && _originalFetch) {
+        globalThis.fetch = _originalFetch;
+    }
+    _fetchInstrumented = false;
+    _originalFetch = undefined;
+    _fetchWrapper = undefined;
+}
+// ---------------------------------------------------------------------------
 // Exporter
 // ---------------------------------------------------------------------------
 /**
@@ -231,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 });
@@ -355,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 = [];
@@ -412,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() {
@@ -456,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;
 }
 /**
@@ -562,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: {
@@ -570,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)));
@@ -658,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.3",
+  "version": "0.5.0",
   "description": "Runtime-aware OpenTelemetry tracing that exports to Heystack (Node, Next.js, Workers).",
   "license": "MIT",
   "type": "module",