@heystack/otel 0.4.3 → 0.6.0

package/README.md

@@ -85,32 +85,120 @@ 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.
+
+### `WorkersConfig` options
 
-### Why a ContextManager (0.3.2)
+| 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`. |
+| `sampling` | `{ rate?: number }` | Head-sampling rate 0–1. `1` (default) keeps everything. `0.2` keeps ~20% of fresh root traces. Parent-respecting: a request that arrives with an inbound sampled `traceparent` is always recorded regardless of the rate. See [Head sampling](#head-sampling) below. |
+| `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). |
 
-`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.
+### Head sampling
 
-`instrument()` must be the **outermost** wrapper if other middleware also wraps the handler, so the request span covers everything inside:
+`sampling: { rate }` performs **head sampling** — the keep/drop decision is made at the start of each fresh root trace, before any export. Traces that are dropped never leave the worker (no egress, no ingest cost, no storage). Traces that are kept are exported in full.
 
 ```ts
-export default instrument(withOtherMiddleware(worker), { service: "my-worker" });
+export default instrument(worker, {
+  service: "my-api",
+  sampling: { rate: 0.2 }, // keep ~20% of traffic
+});
 ```
 
-Set the key as a secret: `wrangler secret put HEYSTACK_API_KEY`.
+The sampler is **deterministic by trace ID**: the same trace always makes the same decision, so parent→child consistency is maintained when this worker is in a call chain sampled at the same rate by another service.
+
+**Tradeoff:** head sampling can't guarantee keeping error traces — the drop/keep decision is made before the response status is known. If you need every error captured, keep `rate: 1` (the default). Heystack's ingest-side keep rules (error and slow retention) apply among traces that _are_ exported; they can't rescue a trace that was dropped in the worker before export.
+
+The `rate` governs **fresh root traces only** (no inbound `traceparent`, or `traceparent` with `sampled=0`). A request arriving with a sampled inbound `traceparent` (`sampled=1`) is always recorded — the parent's decision is respected, so a distributed trace is never split mid-flight by the child's sample rate.
+
+### 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
+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();
+});
+```
+
+`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 +292,8 @@ As belt-and-suspenders the exporter also drops any span whose HTTP target points
 
 ## Migration / versioning
 
+- **`0.6.0`** — **`/workers`: head sampling (`sampling: { rate }`).** New optional `WorkersConfig` field: `sampling.rate` (0–1, default `1`). Keeps a deterministic fraction of fresh root traces — the drop decision is made in the worker before export (no egress, no ingest cost). Parent-respecting: requests arriving with a sampled `traceparent` are always recorded. Consistent with server-side sampling (same trace-ID hash). No breaking changes; all new options are optional. See [Head sampling](#head-sampling).
+- **`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-sampler.d.ts

@@ -0,0 +1,13 @@
+import { type Sampler, type SamplingResult } from "@opentelemetry/sdk-trace-base";
+import type { Context, Attributes, Link, SpanKind } from "@opentelemetry/api";
+export declare function fnv01(s: string): number;
+export declare function traceKept(traceId: string, rate: number): boolean;
+export declare class HeystackRatioSampler implements Sampler {
+    private readonly rate;
+    constructor(rate: number);
+    shouldSample(_ctx: Context, traceId: string, _name: string, _kind: SpanKind, _attrs: Attributes, _links: Link[]): SamplingResult;
+    toString(): string;
+}
+export declare function makeSampler(sampling?: {
+    rate?: number;
+}): Sampler;

package/dist/workers-sampler.js

@@ -0,0 +1,42 @@
+import { SamplingDecision, ParentBasedSampler, AlwaysOnSampler, } from "@opentelemetry/sdk-trace-base";
+// FNV-1a 32-bit → [0,1). MUST stay byte-identical to apps/ingest/src/sampling.ts
+// so the SDK and ingest agree on which traces to keep.
+export function fnv01(s) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return (h >>> 0) / 0x100000000;
+}
+export function traceKept(traceId, rate) {
+    if (rate >= 1)
+        return true;
+    if (rate <= 0)
+        return false;
+    return fnv01(traceId) < rate;
+}
+export class HeystackRatioSampler {
+    rate;
+    constructor(rate) {
+        this.rate = rate;
+    }
+    shouldSample(_ctx, traceId, _name, _kind, _attrs, _links) {
+        return {
+            decision: traceKept(traceId, this.rate)
+                ? SamplingDecision.RECORD_AND_SAMPLED
+                : SamplingDecision.NOT_RECORD,
+        };
+    }
+    toString() {
+        return `HeystackRatioSampler{${this.rate}}`;
+    }
+}
+export function makeSampler(sampling) {
+    const rate = sampling?.rate;
+    if (rate === undefined || rate >= 1)
+        return new AlwaysOnSampler();
+    // ParentBased: a sampled/dropped PARENT (local or remote via traceparent) wins,
+    // so a distributed trace samples consistently; only the root uses the ratio.
+    return new ParentBasedSampler({ root: new HeystackRatioSampler(rate) });
+}

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,36 @@ 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[];
+    /**
+     * Head-sampling configuration. When omitted (or `rate` >= 1), all traces are
+     * kept. When `rate` < 1, a deterministic FNV-1a hash of the trace ID decides
+     * keep/drop at the root span — consistent with the ingest-side sampler so the
+     * SDK and backend agree. Error / slow-span retention is an ingest concern.
+     *
+     * Note: head sampling is parent-respecting, so an incoming request carrying a
+     * sampled `traceparent` is still recorded even at `rate: 0` (it is not an
+     * absolute kill-switch; it governs only fresh/root traces).
+     */
+    sampling?: {
+        rate?: number;
+    };
 }
 /**
  * A `BasicTracerProvider` with the underlying `HeystackSpanExporter` attached so
@@ -141,14 +191,37 @@ export type HeystackTracerProvider = BasicTracerProvider & {
  * must drain the exporter — `await provider.heystackExporter.forceFlush()` (or
  * `flushHeystack()`), not just `provider.forceFlush()`.
  */
-export declare function createTracerProvider(config: HeystackOptions): HeystackTracerProvider;
+export declare function createTracerProvider(config: HeystackOptions & {
+    sampling?: {
+        rate?: number;
+    };
+}): HeystackTracerProvider;
+/**
+ * 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 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).
+ * 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 +342,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,15 @@
 // 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";
+import { makeSampler } from "./workers-sampler.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 +118,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 +146,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 +201,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 +405,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 });
@@ -347,6 +524,7 @@ export function createTracerProvider(config) {
     const provider = new BasicTracerProvider({
         resource: new Resource({ [ATTR_SERVICE_NAME]: config.service }),
         spanProcessors: [new SimpleSpanProcessor(exporter)],
+        sampler: makeSampler(config.sampling),
     });
     // Attach the exporter so flush paths can await its in-flight fetches.
     return Object.assign(provider, { heystackExporter: exporter });
@@ -355,31 +533,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 +610,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 +653,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;
 }
 /**
@@ -524,6 +725,7 @@ export function instrument(handler, config) {
             service: config.service,
             endpoint: config.endpoint,
             waitUntil: config.waitUntil,
+            sampling: config.sampling,
         });
         return { provider, tracer: trace.getTracer("heystack") };
     };
@@ -562,6 +764,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 +783,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 +947,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.6.0",
   "description": "Runtime-aware OpenTelemetry tracing that exports to Heystack (Node, Next.js, Workers).",
   "license": "MIT",
   "type": "module",