@heystack/otel 0.7.0 → 0.8.0

package/README.md

@@ -90,7 +90,7 @@ export default instrument(
     getUser: (req) => ({
       id: req.headers.get("x-user-id") ?? undefined,
     }),
-    instrumentBindings: true,  // auto-trace D1/KV/R2/Vectorize
+    instrumentBindings: true,  // auto-trace D1/KV/R2/Vectorize/AI/Queues/Service bindings
   },
 );
 ```
@@ -116,7 +116,7 @@ Set the key as a secret: `wrangler secret put HEYSTACK_API_KEY`.
 | `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`. |
+| `instrumentBindings` | `boolean \| string[]` | `true` = auto child spans for all detected D1 / KV / R2 / Vectorize / Workers AI / Queue producer / Service binding bindings; `string[]` = only the named bindings. Default `false`. |
 | `sampling` | `{ rate?: number } \| { remote: true }` | Head-sampling configuration. `{ rate }`: keep a deterministic fraction of fresh root traces (0–1; default `1` = keep all). `{ remote: true }`: fetch the rate from the Heystack config endpoint instead — lets you change it centrally without redeploying. Cold isolates keep all traffic until the first config fetch resolves; fails open if the config can't be reached. Parent-respecting in both modes: a request arriving with a sampled `traceparent` is always recorded. 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). |
@@ -159,7 +159,7 @@ On startup the worker fetches its configured rate from the Heystack config endpo
 - **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.
+- **Binding calls** (when `instrumentBindings` is set) — a child span for every D1 query (`db.statement`), KV read/write, R2 operation, Vectorize query, Workers AI inference (`gen_ai.*` attributes including model name and token usage), Queue `.send`/`.sendBatch` (PRODUCER spans with `messaging.*` attributes), and Service binding `.fetch` calls (CLIENT spans with `traceparent` injected so calls to other Workers stitch into the same distributed trace).
 
 ### Client enrichment
 
@@ -305,6 +305,7 @@ As belt-and-suspenders the exporter also drops any span whose HTTP target points
 
 ## Migration / versioning
 
+- **`0.8.0`** — **`/workers`: Workers AI, Queue producer, and Service binding instrumentation.** `instrumentBindings: true` now auto-wraps three additional binding types: `env.AI.run()` emits CLIENT spans with `gen_ai.system`, `gen_ai.request.model`, and `gen_ai.usage.input_tokens`/`output_tokens` (streaming results are never consumed); Queue `.send`/`.sendBatch` emit PRODUCER spans with `messaging.*` attributes including batch size; Service binding `.fetch` emits a CLIENT span and injects a W3C `traceparent` header into the outgoing request so calls to other Workers appear in the same distributed trace. `startSpan` factory now accepts an optional `SpanKind` for correct CLIENT/PRODUCER categorisation. No breaking changes.
 - **`0.7.0`** — **`/workers`: remote sampling (`sampling: { remote: true }`).** New `sampling` variant that fetches the head-sampling rate from the Heystack config endpoint at runtime, so you can change it from the console without redeploying. Cold isolates keep all traffic until the first config fetch resolves (fails open). If the config endpoint is unreachable, the worker keeps everything. Same parent-respecting rule as `sampling: { rate }`. No breaking changes; existing `sampling: { rate }` configs are unchanged.
 - **`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.

package/dist/workers-bindings.d.ts

@@ -1,33 +1,51 @@
-import { type Span } from "@opentelemetry/api";
+import { SpanKind, 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 integration: pass `(name, attrs, kind) => tracer.startSpan(name, { attributes: attrs, kind }, context.active())`.
      * For unit tests: inject a fake so no global provider is required.
      */
-    startSpan: (name: string, attrs: Record<string, unknown>) => Span;
+    startSpan: (name: string, attrs: Record<string, unknown>, kind?: SpanKind) => Span;
     /**
-     * `true`  → auto-detect and wrap all D1/KV/R2/Vectorize bindings.
+     * `true`  → auto-detect and wrap all D1/KV/R2/Vectorize/AI/Queue/Service bindings.
      * `string[]` → only wrap bindings whose env key is listed.
      */
     select: boolean | string[];
 }
