@heystack/otel 0.4.2 → 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.
@@ -200,8 +270,12 @@ As of **0.3.1** the exporter **suppresses tracing for its own ingest POST**, and
 
 As belt-and-suspenders the exporter also drops any span whose HTTP target points at the configured ingest origin. As of **0.3.2** that match is **hostname-accurate**: full-URL attributes (`url.full`, `http.url`) are parsed and compared on `.hostname` (case-insensitive, port-stripped) so a sibling domain like `myingest.heystack.dev` is no longer a false positive and an explicit port like `ingest.heystack.dev:443` is correctly matched; host-only attributes (`server.address`, `net.peer.name`, `net.peer.hostname`, `http.host`, `peer.address`) are port-stripped and compared by hostname.
 
+**The `/node` (and Next-on-Node) path got the same guard in `0.4.3`.** Before then, only the Workers/Edge exporter dropped self-spans; on a plain Node runtime the OTLP-over-`http` exporter's own `POST /v1/traces` was still captured by the HTTP/undici auto-instrumentation and re-exported, so the **same feedback loop ran on Node** (production measurement: ~77% of all ingested spans were `fetch POST .../v1/traces`). `0.4.3` (a) configures the HTTP + undici auto-instrumentations to ignore outbound requests to the ingest host, and (b) wraps the exporter so any span targeting the ingest origin is filtered before export — the latter holds even if you pass your own `instrumentations` array. Same hostname-accurate matcher as the Workers path (shared module). No API change; upgrade and redeploy.
+
 ## 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.
 - **`0.3.3`** — `/next` uses bare, exports-mapped dynamic imports so the OpenNext (Cloudflare Pages) build resolves the workers entry correctly (fixes a build break). Workers/Node paths unchanged.

package/dist/node.d.ts

@@ -1,5 +1,7 @@
 import { NodeSDK } from "@opentelemetry/sdk-node";
 import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
+import { type ExportResult } from "@opentelemetry/core";
+import type { ReadableSpan, SpanExporter } from "@opentelemetry/sdk-trace-base";
 import { type HeystackOptions } from "./core.js";
 /**
  * The element type the NodeSDK `instrumentations` config accepts (an OTel
@@ -24,6 +26,32 @@ export interface NodeOptions extends HeystackOptions {
      */
     instrumentations?: InstrumentationConfigItem[];
 }
+/**
+ * Wraps a span exporter and drops any span that targets the Heystack ingest
+ * origin before it is exported. On Node/Next the runtime auto-instruments
+ * outbound HTTP, so the exporter's own POST to `/v1/traces` becomes a CLIENT
+ * span → exported → re-captured → a sustained self-feeding loop. We measured
+ * this loop accounting for ~77% of ingested spans in production.
+ *
+ * The `/workers` entry stops the loop at the exporter via a suppressed context;
+ * Node's OTLP-over-`http` exporter cannot rely on that being honoured by every
+ * instrumentation version, so we filter at the exporter boundary instead. This
+ * is the universal guard — it works regardless of which instrumentations are
+ * loaded (including a caller-supplied `instrumentations` array). The
+ * `ignore*RequestHook` config below is the cheaper primary defence that stops
+ * the self-span from being created in the first place.
+ */
+export declare class SelfSpanFilteringExporter implements SpanExporter {
+    private readonly inner;
+    /** Bare ingest hostname (lower-case, no port), e.g. `ingest.heystack.dev`. */
+    private readonly ingestHost;
+    constructor(inner: SpanExporter, 
+    /** Bare ingest hostname (lower-case, no port), e.g. `ingest.heystack.dev`. */
+    ingestHost: string);
+    export(spans: ReadableSpan[], cb: (result: ExportResult) => void): void;
+    shutdown(): Promise<void>;
+    forceFlush(): Promise<void>;
+}
 /** Initialise Heystack tracing on a Node runtime. Call once, as early as possible. Returns the started SDK. */
 export declare function initHeystack(o: NodeOptions): NodeSDK;
 /** Flush + shutdown the SDK on SIGTERM/SIGINT so short-lived processes don't lose the last batch. Registers handlers at most once. */

package/dist/node.js

@@ -2,7 +2,78 @@ import { NodeSDK } from "@opentelemetry/sdk-node";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
 import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
 import { diag, DiagConsoleLogger, DiagLogLevel } from "@opentelemetry/api";
+import { ExportResultCode } from "@opentelemetry/core";
 import { buildExporterConfig } from "./core.js";
