@heystack/otel 0.19.0 → 0.19.1

package/README.md

@@ -480,7 +480,7 @@ The automatic `gen_ai.*` enrichment hooks `fetch`. Anything that doesn't go thro
 import { instrument, withSpan, genAiRequestAttrs, genAiResponseAttrs } from "@heystack/otel/workers";
 
 async function chat(env: Env, prompt: string) {
-  const model = "@cf/meta/llama-3.1-8b-instruct";
+  const model = "@cf/meta/llama-3.1-8b-instruct-fast";
   return withSpan(
     "chat cloudflare",
     { ...genAiRequestAttrs("cloudflare", { model, max_tokens: 256 }), "gen_ai.operation.name": "chat" },
@@ -732,6 +732,7 @@ As belt-and-suspenders the exporter also drops any span whose HTTP target points
 
 ## Migration / versioning
 
+- **`0.19.1`** — **Workers fixes found by the live Cloudflare run.** (1) A Durable Object class that extends `DurableObject` from `cloudflare:workers` and is wrapped with `wrapDurableObjectClass` failed to construct on Cloudflare (`constructor parameter 1 is not of type 'DurableObjectState'`): the base class now receives the genuine state, and the traced view replaces it on the instance, so `this.ctx.storage` stays traced. (2) With `instrumentBindings`, a service binding to a `WorkerEntrypoint` was mistaken for a D1 binding (its RPC stub answers every property name), so every RPC call through it failed (`The RPC receiver does not implement the method "bind"`); RPC service bindings are now detected first and their stubs pass through untouched, including nested property chains. (3) `flushHeystack()` (and the drain handed to `waitUntil`) no longer rejects when an export fails, so a down ingest or a rejected key never surfaces as an error in your Worker. No API changes; upgrade and redeploy.
 - **`0.19.0`** — **Cloudflare native spans, coverage gate and direct-mode parity, plus privacy defaults.** **Privacy defaults:** (1) Recorded URLs are redacted on every entry: userinfo stripped and sensitive query/fragment values (`key`, `apikey`, `token`, `code`, `access_token`, `X-Amz-Signature`, …) replaced with `REDACTED`; extend with `redactQueryParams: [...]` or opt out with `false`. (2) `client.address` is **no longer recorded by default** on `/workers` and is stripped from `/node` spans (with `http.client_ip` and SERVER-span peer IPs) — set `captureClientIp: true` to keep it. (3) `/workers` geo defaults to country only — `captureGeo: "full"` restores `geo.region`/`geo.city`/`geo.asn`. (4) `/web` strict replay masking now masks **all** page text (previously only inputs); use `data-hs-unmask` to reveal trusted elements, and a missing masking mode is treated as strict. (5) New `/workers` `trustInboundSampling` (default `true`). See [Privacy](#privacy-url-redaction--client-ip). **Cloudflare:** (1) **Binding attributes.** Every direct-mode binding span carries `cloudflare.binding.type` (`d1`, `kv`, `r2`, `durable_object`, `queue`, `ai`, `vectorize`, `workflow`, `ratelimit`, `analytics_engine`) and `cloudflare.binding.name` (the env key). **Rename:** the rate-limit type value `rate_limit` is now `ratelimit` (ingest accepts both). Queue spans add `cloudflare.queue.name`. (2) **D1** spans add `db.system.name: "cloudflare-d1"` and `db.query.text`; the older `db.system` / `db.statement` stay for one more minor version and will then be removed. (3) **Hashed keys (behaviour change).** KV keys and R2 object keys are no longer recorded raw: `kv.key` / `r2.key` / `cloudflare.do.storage.key` are replaced by `cloudflare.kv.query.keys`, `cloudflare.r2.request.key` and a hashed `cloudflare.do.storage.key` (the prefix through the first `:` or `/` is kept, the rest becomes `h:<16 hex>`; multi-key calls are comma-joined). If Web Crypto is unavailable the attribute is omitted, never the raw key. Hashing runs concurrently and never delays or changes the call; multi-key calls hash at most the first 10 keys and report the full count in `cloudflare.kv.query.key_count` / `cloudflare.r2.request.key_count`. **PII note:** the key prefix through the first `:` or `/` is kept verbatim (e.g. `avatars/h:…`), so never put personal data in key prefixes. Service-binding spans also carry `cloudflare.binding.type: "service"`. `wrapWorkerEntrypointClass` also traces the entrypoint's own `this.env` bindings when `instrumentBindings` is set. (4) **Durable Objects.** `ctx.storage.sql.exec()` emits `durable_object_storage_exec` (`db.query.text`, `cloudflare.durable_object.response.rows_read|rows_written` once the app finishes the cursor, `cloudflare.durable_object.id`); the cursor is never iterated by the SDK. `getAlarm` / `setAlarm` / `deleteAlarm` emit `durable_object_alarms_*`. WebSocket hibernation handlers are now named `DO <Class> webSocketMessage|webSocketClose|webSocketError` (previously `DO rpc …`) with `cloudflare.handler_type`. (5) **New `wrapWorkerEntrypointClass(cls, config)`** for `WorkerEntrypoint` classes: traces `fetch` like `instrument()` and each public RPC method as a SERVER span `rpc <method>` (`jsrpc.method`, `rpc.method`). RPC spans are direct-mode only; under native tracing Cloudflare already emits `jsrpc` spans, so RPC passes straight through. (6) The direct-mode resource now carries `cloud.provider: "cloudflare"` and `cloud.platform: "cloudflare.workers"`. **Migration notes (0.19):** (a) In native mode `http.route` is no longer the raw path: pass `routes` to get templated routes. (b) `kv.key` / `r2.key` are replaced by the hashed native attribute names above. (c) `db.system` / `db.statement` are deprecated in favour of `db.system.name` / `db.query.text`. (d) Binding type `rate_limit` is now `ratelimit`. (e) `CloudflareNativeTracing` / `CloudflareNativeSpan` remain exported as deprecated aliases of `CloudflareTracing` / `CloudflareSpan`. (f) Native enrichment is on for the kinds Cloudflare does not span itself (Workers AI, Vectorize, Workflows, Analytics Engine; Hyperdrive via `wrapSqlClient`); disable it per kind with `nativeEnrichment`, and an explicit `instrumentBindings` overrides the gate. Apps that already wrap AI calls manually may see a duplicate span until they opt out. (g) New `ai.gatewayExport`. (h) New `/workers` exports: `wrapWorkerEntrypointClass`, `wrapSqlClient`, `NATIVELY_COVERED`, `matchRoute`, and the types `CloudflareTracing`, `CloudflareSpan`, `BindingKind`.
 - **`0.16.0`** — **complete direct Workers lifecycle and binding coverage.** Durable Object namespace stubs now trace `fetch` and RPC calls with W3C trace propagation; Workflow bindings trace creation, batch creation, lookup, instance lifecycle methods, and deletion operations. Direct instrumentation also covers scheduled, queue, email, Tail Worker, and related Worker entry points, while preserving synchronous values, native promises, custom thenables, upgrade responses, host-object identity, and callback-scoped native span ownership. Service-binding propagation now respects caller-supplied request headers. No breaking changes.
 - **`0.15.0`** — **direct Workers D1 session and batch coverage.** With `nativeTracing: "direct"` and `instrumentBindings` enabled, prepared D1 statements, database/session `batch`, database `exec`, and statements created through `withSession` now receive child spans. Native Cloudflare OTel remains the recommended Workers path because it preserves Cloudflare's platform trace/log tree; use direct export only where `ctx.tracing` is unavailable. No breaking changes.

package/dist/workers-bindings.js

@@ -63,6 +63,18 @@ function isAnalyticsEngineLike(b) {
 function isServiceLike(b) {
     return typeof b?.fetch === "function";
 }
+/** A service binding to a WorkerEntrypoint answers EVERY property name with a callable
+ *  JS RPC stub, so it would pass every duck-typed check above (`prepare` looks like D1).
+ *  No real binding has a function under this name: one that does is an RPC stub. */
+const RPC_PROBE = "__heystackRpcProbe__";
+function isRpcServiceLike(b) {
+    try {
+        return typeof b?.fetch === "function" && typeof b?.[RPC_PROBE] === "function";
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Adapt a callback-scoped `withSpan` to the immediate-return `startSpan` shape
  * the legacy wrappers use. The callback stays open (pending promise) until the
@@ -668,7 +680,7 @@ export function injectTraceparentArgs(args, traceparent) {
     return [input, init];
 }
 function wrapService(binding, opts, name) {
-    return makeProxy(binding, {
+    const handlers = {
         fetch: async (...args) => {
             if (isTracingSuppressed(context.active())) {
                 return binding.fetch(...args);
@@ -681,6 +693,24 @@ function wrapService(binding, opts, name) {
                 : args;
             return runWithSpan(span, () => binding.fetch(...injectedArgs));
         },
+    };
+    if (!isRpcServiceLike(binding))
+        return makeProxy(binding, handlers);
+    // JS RPC binding: every other property is a callable stub that must reach the caller
+    // untouched. Reading `.bind` on it would itself be an RPC call (to a method named
+    // "bind"), and a bound copy would lose nested property chains (`env.SVC.users.get()`).
+    return new Proxy(binding, {
+        get(target, prop) {
+            if (prop === rawTarget)
+                return target;
+            if (prop === "fetch")
+                return handlers.fetch;
+            const value = Reflect.get(target, prop, target);
+            // connect() is a host method on the Fetcher and needs its receiver.
+            if (prop === "connect" && typeof value === "function")
+                return Function.prototype.bind.call(value, target);
+            return value;
+        },
     });
 }
 // ---------------------------------------------------------------------------
@@ -938,7 +968,12 @@ export function instrumentEnv(env, rawOpts) {
         if (select !== true && !select.includes(key))
             continue;
         const binding = env[key];
-        if (isD1Like(binding)) {
+        if (isRpcServiceLike(binding)) {
+            // First: an RPC stub matches every duck-typed check below.
+            if (allow("service"))
+                result[key] = wrapService(binding, stamped("service", key), key);
+        }
+        else if (isD1Like(binding)) {
             if (allow("d1"))
                 result[key] = wrapD1(binding, stamped("d1", key));
         }

package/dist/workers.js

@@ -1210,12 +1210,25 @@ export async function flushHeystack() {
         new Promise((resolve) => { timer = setTimeout(resolve, DRAIN_TIMEOUT_MS); }),
     ]).finally(() => { if (timer)
         clearTimeout(timer); });
-    if (typeof _provider.forceFlush === "function") {
-        await _provider.forceFlush();
+    // Telemetry must never fail the app: OpenTelemetry's provider.forceFlush rejects (with an
+    // array) when a processor fails or times out, and that would surface in an awaited
+    // flushHeystack() or as an uncaught waitUntil error on every request while ingest is down.
+    try {
+        if (typeof _provider.forceFlush === "function") {
+            await _provider.forceFlush();
+        }
+    }
+    catch {
+        // Dropped batch: the exporter already reported it; still drain what is in flight.
     }
     // The processor's forceFlush does not await our fire-and-forget fetch, so
     // drain the exporter's in-flight POSTs explicitly.
-    await _provider.heystackExporter.forceFlush();
+    try {
+        await _provider.heystackExporter.forceFlush();
+    }
+    catch {
+        // Same rule: an export failure is never the app's error.
+    }
 }
 /**
  * Wrap a Worker `ExecutionContext` so EVERY `ctx.waitUntil(promise)` ALSO
@@ -2151,6 +2164,21 @@ const doIdAttrs = (state) => {
     const id = durableObjectIdOf(state);
     return id ? { "cloudflare.durable_object.id": id } : {};
 };
+/** True when a class (or an ancestor) is named `name`, e.g. cloudflare:workers' `DurableObject`. */
+function extendsNamedBase(cls, name) {
+    try {
+        let c = Object.getPrototypeOf(cls);
+        for (let depth = 0; depth < 8 && typeof c === "function"; depth++) {
+            if (c.name === name)
+                return true;
+            c = Object.getPrototypeOf(c);
+        }
+    }
+    catch {
+        // Exotic prototype chains are treated as plain classes.
+    }
+    return false;
+}
 /** Proxy a DurableObjectState so `state.storage` resolves to the traced proxy. */
 function wrapDurableObjectState(state, startSpan) {
     if (!state || typeof state !== "object")
@@ -2230,12 +2258,35 @@ export function wrapDurableObjectClass(cls, opts = {}) {
     catch {
         // Best-effort enumeration — a hostile getter must never break decoration.
     }
+    // workerd's `DurableObject` base (cloudflare:workers) brand-checks its first argument, so a
+    // subclass of it must receive the genuine state. Classes without that base keep getting the
+    // traced view directly, which also traces storage calls made inside their constructor.
+    const nativeBase = extendsNamedBase(Base, "DurableObject");
     class Wrapped extends Base {
         /** Raw (unwrapped) state captured for flush scheduling. */
         __heystackState;
         constructor(...args) {
-            super(...args.map((arg, i) => i === 0 ? wrapDurableObjectState(arg, startSpan) : arg));
-            this.__heystackState = args[0];
+            const raw = args[0];
+            const traced = wrapDurableObjectState(raw, startSpan);
+            super(...(nativeBase ? args : [traced, ...args.slice(1)]));
+            this.__heystackState = raw;
+            // Swap the traced view in wherever the instance holds the state (`this.ctx` from the
+            // base, or a field the user assigned), so `this.ctx.storage` calls are traced.
+            if (nativeBase && traced !== raw) {
+                const self = this;
+                for (const key of new Set(["ctx", "state", ...Object.keys(self)])) {
+                    if (key === "__heystackState")
+                        continue;
+                    try {
+                        if (self[key] === raw) {
+                            Object.defineProperty(self, key, { value: traced, writable: true, configurable: true, enumerable: true });
+                        }
+                    }
+                    catch {
+                        // A non-configurable or frozen slot keeps the raw state: calls stay untraced, never broken.
+                    }
+                }
+            }
         }
     }
     if (typeof origFetch === "function") {

package/package.json

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