+/**
+ * Build a new args array for `fetch(input, init?)` with a `traceparent` header
+ * injected WITHOUT mutating the caller's original Request or init object.
+ *
+ * - `Request` first arg → rebuilt as `new Request(original, { headers })`.
+ * - String/URL first arg → spread a new init object with an augmented Headers.
+ */
+export declare function injectTraceparentArgs(args: any[], traceparent: string): any[];
 /**
  * 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.
+ * Detects binding type by duck-typing:
+ * - D1: `prepare`
+ * - R2: `get`+`put`+`head`
+ * - KV: `get`+`put`+`list`
+ * - Vectorize: `query`+`upsert`
+ * - Workers AI: `run` (without `prepare`)
+ * - Queue producer: `send`+`sendBatch`
+ * - Service binding / Fetcher: `fetch` (last branch; most generic)
+ *
+ * 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.
  *
+ * Service-binding spans inject a W3C `traceparent` header into outgoing
+ * requests so calls to other Workers stitch into one distributed trace.
+ *
  * @param env  - The Worker env / binding bag.
- * @param opts - `startSpan` factory + `select` filter.
+ * @param opts - `startSpan` factory (now accepts optional `SpanKind`) + `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

@@ -1,13 +1,14 @@
 // ---------------------------------------------------------------------------
 // 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.
+// Wraps D1, KV, R2, Vectorize, Workers AI, Queue producers, and Service
+// 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 { context, SpanKind, SpanStatusCode } from "@opentelemetry/api";
 import { isTracingSuppressed } from "@opentelemetry/core";
 // ---------------------------------------------------------------------------
 // Duck-type detectors — conservative; require the distinctive method set
@@ -31,6 +32,24 @@ function isVectorizeLike(b) {
     return (typeof b?.query === "function" &&
         typeof b?.upsert === "function");
 }
+/**
+ * Workers AI: has `run` but NOT `prepare` (which would match D1 first anyway).
+ * The `prepare` exclusion is defensive — D1 is already matched before this branch.
+ */
+function isWorkersAILike(b) {
+    return (typeof b?.run === "function" &&
+        typeof b?.prepare !== "function");
+}
+/** Queue producer: exposes both `send` and `sendBatch`. */
+function isQueueLike(b) {
+    return (typeof b?.send === "function" &&
+        typeof b?.sendBatch === "function");
+}
+/** Service binding / Fetcher: last branch — anything with `.fetch`. Prior branches
+ *  exclude D1/R2/KV/Vectorize/AI/Queue, so order alone is sufficient. */
+function isServiceLike(b) {
+    return typeof b?.fetch === "function";
+}
 // ---------------------------------------------------------------------------
 // Span lifecycle helper
 // ---------------------------------------------------------------------------
@@ -161,21 +180,153 @@ function wrapVectorize(binding, opts, indexName) {
     });
 }
 // ---------------------------------------------------------------------------