+import { isSelfSpanAttrs, safeHostname } from "./self-span.js";
+/**
+ * Wraps a span exporter and drops any span that targets the Heystack ingest
+ * origin before it is exported. On Node/Next the runtime auto-instruments
+ * outbound HTTP, so the exporter's own POST to `/v1/traces` becomes a CLIENT
+ * span → exported → re-captured → a sustained self-feeding loop. We measured
+ * this loop accounting for ~77% of ingested spans in production.
+ *
+ * The `/workers` entry stops the loop at the exporter via a suppressed context;
+ * Node's OTLP-over-`http` exporter cannot rely on that being honoured by every
+ * instrumentation version, so we filter at the exporter boundary instead. This
+ * is the universal guard — it works regardless of which instrumentations are
+ * loaded (including a caller-supplied `instrumentations` array). The
+ * `ignore*RequestHook` config below is the cheaper primary defence that stops
+ * the self-span from being created in the first place.
+ */
+export class SelfSpanFilteringExporter {
+    inner;
+    ingestHost;
+    constructor(inner, 
+    /** Bare ingest hostname (lower-case, no port), e.g. `ingest.heystack.dev`. */
+    ingestHost) {
+        this.inner = inner;
+        this.ingestHost = ingestHost;
+    }
+    export(spans, cb) {
+        const kept = this.ingestHost
+            ? spans.filter((s) => !isSelfSpanAttrs(s.attributes, this.ingestHost))
+            : spans;
+        // Nothing left to send: report success without a no-op POST (which would
+        // itself be a self-span and re-prime the loop).
+        if (kept.length === 0) {
+            cb({ code: ExportResultCode.SUCCESS });
+            return;
+        }
+        this.inner.export(kept, cb);
+    }
+    shutdown() {
+        return this.inner.shutdown();
+    }
+    forceFlush() {
+        return this.inner.forceFlush?.() ?? Promise.resolve();
+    }
+}
+/**
+ * Per-instrumentation config that tells the HTTP + undici auto-instrumentations
+ * to skip outbound requests to the ingest host, so the exporter's own POST is
+ * never turned into a span. Keyed by instrumentation package name; unknown keys
+ * are ignored by `getNodeAutoInstrumentations`, so this stays version-tolerant.
+ */
+function ingestIgnoreConfig(ingestHost) {
+    if (!ingestHost)
+        return {};
+    return {
+        "@opentelemetry/instrumentation-http": {
+            // RequestOptions carries host/hostname (and sometimes a full URL).
+            ignoreOutgoingRequestHook: (options) => {
+                const h = (options.hostname ?? options.host ?? "")
+                    .toString()
+                    .toLowerCase();
+                // host may include :port — compare on the bare hostname.
+                return h.split(":")[0] === ingestHost;
+            },
+        },
+        "@opentelemetry/instrumentation-undici": {
+            // Undici/fetch request: `.origin` is a full URL string, `.path` the path.
+            ignoreRequestHook: (req) => safeHostname(req.origin ?? "") === ingestHost,
+        },
+    };
+}
 /**
  * Process-level guard so SIGTERM/SIGINT handlers are registered AT MOST ONCE,
  * even if `initHeystack` is called repeatedly (e.g. Next dev server reloads).
@@ -26,12 +97,21 @@ export function initHeystack(o) {
     if (o.debug)
         diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.DEBUG);
     const cfg = buildExporterConfig(o);
+    const ingestHost = safeHostname(cfg.url);
+    // Primary defence: don't even create a span for the exporter's own POST.
+    // Only applies to our default auto-instrumentation set — a caller-supplied
+    // `instrumentations` array is left untouched (the exporter filter still
+    // protects it).
     const instrumentations = o.autoInstrument === false
         ? []
-        : (o.instrumentations ?? [getNodeAutoInstrumentations()]);
+        : (o.instrumentations ??
+            [getNodeAutoInstrumentations(ingestIgnoreConfig(ingestHost))]);
+    // Universal defence: filter any self-span at the exporter boundary, so the
+    // loop is killed regardless of which instrumentations are active.
+    const traceExporter = new SelfSpanFilteringExporter(new OTLPTraceExporter({ url: cfg.url, headers: cfg.headers }), ingestHost);
     const sdk = new NodeSDK({
         serviceName: o.service,
-        traceExporter: new OTLPTraceExporter({ url: cfg.url, headers: cfg.headers }),
+        traceExporter,
         instrumentations,
     });
     sdk.start();

package/dist/self-span.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Parse the hostname (no port) out of a URL, lower-cased; empty string if it
+ * can't be parsed. We compare on hostname rather than `host` so that an ingest
+ * URL like `ingest.heystack.dev` matches a captured span attribute of
+ * `ingest.heystack.dev:443` (and vice-versa).
+ */
+export declare function safeHostname(url: string): string;
+/**
+ * Strip a trailing `:port` from a bare host attribute and lower-case it, so a
+ * host-only attr like `ingest.heystack.dev:443` compares equal to the ingest
+ * hostname. IPv6 literals (`[::1]:443`) keep their bracketed form. Returns ""
+ * for anything that isn't a non-empty string.
+ */
+export declare function hostnameOf(hostAttr: unknown): string;
+/** Attributes that carry a full HTTP URL on a CLIENT/SERVER span. */
+export declare const HTTP_URL_ATTRS: readonly ["url.full", "http.url"];
+/** Host-only attributes (host[:port], no scheme/path). */
+export declare const HTTP_HOST_ATTRS: readonly ["server.address", "net.peer.name", "net.peer.hostname", "http.host", "peer.address"];
+/**
+ * True if `attrs` looks like a request to the configured ingest origin — i.e. it
+ * is (or could be) the exporter's own self-trace. For full-URL attributes we
+ * parse the URL and compare its `.hostname` (case-insensitive, port stripped) so
+ * a sibling domain like `myingest.heystack.dev` is NOT a false positive and an
+ * explicit port like `ingest.heystack.dev:443` IS matched. For host-only attrs
+ * we strip any `:port` and compare hostname equality.
+ *
+ * `ingestHost` must be a bare hostname (lower-case, no port), as produced by
+ * `safeHostname(cfg.url)`.
+ */
+export declare function isSelfSpanAttrs(attrs: Record<string, unknown>, ingestHost: string): boolean;

