@heystack/otel 0.15.0 → 0.17.0

package/README.md

@@ -13,7 +13,7 @@ Always read your key from the environment — never paste it into source:
 HEYSTACK_API_KEY=sk_live_…
 ```
 
-> **Use `@heystack/otel` `>=0.15.0`.** 0.15 extends direct Workers instrumentation to D1 sessions and batches. Cloudflare native OTel remains the preferred path for Workers; direct SDK export is a compatibility fallback when native tracing is unavailable. See [Migration](#migration--versioning) below.
+> **Use `@heystack/otel` `>=0.16.0`.** 0.16 extends direct Workers instrumentation to Durable Objects, Workflows, and the remaining Worker lifecycle entry points while preserving host-object return semantics. Cloudflare native OTel remains the preferred path for Workers; direct SDK export is a compatibility fallback when native tracing is unavailable. See [Migration](#migration--versioning) below.
 
 ## Runtime matrix
 
@@ -615,6 +615,7 @@ As belt-and-suspenders the exporter also drops any span whose HTTP target points
 
 ## Migration / versioning
 
+- **`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.
 - **`0.14.0`** — **gen_ai enrichment under Cloudflare native tracing, Mistral + AI-gateway detection, streaming usage; OpenTelemetry JS SDK 2.x.** (1) `/workers`: under `nativeTracing: "auto" | "native"` `instrument()` never installed the fetch wrapper, so native-mode Workers emitted **no** `gen_ai.*` telemetry. It now installs a lean LLM-only wrapper that opens a native `<operation> <provider>` span (e.g. `chat mistral`) with request/response `gen_ai.*` for detected providers and passes every other subrequest through untouched. (2) New provider **Mistral** (`api.mistral.ai`) and a new `ai.gateways` option (`[{ hostSuffix, pathPattern }]`, e.g. `{ hostSuffix: "wafersecurity.ai", pathPattern: "/p/:tenant/:provider" }`) that resolves the provider from an AI-gateway URL and stamps `heystack.ai.gateway`; `gemini` → `google`, `workers-ai` → `cloudflare`. New `gen_ai.operation.name`. (3) **Streaming (`text/event-stream`) responses now yield usage**: the body is `tee()`d and scanned line-by-line for `usage`/`usageMetadata`, model, id and finish reason only (never content); the span stays open until the stream closes. Google (`usageMetadata`) and Mistral response shapes added to the JSON path too. (4) New `/workers` exports `genAiRequestAttrs` / `genAiResponseAttrs` for manual `withSpan` spans around `env.AI.run` or any non-`fetch` LLM call. Native `error.type` now keeps the exception class instead of being overwritten with `error`. (5) All `@opentelemetry/*` dependencies move to the 2.x SDK line (`core`/`sdk-trace-base`/`resources` ^2.11, `sdk-node`/`exporter-trace-otlp-http` ^0.222, `auto-instrumentations-node` ^0.80, `semantic-conventions` ^1.43), clearing the downstream Dependabot alerts the 1.x line surfaced through this package (GHSA-8988-4f7v-96qf in `@opentelemetry/core`, GHSA-q7rr-3cgh-j5r3 in `sdk-node` / `auto-instrumentations-node` / `exporter-prometheus`, GHSA-45rx-2jwx-cxfr in `propagator-jaeger`). **Node ≥ 18.19 (or ≥ 20.6) is now required on `/node` and `/next`** — the 2.x SDK dropped Node 14/16. If you pass your own `instrumentations` array to `initHeystack`, upgrade those `@opentelemetry/instrumentation-*` packages to a release that peers on `@opentelemetry/core@^2` (the auto-instrumentations 0.80 set already does). `/workers` is still WinterCG-safe (no `node:*` imports). No other API changes; all new options are optional.
 - **`0.13.0`** — **Cloudflare-native tracing and complete Workers platform coverage.** On runtimes exposing `ctx.tracing`, `/workers` now joins Cloudflare's authoritative invocation trace instead of creating and exporting a duplicate tree. `nativeTracing: "auto"` is the default; `withCloudflareSpan(ctx, ...)` adds async-safe business spans, while fetch, queue, and scheduled handlers are enriched in the native tree. The new `/workers/agents` entry maps Cloudflare Agents observability callbacks and Tail Worker diagnostics to structured, redacted telemetry. Direct OTLP remains available with `nativeTracing: "direct"` for runtimes without the native API. Heystack ingest now preserves full OTLP trace/log fidelity, accepts OTLP metrics, and can import Workers Analytics metrics through the app-scoped Cloudflare connector. Native mode needs no Worker API-key secret and must not be combined with direct export.