+// Workers AI wrapper
+// ---------------------------------------------------------------------------
+function wrapWorkersAI(binding, opts, _name) {
+    return makeProxy(binding, {
+        run: async (...args) => {
+            if (isTracingSuppressed(context.active())) {
+                return binding.run(...args);
+            }
+            const attrs = {
+                "gen_ai.system": "cloudflare.workers_ai",
+            };
+            if (typeof args[0] === "string") {
+                attrs["gen_ai.request.model"] = args[0];
+            }
+            const span = opts.startSpan("AI run", attrs, SpanKind.CLIENT);
+            try {
+                const result = await binding.run(...args);
+                // Best-effort usage extraction — never read/await/tee the stream.
+                try {
+                    if (result &&
+                        typeof result === "object" &&
+                        !(result instanceof ReadableStream) &&
+                        typeof result.usage === "object") {
+                        const usage = result.usage;
+                        if (typeof usage.prompt_tokens === "number") {
+                            span.setAttribute("gen_ai.usage.input_tokens", usage.prompt_tokens);
+                        }
+                        if (typeof usage.completion_tokens === "number") {
+                            span.setAttribute("gen_ai.usage.output_tokens", usage.completion_tokens);
+                        }
+                    }
+                }
+                catch {
+                    // Swallow — a weird shape must never throw.
+                }
+                return result;
+            }
+            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();
+            }
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// Queue producer wrapper
+// ---------------------------------------------------------------------------
+function wrapQueue(binding, opts, name) {
+    const baseAttrs = {
+        "messaging.system": "cloudflare_queues",
+        "messaging.destination.name": name,
+    };
+    return makeProxy(binding, {
+        send: async (...args) => {
+            if (isTracingSuppressed(context.active())) {
+                return binding.send(...args);
+            }
+            const span = opts.startSpan("Queue send", { ...baseAttrs, "messaging.operation": "send" }, SpanKind.PRODUCER);
+            return runWithSpan(span, () => binding.send(...args));
+        },
+        sendBatch: async (...args) => {
+            if (isTracingSuppressed(context.active())) {
+                return binding.sendBatch(...args);
+            }
+            const batchAttrs = {
+                ...baseAttrs,
+                "messaging.operation": "sendBatch",
+            };
+            if (Array.isArray(args[0])) {
+                batchAttrs["messaging.batch.message_count"] = args[0].length;
+            }
+            const span = opts.startSpan("Queue sendBatch", batchAttrs, SpanKind.PRODUCER);
+            return runWithSpan(span, () => binding.sendBatch(...args));
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// Service binding / Fetcher wrapper + traceparent injection
+// ---------------------------------------------------------------------------
+/**
+ * Build a new args array for `fetch(input, init?)` with a `traceparent` header
+ * injected WITHOUT mutating the caller's original Request or init object.
+ *
+ * - `Request` first arg → rebuilt as `new Request(original, { headers })`.
+ * - String/URL first arg → spread a new init object with an augmented Headers.
+ */
+export function injectTraceparentArgs(args, traceparent) {
+    const [input, ...rest] = args;
+    if (input instanceof Request) {
+        const headers = new Headers(input.headers);
+        headers.set("traceparent", traceparent);
+        return [new Request(input, { headers }), ...rest];
+    }
+    // String or URL
+    const init = { ...(rest[0] ?? {}) };
+    const headers = new Headers(init.headers);
+    headers.set("traceparent", traceparent);
+    init.headers = headers;
+    return [input, init];
+}
+function wrapService(binding, opts, name) {
+    return makeProxy(binding, {
+        fetch: async (...args) => {
+            if (isTracingSuppressed(context.active())) {
+                return binding.fetch(...args);
+            }
+            const span = opts.startSpan(`Service ${name} fetch`, { "peer.service": name }, SpanKind.CLIENT);
+            const sc = span.spanContext();
+            const traceparent = `00-${sc.traceId}-${sc.spanId}-01`;
+            const injectedArgs = injectTraceparentArgs(args, traceparent);
+            return runWithSpan(span, () => binding.fetch(...injectedArgs));
+        },
+    });
+}
+// ---------------------------------------------------------------------------
 // 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.
+ * Detects binding type by duck-typing:
+ * - D1: `prepare`
+ * - R2: `get`+`put`+`head`
+ * - KV: `get`+`put`+`list`
+ * - Vectorize: `query`+`upsert`
+ * - Workers AI: `run` (without `prepare`)
+ * - Queue producer: `send`+`sendBatch`
+ * - Service binding / Fetcher: `fetch` (last branch; most generic)
+ *
+ * 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.
  *
+ * Service-binding spans inject a W3C `traceparent` header into outgoing
+ * requests so calls to other Workers stitch into one distributed trace.
+ *
  * @param env  - The Worker env / binding bag.
- * @param opts - `startSpan` factory + `select` filter.
+ * @param opts - `startSpan` factory (now accepts optional `SpanKind`) + `select` filter.
  * @returns A shallow copy of `env` with selected bindings replaced by proxies.
  */
 export function instrumentEnv(env, opts) {
@@ -199,6 +350,15 @@ export function instrumentEnv(env, opts) {
         else if (isVectorizeLike(binding)) {
             result[key] = wrapVectorize(binding, opts, key);
         }
+        else if (isWorkersAILike(binding)) {
+            result[key] = wrapWorkersAI(binding, opts, key);
+        }
+        else if (isQueueLike(binding)) {
+            result[key] = wrapQueue(binding, opts, key);
+        }
+        else if (isServiceLike(binding)) {
+            result[key] = wrapService(binding, opts, key);
+        }
         // Unrecognised bindings are left as-is.
     }
     return result;

package/dist/workers.js

@@ -838,7 +838,7 @@ export function instrument(handler, config) {
             if (config.instrumentBindings) {
                 const binTracer = trace.getTracer("heystack");
                 handlerEnv = instrumentEnv(env, {
-                    startSpan: (name, attrs) => binTracer.startSpan(name, { attributes: attrs }, context.active()),
+                    startSpan: (name, attrs, kind) => binTracer.startSpan(name, { attributes: attrs, kind }, context.active()),
                     select: config.instrumentBindings,
                 });
             }

package/package.json

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