package/dist/self-span.js

@@ -0,0 +1,83 @@
+// ---------------------------------------------------------------------------
+// Self-span detection (shared by /workers and /node)
+//
+// When a runtime auto-instruments outbound HTTP (undici/fetch on Next/OpenNext,
+// the http module on Node), the exporter's own POST to `/v1/traces` becomes a
+// CLIENT span → exported → re-captured → a sustained loop. These helpers detect
+// a span that targets the configured ingest origin so we can drop it before it
+// feeds the loop. Pure string logic — no runtime imports — safe in any entry
+// (including the WinterCG-only `/workers` build).
+// ---------------------------------------------------------------------------
+/**
+ * Parse the hostname (no port) out of a URL, lower-cased; empty string if it
+ * can't be parsed. We compare on hostname rather than `host` so that an ingest
+ * URL like `ingest.heystack.dev` matches a captured span attribute of
+ * `ingest.heystack.dev:443` (and vice-versa).
+ */
+export function safeHostname(url) {
+    try {
+        return new URL(url).hostname.toLowerCase();
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Strip a trailing `:port` from a bare host attribute and lower-case it, so a
+ * host-only attr like `ingest.heystack.dev:443` compares equal to the ingest
+ * hostname. IPv6 literals (`[::1]:443`) keep their bracketed form. Returns ""
+ * for anything that isn't a non-empty string.
+ */
+export function hostnameOf(hostAttr) {
+    if (typeof hostAttr !== "string" || hostAttr === "")
+        return "";
+    const v = hostAttr.trim();
+    // Bracketed IPv6, optionally with a port: `[::1]` or `[::1]:443`.
+    if (v.startsWith("[")) {
+        const close = v.indexOf("]");
+        if (close !== -1)
+            return v.slice(0, close + 1).toLowerCase();
+        return v.toLowerCase();
+    }
+    // Strip a single trailing :port (host:port). A bare hostname has no colon.
+    const colon = v.lastIndexOf(":");
+    if (colon !== -1 && v.indexOf(":") === colon) {
+        return v.slice(0, colon).toLowerCase();
+    }
+    return v.toLowerCase();
+}
+/** Attributes that carry a full HTTP URL on a CLIENT/SERVER span. */
+export const HTTP_URL_ATTRS = ["url.full", "http.url"];
+/** Host-only attributes (host[:port], no scheme/path). */
+export const HTTP_HOST_ATTRS = [
+    "server.address",
+    "net.peer.name",
+    "net.peer.hostname",
+    "http.host",
+    "peer.address",
+];
+/**
+ * True if `attrs` looks like a request to the configured ingest origin — i.e. it
+ * is (or could be) the exporter's own self-trace. For full-URL attributes we
+ * parse the URL and compare its `.hostname` (case-insensitive, port stripped) so
+ * a sibling domain like `myingest.heystack.dev` is NOT a false positive and an
+ * explicit port like `ingest.heystack.dev:443` IS matched. For host-only attrs
+ * we strip any `:port` and compare hostname equality.
+ *
+ * `ingestHost` must be a bare hostname (lower-case, no port), as produced by
+ * `safeHostname(cfg.url)`.
+ */
+export function isSelfSpanAttrs(attrs, ingestHost) {
+    if (!ingestHost)
+        return false;
+    for (const key of HTTP_URL_ATTRS) {
+        const v = attrs[key];
+        if (typeof v === "string" && safeHostname(v) === ingestHost)
+            return true;
+    }
+    for (const key of HTTP_HOST_ATTRS) {
+        if (hostnameOf(attrs[key]) === ingestHost)
+            return true;
+    }
+    return false;
+}

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;
+}