@@ -658,3 +659,37 @@ claude mcp add --transport http heystack https://mcp.heystack.dev/mcp
 ```
 
 One-click links for Cursor and VS Code, commands for Codex/Gemini CLI, personal access tokens for CI, and the full tool reference are in the docs: **https://heystack.dev/docs/mcp**.
+
+
+## Product activity (0.17.0)
+
+Use `createProductAnalytics` from `@heystack/otel/product` alongside the runtime
+instrumentation. `track({ name, feature?, surface?, action?, outcome?, userId?,
+sessionId?, traceId?, spanId?, properties? })` queues an explicit event.
+`withContext(context)` returns an immutable request/session tracker;
+`feature(name, options?)` and `screen(name, options?)` are convenience methods.
+There is no mutable global user identity. Read the [full guide](https://heystack.dev/docs/product-activity).
+
+```ts
+import { createProductAnalytics } from "@heystack/otel/product";
+const activity = createProductAnalytics({ apiKey, service: "api", version: "2.4.0", allowedProperties: ["plan"] });
+activity.withContext({ userId, sessionId, feature: "signup" }).track({
+  name: "signup.completed", outcome: "succeeded", properties: { plan: "starter" },
+});
+await activity.flush(); // Workers: ctx.waitUntil(activity.flush())
+```
+
+Only allowlisted metadata is exported. Queue: 200 events; batches: 50;
+properties: 20 keys, 256-character strings. `track` reports queued, `flush`
+reports HTTP acceptance, not durable query visibility. Failed batches remain
+bounded for retry; counts may include duplicates. No automatic click/form/text
+capture. The browser-only `flushIntervalMs` timer is opt-in (minimum 5s);
+servers have no background timer. Call `shutdown()` to stop and flush.
+
+`instrumentWeb` now accepts `sessionId`, a UUID shared with product activity.
+Capture product collection's original fetch before calling `instrumentWeb`,
+or supply an original `fetch`. Rotate session UUID and discard bound user
+trackers on logout; restart replay to avoid linking different people. Replay
+sampling remains independent. Use a dedicated browser ingest configuration,
+never expose the backend secret. Native clients may emit the documented event
+attributes through existing log APIs.

package/dist/product.d.ts

@@ -0,0 +1,41 @@
+import { type HeystackOptions } from "./core.js";
+export interface ActivityContext {
+    /** Stable pseudonymous identifiers; never email addresses or credentials. */
+    userId?: string;
+    sessionId?: string;
+    feature?: string;
+    /** Stable screen/route name, not a URL containing customer data. */
+    surface?: string;
+    traceId?: string;
+    spanId?: string;
+}
+export interface ProductEvent extends ActivityContext {
+    name: string;
+    action?: string;
+    outcome?: "started" | "succeeded" | "failed" | "cancelled";
+    properties?: Record<string, string | number | boolean>;
+}
+export interface ProductAnalyticsOptions extends HeystackOptions {
+    environment?: string;
+    /** Supply an original, uninstrumented fetch if browser fetch is already patched. */
+    fetch?: typeof fetch;
+    /** Explicitly allow metadata keys. Unlisted properties are discarded. */
+    allowedProperties?: readonly string[];
+    /** Opt-in browser flush timer. Default: no background work; await flush on servers. */
+    flushIntervalMs?: number;
+}
+export interface ActivityTracker {
+    track(event: ProductEvent): boolean;
+    feature(name: string, event?: Omit<ProductEvent, "name" | "feature">): boolean;
+    screen(name: string, event?: Omit<ProductEvent, "name" | "surface">): boolean;
+    /** Immutable binding. Create one per request/session; never store request identity globally. */
+    withContext(context: ActivityContext): ActivityTracker;
+}
+export interface ProductAnalytics extends ActivityTracker {
+    flush(): Promise<boolean>;
+    shutdown(): Promise<boolean>;
+}
+/** Explicit product activity over the existing OTLP logs ingest path.
+ * Bounded, best-effort collection; never auto-captures UI text or form contents.
+ * The return value means queued, not delivered or verified business success. */
+export declare function createProductAnalytics(options: ProductAnalyticsOptions): ProductAnalytics;

package/dist/product.js

@@ -0,0 +1,97 @@
+import { suppressTracing } from "@opentelemetry/core";
+import { context, trace, isSpanContextValid } from "@opentelemetry/api";
+import { DEFAULT_ENDPOINT, releaseResourceAttributes } from "./core.js";
+const MAX_QUEUE = 200;
+const MAX_BATCH = 50;
+const NAME = /^[a-zA-Z][a-zA-Z0-9_.-]{0,127}$/;
+const SENSITIVE = /password|secret|token|authorization|cookie|email|phone|credit|card|body|prompt|content/i;
+const text = (v, max = 256) => typeof v === "string" ? v.trim().slice(0, max) : "";
+const id = (v, length) => typeof v === "string" && new RegExp(`^[a-f0-9]{${length}}$`, "i").test(v) && !/^0+$/.test(v) ? v.toLowerCase() : "";
+/** Explicit product activity over the existing OTLP logs ingest path.
+ * Bounded, best-effort collection; never auto-captures UI text or form contents.
+ * The return value means queued, not delivered or verified business success. */
+export function createProductAnalytics(options) {
+    const send = options.fetch ?? globalThis.fetch.bind(globalThis);
+    const endpoint = `${(options.endpoint ?? DEFAULT_ENDPOINT).replace(/\/+$/, "")}/v1/logs`;
+    const resource = { "service.name": options.service, ...releaseResourceAttributes(options),
+        ...(options.environment ? { "deployment.environment": text(options.environment) } : {}) };
+    const allowed = new Set((options.allowedProperties ?? []).filter(k => NAME.test(k) && !SENSITIVE.test(k)).slice(0, 20));
+    const kv = (key, value) => ({ key, value: typeof value === "boolean" ? { boolValue: value } : typeof value === "number" ? { doubleValue: value } : { stringValue: value } });
+    let queue = [];
+    let sequence = 0;
+    let stopped = false;
+    let inFlight;
+    let timer;
+    const tracker = (bound) => ({
+        track(event) {
+            if (stopped || queue.length >= MAX_QUEUE || !NAME.test(event.name))
+                return false;
+            const active = trace.getSpan(context.active())?.spanContext();
+            const ctx = { ...bound, ...event };
+            const attrs = {
+                "event.name": event.name, "event.domain": "product", "event.id": crypto.randomUUID(),
+            };
+            for (const [key, v] of Object.entries({ "enduser.id": ctx.userId, "session.id": ctx.sessionId,
+                "heystack.feature": ctx.feature, "heystack.surface": ctx.surface, "heystack.action": event.action, "heystack.outcome": event.outcome })) {
+                if (text(v))
+                    attrs[key] = text(v);
+            }
+            for (const key of allowed) {
+                const v = event.properties?.[key];
+                if (typeof v === "string")
+                    attrs[`heystack.properties.${key}`] = v.slice(0, 256);
+                else if (typeof v === "boolean" || (typeof v === "number" && Number.isFinite(v)))
+                    attrs[`heystack.properties.${key}`] = v;
+            }
+            const traceId = ctx.traceId !== undefined ? id(ctx.traceId, 32) : (active && isSpanContextValid(active) ? active.traceId : "");
+            const spanId = ctx.traceId ? id(ctx.spanId, 16) : active && isSpanContextValid(active) ? active.spanId : "";
+            queue.push({ sequence: ++sequence, record: { timeUnixNano: (BigInt(Date.now()) * 1000000n).toString(),
+                    severityText: event.outcome === "failed" ? "ERROR" : "INFO", severityNumber: event.outcome === "failed" ? 17 : 9,
+                    body: { stringValue: event.name }, attributes: Object.entries(attrs).map(([k, v]) => kv(k, v)),
+                    ...(traceId ? { traceId, ...(spanId ? { spanId } : {}) } : {}) } });
+            return true;
+        },
+        feature(name, event = {}) { return this.track({ ...event, name: "feature.used", feature: name }); },
+        screen(name, event = {}) { return this.track({ ...event, name: "screen.viewed", surface: name }); },
+        withContext(next) { return tracker({ ...bound, ...next }); },
+    });
+    const flushThrough = (target) => {
+        // Every caller waits for its own sequence watermark, including events queued
+        // during an earlier export. New producers cannot extend this caller forever.
+        if (inFlight)
+            return inFlight.then(ok => ok ? flushThrough(target) : false);
+        const run = async () => {
+            while (queue.length && queue[0].sequence <= target) {
+                const size = Math.min(MAX_BATCH, queue.filter(item => item.sequence <= target).length);
+                const batch = queue.splice(0, size);
+                const records = batch.map(item => item.record);
+                const controller = new AbortController();
+                const timeout = setTimeout(() => controller.abort(), 5000);
+                try {
+                    const response = await context.with(suppressTracing(context.active()), () => send(endpoint, { method: "POST", signal: controller.signal,
+                        headers: { "content-type": "application/json", authorization: `Bearer ${options.apiKey}` },
+                        body: JSON.stringify({ resourceLogs: [{ resource: { attributes: Object.entries(resource).map(([k, v]) => kv(k, v)) },
+                                    scopeLogs: [{ scope: { name: "@heystack/otel/product", version: "1" }, logRecords: records }] }] }) }));
+                    if (!response.ok)
+                        throw new Error("export failed");
+                }
+                catch {
+                    queue = [...batch, ...queue].slice(0, MAX_QUEUE);
+                    return false;
+                }
+                finally {
+                    clearTimeout(timeout);
+                }
+            }
+            return true;
+        };
+        inFlight = run().finally(() => { inFlight = undefined; });
+        return inFlight;
+    };
+    const flush = () => flushThrough(sequence);
+    if (typeof window !== "undefined" && options.flushIntervalMs !== undefined) {
+        timer = setInterval(() => { void flush(); }, Math.max(5000, Number.isFinite(options.flushIntervalMs) ? options.flushIntervalMs : 5000));
+    }
+    return { ...tracker({}), flush, async shutdown() { stopped = true; if (timer)
+            clearInterval(timer); return flush(); } };
+}

package/dist/traceparent.d.ts

@@ -0,0 +1,8 @@
+interface TraceparentSpanContext {
+    traceId: string;
+    spanId: string;
+    traceFlags: number;
+}
+/** Encode a span context as W3C traceparent, preserving the low flags byte. */
+export declare function makeTraceparent(context: TraceparentSpanContext): string;
+export {};

package/dist/traceparent.js

@@ -0,0 +1,5 @@
+/** Encode a span context as W3C traceparent, preserving the low flags byte. */
+export function makeTraceparent(context) {
+    const flags = (context.traceFlags & 0xff).toString(16).padStart(2, "0");
+    return `00-${context.traceId}-${context.spanId}-${flags}`;
+}

package/dist/web.d.ts

@@ -85,6 +85,8 @@ export interface InstrumentWebOptions {
      * resource of exported browser logs for commit-level attribution.
      */
     build?: string;
+    /** Optional shared UUID for product events, browser errors and replay. Rotate on logout. */
+    sessionId?: string;
     /** Optional app-supplied user identifier stamped on the session. */
     userId?: string;
     /** Local overrides; by default sampling + masking come from server config. */
@@ -144,6 +146,8 @@ export declare function tracingActive(opts: Pick<InstrumentWebOptions, "tracing"
  * (`cfg.errors_enabled`). **Fail-open**: an absent/`true` flag counts as enabled.
  */
 export declare function errorCaptureActive(opts: Pick<InstrumentWebOptions, "errors">, cfg: Pick<RecorderConfig, "errors_enabled">): boolean;
+/** A caller-owned session UUID allows product activity to correlate with replay. */
+export declare function resolveWebSessionId(candidate?: string): string;
 /** Entry point: fetch config, decide sampling, start rrweb, stream chunks.
  *  Returns a stop() function. Safe to call in any browser; no-ops on the server. */
 export declare function instrumentWeb(opts: InstrumentWebOptions): Promise<() => void>;

package/dist/web.js

@@ -100,6 +100,14 @@ export function tracingActive(opts, cfg) {
 export function errorCaptureActive(opts, cfg) {
     return opts.errors !== false && cfg.errors_enabled !== false;
 }
+/** A caller-owned session UUID allows product activity to correlate with replay. */
+export function resolveWebSessionId(candidate) {
+    if (candidate === undefined)
+        return crypto.randomUUID();
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(candidate))
+        throw new Error("sessionId must be a UUID");
+    return candidate;
+}
 /** Entry point: fetch config, decide sampling, start rrweb, stream chunks.
  *  Returns a stop() function. Safe to call in any browser; no-ops on the server. */
 export async function instrumentWeb(opts) {
@@ -125,7 +133,7 @@ export async function instrumentWeb(opts) {
     // One session id for the whole run — shared by errors, console logs AND replay
     // (created here, before the replay sampling gate, so errors correlate even when
     // replay isn't sampled; when it is, they share this id → error ↔ replay linking).
-    const sessionId = crypto.randomUUID();
+    const sessionId = resolveWebSessionId(opts.sessionId);
     // service.version / service.build for release attribution on exported browser logs.
     const releaseAttrs = releaseResourceAttributes({ version: opts.version, build: opts.build });
     // 2. Browser distributed tracing (opt-in) — INDEPENDENT of replay sampling. Emits

package/dist/workers-agents.d.ts

@@ -1,5 +1,5 @@
 import { type Span } from "@opentelemetry/api";
-import { type CloudflareNativeTracing } from "./workers";
+import { type CloudflareNativeTracing } from "./workers.js";
 /** Structural equivalent of the Agents SDK event; no `agents` peer required. */
 export interface CloudflareAgentEvent {
     type: string;

package/dist/workers-agents.js

@@ -1,5 +1,5 @@
 import { trace } from "@opentelemetry/api";
-import { withCloudflareSpan, } from "./workers";
+import { withCloudflareSpan, } from "./workers.js";
 const SENSITIVE_KEY = /(?:authorization|cookie|password|secret|token|api[_-]?key|prompt|completion|content|message)/i;
 const ERROR_EVENT = /(?::error|:failed|:stalled|:interrupted|:exhausted)$/;
 function sanitize(value, extraKeys, depth = 0) {

package/dist/workers-bindings.d.ts

@@ -10,11 +10,19 @@ export interface InstrumentBindingsOpts {
      */
     startSpan: (name: string, attrs: Record<string, unknown>, kind?: SpanKind) => Span;
     /**
-     * `true`  → auto-detect and wrap all supported Cloudflare bindings.
+     * `true`  → auto-detect and wrap every supported Cloudflare binding.
      * `string[]` → only wrap bindings whose env key is listed.
      */
     select: boolean | string[];
 }
+/**
+ * Run `fn`, ending `span` in `finally` and recording exceptions + ERROR status
+ * on failure (re-throwing). Internal helper shared with the class-level
+ * wrappers in workers.ts.
+ */
+export declare function runWithSpan<T>(span: Span, fn: () => Promise<T>): Promise<T>;
+/** Internal proxy builder shared with the class-level wrappers in workers.ts. */
+export declare function makeProxy(target: any, handlers: Record<string, Function>): any;
 /**
  * Build a new args array for `fetch(input, init?)` with a `traceparent` header
  * injected WITHOUT mutating the caller's original Request or init object.
@@ -37,6 +45,8 @@ export declare function injectTraceparentArgs(args: any[], traceparent: string):
  * - Workflow: `get`+`create`+`createBatch`
  * - Rate limit: `limit`
  * - Analytics Engine: `writeDataPoint`
+ * - Durable Object namespace: `idFromName`+`get`+`newUniqueId` (stub fetch/RPC spans)
+ * - Workflow binding: `create`+`createBatch`+`get` and not a DO namespace
  * - Service binding / Fetcher: `fetch` (last branch; most generic)
  *
  * Unrecognised bindings are passed through unchanged.

package/dist/workers-bindings.js

@@ -1,14 +1,15 @@
 // ---------------------------------------------------------------------------
 // Cloudflare binding instrumentation for @heystack/otel/workers.
 //
-// Wraps stable Cloudflare binding APIs with OTel child spans so that binding
-// operations are visible as children of the active request span.
+// Wraps supported Cloudflare data, AI, messaging, Durable Object, Workflow,
+// and Service binding operations with OTel child spans.
 //
-// WinterCG-safe: no `node:*` imports. Span factory is injected so the logic
+// WinterCG-safe: no Node-builtin imports. Span factory is injected so the logic
 // is pure and unit-testable without a global provider.
 // ---------------------------------------------------------------------------
 import { context, SpanKind, SpanStatusCode } from "@opentelemetry/api";
 import { isTracingSuppressed } from "@opentelemetry/core";
+import { makeTraceparent } from "./traceparent.js";
 // ---------------------------------------------------------------------------
 // Duck-type detectors — conservative; require the distinctive method set
 // exactly as documented in the task brief.
@@ -63,7 +64,12 @@ function isServiceLike(b) {
 // ---------------------------------------------------------------------------
 // Span lifecycle helper
 // ---------------------------------------------------------------------------
-async function runWithSpan(span, fn) {
+/**
+ * Run `fn`, ending `span` in `finally` and recording exceptions + ERROR status
+ * on failure (re-throwing). Internal helper shared with the class-level
+ * wrappers in workers.ts.
+ */
+export async function runWithSpan(span, fn) {
     try {
         return await fn();
     }
@@ -95,11 +101,80 @@ function runSyncWithSpan(span, fn) {
         span.end();
     }
 }
+function isPromiseLike(value) {
+    return (((typeof value === "object" && value !== null) || typeof value === "function") &&
+        typeof value.then === "function");
+}
+function recordSpanError(span, error) {
+    span.recordException(error instanceof Error ? error : new Error(String(error)));
+    span.setStatus({
+        code: SpanStatusCode.ERROR,
+        message: error instanceof Error ? error.message : String(error),
+    });
+}
+/** Trace a call without replacing synchronous, Promise, or custom thenable results. */
+function runWithSpanPreservingReturn(span, fn) {
+    try {
+        const result = fn();
+        if (isPromiseLike(result)) {
+            let settled = false;
+            const finish = (error, failed = false) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (failed) {
+                    try {
+                        recordSpanError(span, error);
+                    }
+                    catch {
+                        // Instrumentation must not alter the observed thenable's behaviour.
+                    }
+                }
+                try {
+                    span.end();
+                }
+                catch {
+                    // Instrumentation must not alter the observed thenable's behaviour.
+                }
+            };
+            try {
+                const observer = result.then(() => finish(), (error) => finish(error, true));
+                // A non-compliant custom thenable may reject the observer despite the
+                // rejection callback above. Consume that rejection without replacing
+                // or awaiting the original RPC/Promise object returned to the caller.
+                if (isPromiseLike(observer)) {
+                    try {
+                        observer.then(undefined, () => undefined);
+                    }
+                    catch {
+                        // Calling then() is best-effort for exotic host thenables.
+                    }
+                }
+            }
+            catch (error) {
+                finish(error, true);
+            }
+            return result;
+        }
+        span.end();
+        return result;
+    }
+    catch (error) {
+        recordSpanError(span, error);
+        span.end();
+        throw error;
+    }
+}
+/** Transform either a synchronous result or a promise without changing its category. */
+function mapReturn(result, map) {
+    return isPromiseLike(result) ? Promise.resolve(result).then(map) : map(result);
+}
 // ---------------------------------------------------------------------------
 // Proxy helper — intercepts listed handlers, falls through to prototype for rest
 // ---------------------------------------------------------------------------
 const rawTarget = Symbol("heystack.rawBindingTarget");
-function makeProxy(target, handlers) {
+/** Internal proxy builder shared with the class-level wrappers in workers.ts. */
+export function makeProxy(target, handlers) {
     return new Proxy(target, {
         get(t, prop, receiver) {
             if (prop === rawTarget)
@@ -455,6 +530,14 @@ function wrapAnalyticsEngine(binding, opts, name) {
 export function injectTraceparentArgs(args, traceparent) {
     const [input, ...rest] = args;
     if (input instanceof Request) {
+        const originalInit = rest[0];
+        if (originalInit?.headers !== undefined) {
+            const init = { ...originalInit };
+            const headers = new Headers(originalInit.headers);
+            headers.set("traceparent", traceparent);
+            init.headers = headers;
+            return [input, init, ...rest.slice(1)];
+        }
         const headers = new Headers(input.headers);
         headers.set("traceparent", traceparent);
         return [new Request(input, { headers }), ...rest];
@@ -474,13 +557,202 @@ function wrapService(binding, opts, name) {
             }
             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 traceparent = makeTraceparent(sc);
             const injectedArgs = injectTraceparentArgs(args, traceparent);
             return runWithSpan(span, () => binding.fetch(...injectedArgs));
         },
     });
 }
 // ---------------------------------------------------------------------------
+// Durable Object namespace binding
+// ---------------------------------------------------------------------------
+/** DO namespace detector using the real synchronous Cloudflare API surface. */
+function isDurableObjectNamespaceLike(b) {
+    return (typeof b?.idFromName === "function" &&
+        typeof b?.get === "function" &&
+        typeof b?.newUniqueId === "function");
+}
+/** Fetcher/DO members that are platform operations or must retain host semantics. */
+const DO_STUB_RPC_EXCLUDED = new Set([
+    "fetch",
+    "connect",
+    "alarm",
+    "webSocketMessage",
+    "webSocketClose",
+    "webSocketError",
+    "id",
+    "name",
+    "dup",
+    "constructor",
+    "then",
+]);
+/** Wrap a DO stub: CLIENT spans on fetch (+ traceparent injection) and RPC calls. */
+function wrapDurableObjectStub(stub, opts, name) {
+    const fetch = (...args) => {
+        if (isTracingSuppressed(context.active()))
+            return stub.fetch(...args);
+        const span = opts.startSpan(`DO ${name} fetch`, { "peer.service": name }, SpanKind.CLIENT);
+        const sc = span.spanContext();
+        // Propagate into the DO so its own spans join this trace.
+        const injectedArgs = injectTraceparentArgs(args, makeTraceparent(sc));
+        return runWithSpanPreservingReturn(span, () => stub.fetch(...injectedArgs));
+    };
+    // workerd exposes RPC methods through a wildcard property hook, so method
+    // names are not enumerable. Resolve and wrap them lazily on first access.
+    const rpcMethods = new Map();
+    return new Proxy(stub, {
+        get(target, property) {
+            if (property === "fetch")
+                return fetch;
+            const value = Reflect.get(target, property, target);
+            if (typeof property !== "string" ||
+                typeof value !== "function" ||
+                DO_STUB_RPC_EXCLUDED.has(property) ||
+                property in Object.prototype) {
+                return typeof value === "function" ? value.bind(target) : value;
+            }
+            const cached = rpcMethods.get(property);
+            if (cached)
+                return cached;
+            // Capture the host callable returned for this property. Calling it with
+            // the original stub as receiver preserves both ordinary and workerd RPC
+            // method semantics; the wrapper itself remains stable across reads.
+            const method = value;
+            const wrapped = (...args) => {
+                if (isTracingSuppressed(context.active())) {
+                    return Reflect.apply(method, target, args);
+                }
+                const span = opts.startSpan(`DO ${name} ${property}`, { "peer.service": name, "rpc.method": property }, SpanKind.CLIENT);
+                return runWithSpanPreservingReturn(span, () => Reflect.apply(method, target, args));
+            };
+            rpcMethods.set(property, wrapped);
+            return wrapped;
+        },
+    });
+}
+function wrapDurableObjectNamespace(ns, opts, name) {
+    const handlers = {
+        // Namespace lookup is local and synchronous. Trace the returned stub's
+        // actual fetch/RPC calls, not get() itself.
+        get: (...args) => wrapDurableObjectStub(ns.get(...args), opts, name),
+    };
+    if (typeof ns.getByName === "function") {
+        handlers.getByName = (...args) => wrapDurableObjectStub(ns.getByName(...args), opts, name);
+    }
+    if (typeof ns.jurisdiction === "function") {
+        handlers.jurisdiction = (...args) => wrapDurableObjectNamespace(ns.jurisdiction(...args), opts, name);
+    }
+    // idFromName/idFromString/newUniqueId are synchronous local operations and
+    // fall through untouched.
+    return makeProxy(ns, handlers);
+}
+// ---------------------------------------------------------------------------
+// Workflows binding wrapper
+// ---------------------------------------------------------------------------
+/** Workflow binding: exposes create/createBatch/get and is not a DO namespace. */
+function isWorkflowBindingLike(b) {
+    return (typeof b?.create === "function" &&
+        typeof b?.createBatch === "function" &&
+        typeof b?.get === "function" &&
+        !isDurableObjectNamespaceLike(b));
+}
+const WORKFLOW_INSTANCE_METHODS = [
+    "pause",
+    "resume",
+    "terminate",
+    "restart",
+    "status",
+    "sendEvent",
+];
+function workflowId(value) {
+    if (typeof value === "string" && value.length > 0)
+        return value;
+    if (value && typeof value === "object") {
+        const id = value.id;
+        if (typeof id === "string" && id.length > 0)
+            return id;
+    }
+    return undefined;
+}
+function workflowBatchIds(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.map(workflowId).filter((id) => id !== undefined);
+}
+function wrapWorkflowInstance(instance, opts, name) {
+    if (!instance || typeof instance !== "object")
+        return instance;
+    const target = instance;
+    const handlers = {};
+    const instanceId = workflowId(instance);
+    for (const method of WORKFLOW_INSTANCE_METHODS) {
+        if (typeof target[method] !== "function")
+            continue;
+        handlers[method] = (...args) => {
+            const underlying = target[method];
+            if (isTracingSuppressed(context.active())) {
+                return underlying.apply(instance, args);
+            }
+            const attrs = {
+                "cloudflare.workflow.namespace": name,
+            };
+            if (instanceId !== undefined) {
+                attrs["cloudflare.workflow.instance_id"] = instanceId;
+            }
+            const span = opts.startSpan(`Workflow ${method}`, attrs, SpanKind.CLIENT);
+            return runWithSpanPreservingReturn(span, () => underlying.apply(instance, args));
+        };
+    }
+    return makeProxy(instance, handlers);
+}
+function wrapWorkflowBindingResult(value, op, opts, name, span) {
+    if (op === "deleteBatch")
+        return value;
+    if (op === "createBatch") {
+        if (!Array.isArray(value))
+            return value;
+        const returnedIds = workflowBatchIds(value);
+        if (span && returnedIds.length > 0) {
+            span.setAttribute("cloudflare.workflow.instance_ids", returnedIds);
+        }
+        return value.map((item) => wrapWorkflowInstance(item, opts, name));
+    }
+    const returnedId = workflowId(value);
+    if (span && returnedId !== undefined) {
+        span.setAttribute("cloudflare.workflow.instance_id", returnedId);
+    }
+    return wrapWorkflowInstance(value, opts, name);
+}
+function wrapWorkflowBinding(binding, opts, name) {
+    const baseAttrs = {
+        "cloudflare.workflow.namespace": name,
+        "cloudflare.binding.type": "workflow",
+        "cloudflare.binding.name": name,
+    };
+    const ops = ["create", "createBatch", "get", "deleteBatch"];
+    const handlers = {};
+    for (const op of ops) {
+        handlers[op] = (...args) => {
+            if (isTracingSuppressed(context.active())) {
+                return mapReturn(binding[op](...args), (value) => wrapWorkflowBindingResult(value, op, opts, name));
+            }
+            const attrs = { ...baseAttrs };
+            const instanceId = workflowId(args[0]);
+            const batchIds = op === "createBatch" || op === "deleteBatch" ? workflowBatchIds(args[0]) : [];
+            if (instanceId !== undefined) {
+                attrs["cloudflare.workflow.instance_id"] = instanceId;
+            }
+            if (batchIds.length > 0) {
+                attrs["cloudflare.workflow.instance_ids"] = batchIds;
+                attrs["cloudflare.workflow.batch.size"] = batchIds.length;
+            }
+            const span = opts.startSpan(`Workflow ${op}`, attrs, SpanKind.CLIENT);
+            return runWithSpanPreservingReturn(span, () => mapReturn(binding[op](...args), (value) => wrapWorkflowBindingResult(value, op, opts, name, span)));
+        };
+    }
+    return makeProxy(binding, handlers);
+}
+// ---------------------------------------------------------------------------
 // Main export
 // ---------------------------------------------------------------------------
 /**
@@ -497,6 +769,8 @@ function wrapService(binding, opts, name) {
  * - Workflow: `get`+`create`+`createBatch`
  * - Rate limit: `limit`
  * - Analytics Engine: `writeDataPoint`
+ * - Durable Object namespace: `idFromName`+`get`+`newUniqueId` (stub fetch/RPC spans)
+ * - Workflow binding: `create`+`createBatch`+`get` and not a DO namespace
  * - Service binding / Fetcher: `fetch` (last branch; most generic)
  *
  * Unrecognised bindings are passed through unchanged.
@@ -538,6 +812,12 @@ export function instrumentEnv(env, opts) {
         else if (isQueueLike(binding)) {
             result[key] = wrapQueue(binding, opts, key);
         }
+        else if (isDurableObjectNamespaceLike(binding)) {
+            result[key] = wrapDurableObjectNamespace(binding, opts, key);
+        }
+        else if (isWorkflowBindingLike(binding)) {
+            result[key] = wrapWorkflowBinding(binding, opts, key);
+        }
         else if (isWorkflowLike(binding)) {
             result[key] = wrapWorkflow(binding, opts, key);
         }