@heystack/otel 0.18.0 → 0.19.1

package/dist/workers.js

@@ -7,7 +7,7 @@
 // `@opentelemetry/resources` and the platform `fetch` — all WinterCG-safe — and
 // ships its own OTLP/JSON-over-fetch span exporter so it runs on Workers/Edge
 // where the Node SDK cannot.
-import { context, createContextKey, INVALID_SPAN_CONTEXT, trace, SpanKind, SpanStatusCode, } from "@opentelemetry/api";
+import { context, createContextKey, trace, SpanKind, SpanStatusCode, } from "@opentelemetry/api";
 import { suppressTracing, isTracingSuppressed } from "@opentelemetry/core";
 import { ROOT_CONTEXT } from "@opentelemetry/api";
 import { resourceFromAttributes } from "@opentelemetry/resources";
@@ -16,9 +16,14 @@ import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
 import { buildExporterConfig, DEFAULT_ENDPOINT, releaseResourceAttributes, } from "./core.js";
 import { isSelfSpanAttrs, safeHostname } from "./self-span.js";
 import { llmRequestAttrs, llmResponseAttrs, llmContentAttrs, llmOperationName, resolveLLMProvider, scanSseStreamForUsage, } from "./llm-enrich.js";
-import { instrumentEnv, makeProxy, runWithSpan } from "./workers-bindings.js";
+import { instrumentEnv, keysOf, makeProxy, runWithSpan, runWithSpanKeyed, runWithSpanPreservingReturn, settlePendingKeyHashes, wrapSqlClient, } from "./workers-bindings.js";
+import { NATIVELY_COVERED, NATIVE_PROPAGATES_EXTERNAL, shouldEnrichNatively } from "./workers-coverage.js";
 import { makeSampler, loadRemoteSamplingRate } from "./workers-sampler.js";
+import { createNativePropagation, injectOutboundHeaders, isAiGatewayHost, NATIVE_PROPAGATION_CONTEXT_KEY, propagationTargetAllowed, propagationTraceparent, } from "./workers-propagation.js";
+import { resolveRoute } from "./workers-routes.js";
 import { makeTraceparent } from "./traceparent.js";
+import { NATIVE_TRACING_CONTEXT_KEY, NativeOtelSpan, getNativeTracing, nativeTracingFromContext, runNativeSpan, setNativeContextInit, } from "./workers-native.js";
+import { applySpanPrivacy, makeUrlRedactor, } from "./redact.js";
 // `ExportResult` / `ExportResultCode` mirror `@opentelemetry/core`. We define
 // them inline (structurally identical) rather than import them: core is only a
 // transitive dep of sdk-trace-base and isn't reliably resolvable, and keeping it
@@ -109,8 +114,9 @@ function toStatus(status) {
         out.message = status.message;
     return out;
 }
-function readableSpanToOtlp(span) {
+function readableSpanToOtlp(span, transform) {
     const ctx = span.spanContext();
+    const attrs = span.attributes;
     return {
         traceId: ctx.traceId,
         spanId: ctx.spanId,
@@ -121,7 +127,7 @@ function readableSpanToOtlp(span) {
         kind: toOtlpKind(span.kind),
         startTimeUnixNano: hrTimeToUnixNano(span.startTime),
         endTimeUnixNano: hrTimeToUnixNano(span.endTime),
-        attributes: toKeyValues(span.attributes),
+        attributes: toKeyValues(transform ? transform(attrs, span) : attrs),
         events: span.events.map((ev) => ({
             timeUnixNano: hrTimeToUnixNano(ev.time),
             name: ev.name,
@@ -136,7 +142,7 @@ function readableSpanToOtlp(span) {
  * All spans in a SimpleSpanProcessor batch share the same per-request provider,
  * hence the same resource, so we emit a single resourceSpans entry.
  */
-export function serializeSpans(spans) {
+export function serializeSpans(spans, transform) {
     const resourceAttrs = spans[0]
         ? spans[0].resource.attributes
         : {};
@@ -144,7 +150,7 @@ export function serializeSpans(spans) {
         resourceSpans: [
             {
                 resource: { attributes: toKeyValues(resourceAttrs) },
-                scopeSpans: [{ spans: spans.map(readableSpanToOtlp) }],
+                scopeSpans: [{ spans: spans.map((s) => readableSpanToOtlp(s, transform)) }],
             },
         ],
     };
@@ -228,6 +234,8 @@ export function isSelfSpanForTest(attrs, ingestHost) {
 // self-span guardrail satisfied and the path WinterCG-safe (pure string logic).
 // ---------------------------------------------------------------------------
 let _fetchInstrumented = false;
+/** URL redactor for outbound CLIENT spans (set from config by ensureGlobalProvider). */
+let _fetchRedact = makeUrlRedactor();
 let _originalFetch;
 let _fetchWrapper;
 /** Resolve the absolute URL of an outbound fetch arg (string | URL | Request). */
@@ -270,12 +278,6 @@ function injectTraceparent(input, init, traceparent) {
 }
 /** Max response body size to clone for gen_ai enrichment (512 KB). */
 const LLM_RESPONSE_SIZE_CAP = 512 * 1024;
-/**
- * Context key under which `runNativeSpan` / `withSpan` publish the request's
- * Cloudflare native tracer, so nested helpers (and the fetch wrapper) can join
- * the platform trace tree instead of creating OTel-provider spans.
- */
-const NATIVE_TRACING_CONTEXT_KEY = createContextKey("heystack.cloudflare.native-tracing");
 /**
  * Latest ingest host / ai config seen by `ensureFetchInstrumentation`. The
  * wrapper is installed ONCE per isolate but `instrument()` may reach it first
@@ -285,6 +287,37 @@ const NATIVE_TRACING_CONTEXT_KEY = createContextKey("heystack.cloudflare.native-
  */
 let _fetchIngestHost = "";
 let _fetchAiCfg = {};
+let _fetchPropagateTargets;
+/** True when the caller already supplied header `name` on this fetch. */
+function hasHeader(input, init, name) {
+    try {
+        return new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined)).has(name);
+    }
+    catch {
+        return false;
+    }
+}
+/** Bare ingest hostname for native mode (no exporter exists to derive it from). */
+function nativeIngestHost(config) {
+    return safeHostname(config.endpoint ?? DEFAULT_ENDPOINT);
+}
+/**
+ * Native root helper: record the inbound parent (only when it validates) and
+ * the invocation's synthetic propagation pair as link attributes, then run `fn`
+ * with the pair published in OTel context so outbound fetches can use it.
+ * These are SDK-minted ids, NOT Cloudflare's native ids (which don't exist).
+ */
+function withNativePropagation(span, inboundTraceparent, fn) {
+    const prop = createNativePropagation();
+    const parent = parseTraceparent(inboundTraceparent);
+    if (parent) {
+        span.setAttribute("heystack.parent.trace_id", parent.traceId);
+        span.setAttribute("heystack.parent.span_id", parent.spanId);
+    }
+    span.setAttribute("heystack.propagation.trace_id", prop.traceId);
+    span.setAttribute("heystack.propagation.span_id", prop.spanId);
+    return context.with(context.active().setValue(NATIVE_PROPAGATION_CONTEXT_KEY, prop), fn);
+}
 /** A promise whose settle handles are exposed. */
 function deferred() {
     let resolve;
@@ -395,7 +428,7 @@ async function enrichLLMResponse(span, provider, response, parsedReqBody, aiCfg)
  * deferred — that is what lets usage tokens land on the span without buffering
  * or delaying the stream. No OTel provider/exporter is involved.
  */
-function nativeLLMFetch(nativeTracing, resolved, url, input, init, originalFetch, aiCfg) {
+function nativeLLMFetch(nativeTracing, resolved, url, input, init, originalFetch, aiCfg, delegated = false) {
     const ready = deferred();
     const name = `${llmOperationName(url.pathname)} ${resolved.provider}`;
     let run;
@@ -404,7 +437,7 @@ function nativeLLMFetch(nativeTracing, resolved, url, input, init, originalFetch
         run = nativeTracing.enterSpan(name, async (nativeSpan) => {
             invoked = true;
             // Unsampled invocation: skip all enrichment work (no tee, no clone).
-            if (!nativeSpan.isTraced) {
+            if (nativeSpan.isTraced === false) {
                 try {
                     ready.resolve(await originalFetch(input, init));
                 }
@@ -413,9 +446,11 @@ function nativeLLMFetch(nativeTracing, resolved, url, input, init, originalFetch
                 }
                 return;
             }
-            const adapter = new NativeSpanAdapter(nativeSpan);
+            const adapter = new NativeOtelSpan(nativeSpan);
             const { attrs, parsedReqBody } = llmRequestSide(resolved, url, init);
             adapter.setAttributes({ ...attrs, "server.address": url.hostname });
+            if (delegated)
+                adapter.setAttribute("heystack.ai.delegated", true);
             try {
                 const response = await originalFetch(input, init);
                 adapter.setAttribute("http.response.status_code", response.status);
@@ -464,10 +499,11 @@ function nativeLLMFetch(nativeTracing, resolved, url, input, init, originalFetch
  * exporter's own uploads are never traced; native callers pass "" (no exporter).
  * `aiCfg` configures gen_ai enrichment (content capture is opt-in).
  */
-function ensureFetchInstrumentation(ingestHost, aiCfg = {}) {
+function ensureFetchInstrumentation(ingestHost, aiCfg = {}, propagateTargets) {
     if (ingestHost)
         _fetchIngestHost = ingestHost;
     _fetchAiCfg = aiCfg;
+    _fetchPropagateTargets = propagateTargets;
     if (_fetchInstrumented)
         return;
     _fetchInstrumented = true;
@@ -487,10 +523,27 @@ function ensureFetchInstrumentation(ingestHost, aiCfg = {}) {
         const nativeTracing = active.getValue(NATIVE_TRACING_CONTEXT_KEY);
         if (nativeTracing) {
             const url = parseTarget(input);
-            const resolved = url ? resolveLLMProvider(url, _fetchAiCfg.gateways) : null;
-            if (!url || !resolved)
+            if (!url)
                 return originalFetch(input, init);
-            return nativeLLMFetch(nativeTracing, resolved, url, input, init, originalFetch, _fetchAiCfg);
+            // Link headers: the invocation's synthetic ids, never to the Heystack
+            // ingest host and only to hosts allowed by `propagateTargets`.
+            let reqInput = input;
+            let reqInit = init;
+            const prop = active.getValue(NATIVE_PROPAGATION_CONTEXT_KEY);
+            const host = url.hostname.toLowerCase();
+            const gateway = isAiGatewayHost(url);
+            let injected = false;
+            if (prop && host !== _fetchIngestHost && propagationTargetAllowed(host, _fetchPropagateTargets)) {
+                injected = gateway && !hasHeader(input, init, "cf-aig-otel-trace-id");
+                [reqInput, reqInit] = injectOutboundHeaders(input, init, {
+                    traceparent: propagationTraceparent(prop),
+                    aiGateway: gateway ? { traceId: prop.traceId, parentSpanId: prop.spanId } : undefined,
+                });
+            }
+            const resolved = resolveLLMProvider(url, _fetchAiCfg.gateways);
+            if (!resolved)
+                return originalFetch(reqInput, reqInit);
+            return nativeLLMFetch(nativeTracing, resolved, url, reqInput, reqInit, originalFetch, _fetchAiCfg, injected && _fetchAiCfg.gatewayExport === true);
         }
         // Direct plane: nothing to parent to (a fetch outside a traced request).
         if (!trace.getSpan(active)) {
@@ -507,13 +560,27 @@ function ensureFetchInstrumentation(ingestHost, aiCfg = {}) {
             kind: SpanKind.CLIENT,
             attributes: {
                 "http.request.method": method,
-                "url.full": target,
+                // Redacted: userinfo stripped + sensitive query/fragment values
+                // (e.g. Gemini `?key=`, Supabase `?apikey=`) replaced with REDACTED.
+                "url.full": _fetchRedact(target),
                 "server.address": host,
             },
         }, active);
         const sc = span.spanContext();
         const traceparent = makeTraceparent(sc);
-        const [reqInput, reqInit] = injectTraceparent(input, init, traceparent);
+        let [reqInput, reqInit] = injectTraceparent(input, init, traceparent);
+        const directUrl = parseTarget(input);
+        const directGateway = directUrl !== null && isAiGatewayHost(directUrl);
+        if (directGateway) {
+            const ours = !hasHeader(input, init, "cf-aig-otel-trace-id");
+            // The span's REAL trace id + this CLIENT span id; existing headers win.
+            [reqInput, reqInit] = injectOutboundHeaders(reqInput, reqInit, {
+                traceparent,
+                aiGateway: { traceId: sc.traceId, parentSpanId: sc.spanId },
+            });
+            if (ours && _fetchAiCfg.gatewayExport === true)
+                span.setAttribute("heystack.ai.delegated", true);
+        }
         // gen_ai enrichment — request side (direct host or configured gateway).
         const url = parseTarget(input);
         const resolved = url ? resolveLLMProvider(url, _fetchAiCfg.gateways) : null;
@@ -568,6 +635,7 @@ export function __resetFetchInstrumentation() {
     _fetchWrapper = undefined;
     _fetchIngestHost = "";
     _fetchAiCfg = {};
+    _fetchRedact = makeUrlRedactor();
 }
 // ---------------------------------------------------------------------------
 // Exporter
@@ -630,6 +698,7 @@ function markManualFlushObserved() {
  * completes, letting the isolate be torn down and silently dropping the trace.
  */
 async function drainProvider(provider) {
+    await settlePendingKeyHashes();
     await provider.forceFlush().catch(() => { });
     await provider.heystackExporter.forceFlush().catch(() => { });
 }
@@ -681,8 +750,18 @@ export class HeystackSpanExporter {
      * the `pending` set + manual `flushHeystack()` when absent/unavailable.
      */
     waitUntil;
+    /**
+     * Privacy pass on every exported span — redacts URL attributes (`url.full`,
+     * `http.url`, `http.target`, `url.query`, …) so spans from host frameworks
+     * (Next/OpenNext, manual spans) are covered too, not just Heystack's own.
+     */
+    privacy;
     constructor(options) {
         const cfg = buildExporterConfig(options);
+        const redact = makeUrlRedactor(options);
+        // Client IP is gated at its source (instrument()'s SERVER span), so the
+        // exporter only redacts URLs and leaves deliberate manual attributes alone.
+        this.privacy = (attrs) => applySpanPrivacy(attrs, { redact, captureClientIp: true });
         this.url = cfg.url;
         this.ingestHost = safeHostname(cfg.url);
         this.headers = {
@@ -710,7 +789,7 @@ export class HeystackSpanExporter {
             resultCallback({ code: ExportResultCode.SUCCESS });
             return;
         }
-        const body = JSON.stringify(serializeSpans(exportable));
+        const body = JSON.stringify(serializeSpans(exportable, this.privacy));
         // Build the export chain as a promise we retain, so forceFlush() can await
         // the actual network write — INCLUDING the bounded retry/backoff, so a
         // waitUntil drain keeps the isolate alive until retries settle too. It
@@ -891,87 +970,31 @@ export class HeystackSpanExporter {
         }
     }
 }
-function nativeTracingFromContext() {
-    return context.active().getValue(NATIVE_TRACING_CONTEXT_KEY);
-}
 /**
- * Adapts Cloudflare's deliberately-small Span API to the OTel API shape used by
- * `withSpan`. Unsupported OTel operations degrade to attributes instead of
- * creating a second exporter/provider.
+ * Native mode: wrap the env's uncovered bindings (Workers AI, Vectorize,
+ * Workflows, Analytics Engine) so their calls become native child spans. An
+ * explicit `instrumentBindings` wins over the coverage gate.
  */
-class NativeSpanAdapter {
-    nativeSpan;
-    constructor(nativeSpan) {
-        this.nativeSpan = nativeSpan;
-    }
-    spanContext() { return INVALID_SPAN_CONTEXT; }
-    setAttribute(key, value) {
-        try {
-            if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
-                this.nativeSpan.setAttribute(key, value);
-            }
-            else if (Array.isArray(value)) {
-                this.nativeSpan.setAttribute(key, JSON.stringify(value));
-            }
-        }
-        catch {
-            // Telemetry must never surface as an application error (e.g. a platform
-            // span rejecting a value); drop the attribute instead.
-        }
-        return this;
-    }
-    setAttributes(attributes) {
-        for (const [key, value] of Object.entries(attributes)) {
-            if (value !== undefined)
-                this.setAttribute(key, value);
-        }
-        return this;
-    }
-    addEvent(name, attributesOrStartTime) {
-        const prefix = `event.${name}`;
-        this.nativeSpan.setAttribute(prefix, true);
-        if (attributesOrStartTime && !Array.isArray(attributesOrStartTime) && typeof attributesOrStartTime === "object") {
-            for (const [key, value] of Object.entries(attributesOrStartTime)) {
-                if (value !== undefined)
-                    this.setAttribute(`${prefix}.${key}`, value);
-            }
-        }
-        return this;
-    }
-    addLink(_link) { return this; }
-    addLinks(_links) { return this; }
-    /** True once `recordException` stamped a specific `error.type` (the exception class). */
-    errorTyped = false;
-    setStatus(status) {
-        if (status.code === SpanStatusCode.ERROR) {
-            // Don't clobber the more specific class name a preceding recordException set.
-            if (!this.errorTyped)
-                this.nativeSpan.setAttribute("error.type", "error");
-            if (status.message)
-                this.nativeSpan.setAttribute("error.message", status.message);
-        }
-        return this;
-    }
-    updateName(_name) { return this; }
-    end(_endTime) { }
-    isRecording() { return this.nativeSpan.isTraced; }
-    recordException(exception, _time) {
-        const error = exception instanceof Error ? exception : new Error(String(exception));
-        this.nativeSpan.setAttribute("error.type", error.name || "Error");
-        this.errorTyped = true;
-        this.nativeSpan.setAttribute("error.message", error.message);
-        if (error.stack)
-            this.nativeSpan.setAttribute("exception.stacktrace", error.stack);
-    }
-}
-function getNativeTracing(ctx) {
-    const candidate = ctx.tracing;
-    return candidate && typeof candidate.enterSpan === "function" ? candidate : undefined;
+function nativeInstrumentedEnv(env, tracing, config) {
+    if (!env || typeof env !== "object")
+        return env;
+    const explicit = config.instrumentBindings;
+    if (explicit === false)
+        return env;
+    return instrumentEnv(env, {
+        select: explicit ? explicit : true,
+        kindFilter: explicit ? undefined : (k) => shouldEnrichNatively(k, config.nativeEnrichment),
+        withSpan: (name, attrs, _kind, fn) => runNativeSpan(tracing, name, attrs, fn),
+        nativeNames: true,
+    });
 }
 function setNativeRequestAttributes(span, config, req) {
-    const url = new URL(req.url);
     span.setAttribute("service.name", config.service);
-    span.setAttribute("http.route", url.pathname);
+    // Labels the heystack.request child only; the fetch wrapper also sets the
+    // platform invocation span via `getActiveSpan()` when the runtime exposes it.
+    const route = resolveRoute(req, config);
+    if (route)
+        span.setAttribute("http.route", route);
     if (config.version)
         span.setAttribute("service.version", config.version);
     if (config.build)
@@ -985,26 +1008,6 @@ function setNativeRequestAttributes(span, config, req) {
     if (requestId)
         span.setAttribute("http.request.id", requestId);
 }
-async function runNativeSpan(nativeTracing, name, attrs, fn) {
-    ensureContextManager();
-    return nativeTracing.enterSpan(name, async (nativeSpan) => {
-        const adapter = new NativeSpanAdapter(nativeSpan);
-        for (const [key, value] of Object.entries(attrs)) {
-            if (value !== undefined)
-                adapter.setAttribute(key, value);
-        }
-        const nativeContext = trace.setSpan(context.active().setValue(NATIVE_TRACING_CONTEXT_KEY, nativeTracing), adapter);
-        try {
-            return await context.with(nativeContext, () => fn(adapter));
-        }
-        catch (error) {
-            const err = error instanceof Error ? error : new Error(String(error));
-            adapter.recordException(err);
-            adapter.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
-            throw error;
-        }
-    });
-}
 /**
  * Build a `BasicTracerProvider` wired to a `HeystackSpanExporter` via a
  * `SimpleSpanProcessor`. Exposed for advanced users who want to add manual
@@ -1022,10 +1025,18 @@ export function createTracerProvider(config) {
         // only when the caller supplied `version`/`build` (release attribution).
         resource: resourceFromAttributes({
             [ATTR_SERVICE_NAME]: config.service,
+            // Lets ingest recognise direct-mode Workers apps as Cloudflare (route
+            // templating, native-error and binding inference).
+            "cloud.provider": "cloudflare",
+            "cloud.platform": "cloudflare.workers",
+            // Marks direct-mode SDK spans so coverage never reports a wrapped Worker as native-only.
+            "heystack.sdk.mode": "direct",
             ...releaseResourceAttributes(config),
         }),
         spanProcessors: [new SimpleSpanProcessor(exporter)],
-        sampler: makeSampler(config.sampling),
+        sampler: makeSampler(config.sampling, {
+            trustRemoteParent: config.trustInboundSampling !== false,
+        }),
     });
     // Attach the exporter so flush paths can await its in-flight fetches.
     return Object.assign(provider, { heystackExporter: exporter });
@@ -1125,6 +1136,7 @@ function ensureContextManager() {
     const mgr = getALS() ? new AlsContextManager() : new SyncStackContextManager();
     context.setGlobalContextManager(mgr.enable());
 }
+setNativeContextInit(ensureContextManager);
 /** Reset the context-manager registration guard. Internal/testing helper. */
 export function __resetContextManager() {
     _contextManagerRegistered = false;
@@ -1157,7 +1169,8 @@ function ensureGlobalProvider(config) {
     // Patch globalThis.fetch (once) so outbound subrequests get CLIENT child spans
     // + `traceparent` injection (distributed tracing). The exporter's own POST uses
     // the captured original fetch, so it is never re-entered by this wrapper.
-    ensureFetchInstrumentation(_provider.heystackExporter.ingestHost, config.ai ?? {});
+    _fetchRedact = makeUrlRedactor(config);
+    ensureFetchInstrumentation(_provider.heystackExporter.ingestHost, config.ai ?? {}, config.propagateTargets);
     return _provider;
 }
 /**
@@ -1190,12 +1203,32 @@ export async function flushHeystack() {
     markManualFlushObserved();
     if (!_provider)
         return;
-    if (typeof _provider.forceFlush === "function") {
-        await _provider.forceFlush();
+    // Bounded by the same budget as the export drain so a stuck hash can't pin us.
+    let timer;
+    await Promise.race([
+        settlePendingKeyHashes(),
+        new Promise((resolve) => { timer = setTimeout(resolve, DRAIN_TIMEOUT_MS); }),
+    ]).finally(() => { if (timer)
+        clearTimeout(timer); });
+    // 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
@@ -1289,6 +1322,9 @@ export function instrument(handler, config) {
             build: config.build,
             waitUntil: config.waitUntil,
             sampling: config.sampling,
+            trustInboundSampling: config.trustInboundSampling,
+            redactQueryParams: config.redactQueryParams,
+            captureClientIp: config.captureClientIp,
             ai: config.ai,
         });
         // instrument() wires a per-request drain (see `drain` below), so exports on
@@ -1296,6 +1332,9 @@ export function instrument(handler, config) {
         requestDrainWired = true;
         return { provider, tracer: trace.getTracer("heystack") };
     };
+    // Privacy: one redactor per instrument() call for the inbound SERVER span URL.
+    const redactInboundUrl = makeUrlRedactor(config);
+    const captureGeo = config.captureGeo ?? "country";
     // Drain BOTH the provider's span processor AND the exporter's in-flight fetch
     // via ctx.waitUntil, raced against an ~8s timeout (see drainWithTimeout, #25).
     const drain = (provider, ctx) => {
@@ -1307,7 +1346,7 @@ export function instrument(handler, config) {
     const originalFetch = handler.fetch?.bind(handler);
     if (originalFetch) {
         wrapped.fetch = async (req, env, ctx) => {
-            const nativeTracing = config.nativeTracing === "direct" ? undefined : getNativeTracing(ctx);
+            const nativeTracing = config.nativeTracing === "direct" ? null : getNativeTracing(ctx, config.tracing);
             if (nativeTracing) {
                 // `withSpan()` discovers the request's native tracer through OTel
                 // context. Register our WinterCG-safe manager even though native mode
@@ -1316,14 +1355,25 @@ export function instrument(handler, config) {
                 // Install the (LLM-only under native) fetch wrapper so outbound calls
                 // to LLM providers/gateways still get gen_ai.* enrichment — native mode
                 // never runs `setup()`, which is where the direct plane installs it.
-                ensureFetchInstrumentation("", config.ai ?? {});
+                ensureFetchInstrumentation(nativeIngestHost(config), config.ai ?? {}, config.propagateTargets);
+                // The platform's invocation (root fetch) span is what Service Health/RED
+                // read. When the runtime exposes it, put the route template there too;
+                // otherwise `routes` labels only the `heystack.request` child.
+                try {
+                    const rootRoute = resolveRoute(req, config);
+                    if (rootRoute)
+                        nativeTracing.getActiveSpan?.()?.setAttribute("http.route", rootRoute);
+                }
+                catch { /* telemetry must never surface */ }
                 return runNativeSpan(nativeTracing, "heystack.request", {}, async (adapter) => {
                     setNativeRequestAttributes(adapter, config, req);
-                    const response = await originalFetch(req, env, ctx);
-                    adapter.setAttribute("http.response.status_code", response.status);
-                    if (response.status >= 500)
-                        adapter.setAttribute("error.type", "http_error");
-                    return response;
+                    return withNativePropagation(adapter, req.headers.get("traceparent"), async () => {
+                        const response = await originalFetch(req, nativeInstrumentedEnv(env, nativeTracing, config), ctx);
+                        adapter.setAttribute("http.response.status_code", response.status);
+                        if (response.status >= 500)
+                            adapter.setAttribute("error.type", "http_error");
+                        return response;
+                    });
                 });
             }
             const s = setup(env);
@@ -1362,12 +1412,16 @@ export function instrument(handler, config) {
                 kind: SpanKind.SERVER,
                 attributes: {
                     "http.request.method": req.method,
-                    "url.full": req.url,
+                    "url.full": redactInboundUrl(req.url),
                     "url.path": url.pathname,
                     "server.address": url.host,
+                    "cloudflare.handler_type": "fetch",
                 },
             }, startCtx);
-            // A1 enrichment: identity, request id, client ip, geo.
+            const directRoute = resolveRoute(req, config);
+            if (directRoute)
+                span.setAttribute("http.route", directRoute);
+            // A1 enrichment: identity, request id, (opt-in) client ip, geo.
             // All attributes are set only when non-empty to keep spans lean.
             const userInfo = config.getUser?.(req);
             if (userInfo?.id)
@@ -1377,20 +1431,26 @@ export function instrument(handler, config) {
             const reqId = userInfo?.requestId ?? req.headers.get("cf-ray") ?? "";
             if (reqId)
                 span.setAttribute("http.request.id", reqId);
-            const clientIp = req.headers.get("CF-Connecting-IP") ?? "";
-            if (clientIp)
-                span.setAttribute("client.address", clientIp);
+            // End-user IP is personal data: recorded only with `captureClientIp: true`.
+            if (config.captureClientIp === true) {
+                const clientIp = req.headers.get("CF-Connecting-IP") ?? "";
+                if (clientIp)
+                    span.setAttribute("client.address", clientIp);
+            }
             // Cloudflare geo — only present on the real CF runtime; read defensively.
+            // Default is country-only; region/city/ASN need `captureGeo: "full"`.
             const cf = req.cf;
-            if (cf) {
+            if (cf && captureGeo) {
                 if (typeof cf.country === "string" && cf.country)
                     span.setAttribute("geo.country", cf.country);
-                if (typeof cf.region === "string" && cf.region)
-                    span.setAttribute("geo.region", cf.region);
-                if (typeof cf.city === "string" && cf.city)
-                    span.setAttribute("geo.city", cf.city);
-                if (cf.asn != null)
-                    span.setAttribute("geo.asn", String(cf.asn));
+                if (captureGeo === "full") {
+                    if (typeof cf.region === "string" && cf.region)
+                        span.setAttribute("geo.region", cf.region);
+                    if (typeof cf.city === "string" && cf.city)
+                        span.setAttribute("geo.city", cf.city);
+                    if (cf.asn != null)
+                        span.setAttribute("geo.asn", String(cf.asn));
+                }
             }
             // FR5: response header carrying THIS span's trace + span id.
             const sc = span.spanContext();
@@ -1558,19 +1618,21 @@ export function instrument(handler, config) {
     const originalQueue = handler.queue?.bind(handler);
     if (originalQueue) {
         wrapped.queue = async (batch, env, ctx) => {
-            const nativeTracing = config.nativeTracing === "direct" ? undefined : getNativeTracing(ctx);
+            const nativeTracing = config.nativeTracing === "direct" ? null : getNativeTracing(ctx, config.tracing);
             if (nativeTracing) {
-                ensureFetchInstrumentation("", config.ai ?? {});
+                ensureFetchInstrumentation(nativeIngestHost(config), config.ai ?? {}, config.propagateTargets);
                 // Native mode: Cloudflare owns queue spans — pass the ORIGINAL batch
                 // through untouched so platform objects keep their identity.
                 return runNativeSpan(nativeTracing, `heystack.queue ${batch.queue}`, {
                     "service.name": config.service,
                     "messaging.batch.message_count": batch.messages.length,
+                    "cloudflare.queue.batch_size": batch.messages.length,
+                    "cloudflare.handler_type": "queue",
                     "messaging.destination.name": batch.queue,
                     "messaging.operation.type": "process",
                     "service.version": config.version,
                     "service.build": config.build,
-                }, () => originalQueue(batch, env, ctx));
+                }, (adapter) => withNativePropagation(adapter, null, () => originalQueue(batch, nativeInstrumentedEnv(env, nativeTracing, config), ctx)));
             }
             const s = setup(env);
             if (!s)
@@ -1580,7 +1642,9 @@ export function instrument(handler, config) {
                 kind: SpanKind.CONSUMER,
                 attributes: {
                     "messaging.batch.message_count": batch.messages.length,
+                    "cloudflare.queue.batch_size": batch.messages.length,
                     "messaging.destination.name": batch.queue,
+                    "cloudflare.handler_type": "queue",
                 },
             });
             // The request's CONSUMER context, captured per-batch as an explicit parent
@@ -1620,16 +1684,18 @@ export function instrument(handler, config) {
     const originalScheduled = handler.scheduled?.bind(handler);
     if (originalScheduled) {
         wrapped.scheduled = async (controller, env, ctx) => {
-            const nativeTracing = config.nativeTracing === "direct" ? undefined : getNativeTracing(ctx);
+            const nativeTracing = config.nativeTracing === "direct" ? null : getNativeTracing(ctx, config.tracing);
             if (nativeTracing) {
-                ensureFetchInstrumentation("", config.ai ?? {});
+                ensureFetchInstrumentation(nativeIngestHost(config), config.ai ?? {}, config.propagateTargets);
                 return runNativeSpan(nativeTracing, `heystack.scheduled ${controller.cron}`, {
                     "service.name": config.service,
                     "faas.trigger": "timer",
                     "cloudflare.scheduled.cron": controller.cron,
+                    "faas.cron": controller.cron,
+                    "cloudflare.handler_type": "scheduled",
                     "service.version": config.version,
                     "service.build": config.build,
-                }, () => originalScheduled(controller, env, ctx));
+                }, (adapter) => withNativePropagation(adapter, null, () => originalScheduled(controller, nativeInstrumentedEnv(env, nativeTracing, config), ctx)));
             }
             const s = setup(env);
             if (!s)
@@ -1639,6 +1705,8 @@ export function instrument(handler, config) {
                 kind: SpanKind.INTERNAL,
                 attributes: {
                     "controller.cron": controller.cron,
+                    "faas.cron": controller.cron,
+                    "cloudflare.handler_type": "scheduled",
                 },
             });
             try {
@@ -1662,7 +1730,7 @@ export function instrument(handler, config) {
     const originalEmail = handler.email?.bind(handler);
     if (originalEmail) {
         wrapped.email = async (message, env, ctx) => {
-            const nativeTracing = config.nativeTracing === "direct" ? undefined : getNativeTracing(ctx);
+            const nativeTracing = config.nativeTracing === "direct" ? null : getNativeTracing(ctx, config.tracing);
             // PRIVACY: only from/to DOMAINS + envelope size are recorded — never the
             // full addresses and never any message content.
             const { name: emailSpanName, attrs: emailAttrs } = emailHandlerAttrs(message);
@@ -1672,7 +1740,7 @@ export function instrument(handler, config) {
                     ...emailAttrs,
                     "service.version": config.version,
                     "service.build": config.build,
-                }, () => originalEmail(message, env, ctx));
+                }, (adapter) => withNativePropagation(adapter, null, () => originalEmail(message, nativeInstrumentedEnv(env, nativeTracing, config), ctx)));
             }
             const s = setup(env);
             if (!s)
@@ -1680,7 +1748,7 @@ export function instrument(handler, config) {
             const { provider, tracer } = s;
             const span = tracer.startSpan(emailSpanName, {
                 kind: SpanKind.SERVER,
-                attributes: emailAttrs,
+                attributes: { ...emailAttrs, "cloudflare.handler_type": "email" },
             });
             try {
                 await context.with(trace.setSpan(context.active(), span), () => originalEmail(message, env, wrapExecutionContextWithProvider(ctx, provider)));
@@ -1703,7 +1771,7 @@ export function instrument(handler, config) {
     const originalTail = handler.tail?.bind(handler);
     if (originalTail) {
         wrapped.tail = async (events, env, ctx) => {
-            const nativeTracing = config.nativeTracing === "direct" ? undefined : getNativeTracing(ctx);
+            const nativeTracing = config.nativeTracing === "direct" ? null : getNativeTracing(ctx, config.tracing);
             // PRIVACY: only the event COUNT is recorded — tail payloads can contain
             // request URLs, headers and console output; none of it is captured.
             const count = Array.isArray(events) ? events.length : 0;
@@ -1722,7 +1790,7 @@ export function instrument(handler, config) {
             const { provider, tracer } = s;
             const span = tracer.startSpan("tail", {
                 kind: SpanKind.INTERNAL,
-                attributes: attrs,
+                attributes: { ...attrs, "cloudflare.handler_type": "tail" },
             });
             try {
                 await context.with(trace.setSpan(context.active(), span), () => originalTail(events, env, wrapExecutionContextWithProvider(ctx, provider)));
@@ -1862,7 +1930,18 @@ function classStartSpan(opts) {
  * to the invocation's DurableObjectState `waitUntil`. Best-effort no-op when no
  * state/waitUntil is available (e.g. unit tests).
  */
-function scheduleStateFlush(state) {
+function scheduleStateFlush(state, invocation) {
+    // SQL cursors the app never finished iterating: close THIS invocation's spans
+    // (without row counts); concurrent invocations on the same DO keep theirs.
+    if (state && typeof state === "object") {
+        const pending = pendingSqlSpans.get(state);
+        if (pending) {
+            for (const p of [...pending]) {
+                if (invocation === undefined || p.owner === undefined || p.owner === invocation)
+                    p.abandon();
+            }
+        }
+    }
     const waitUntil = state
         ?.waitUntil;
     if (typeof waitUntil !== "function")
@@ -1874,8 +1953,152 @@ function scheduleStateFlush(state) {
         // A failing waitUntil must never break the wrapped handler.
     }
 }
-/** INTERNAL child spans for DurableObjectStorage get/put/delete/list ops. */
-function wrapDurableObjectStorage(storage, startSpan) {
+/** Marks the DO handler invocation in context; nested spans inherit it. */
+const DO_INVOCATION_KEY = createContextKey("heystack.do.invocation");
+/** Open `sql.exec` spans per raw DurableObjectState, closed when the invocation ends. */
+const pendingSqlSpans = new WeakMap();
+/**
+ * `ctx.storage.sql.exec()` → `durable_object_storage_exec`. The cursor is lazy and
+ * owned by the app: we never step it. The span ends (with rows read/written) when
+ * the app completes it via `toArray()`, `one()` or iterator exhaustion, and is
+ * closed without counts if the invocation ends first.
+ */
+function wrapDurableObjectSql(sql, startSpan, doId, pending) {
+    return new Proxy(sql, {
+        get(t, prop) {
+            const val = Reflect.get(t, prop, t);
+            if (typeof val !== "function")
+                return val;
+            if (prop !== "exec")
+                return val.bind(t);
+            return (query, ...bindings) => {
+                if (isTracingSuppressed(context.active()))
+                    return val.call(t, query, ...bindings);
+                const attrs = {};
+                if (typeof query === "string")
+                    attrs["db.query.text"] = query;
+                if (doId)
+                    attrs["cloudflare.durable_object.id"] = doId;
+                const span = startSpan("durable_object_storage_exec", attrs, SpanKind.INTERNAL);
+                let cursor;
+                try {
+                    cursor = val.call(t, query, ...bindings);
+                }
+                catch (error) {
+                    span.recordException(error instanceof Error ? error : new Error(String(error)));
+                    span.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: error instanceof Error ? error.message : String(error),
+                    });
+                    span.end();
+                    throw error;
+                }
+                if (!cursor || typeof cursor !== "object") {
+                    span.end();
+                    return cursor;
+                }
+                let done = false;
+                let lastActivity = Date.now();
+                const owner = context.active().getValue(DO_INVOCATION_KEY);
+                const finish = (counts, error) => {
+                    if (done)
+                        return;
+                    done = true;
+                    pending.delete(entry);
+                    try {
+                        if (error !== undefined) {
+                            span.recordException(error instanceof Error ? error : new Error(String(error)));
+                            span.setStatus({
+                                code: SpanStatusCode.ERROR,
+                                message: error instanceof Error ? error.message : String(error),
+                            });
+                        }
+                        if (counts) {
+                            // Side-effect-free getters: reading them never steps the cursor.
+                            if (typeof cursor.rowsRead === "number") {
+                                span.setAttribute("cloudflare.durable_object.response.rows_read", cursor.rowsRead);
+                            }
+                            if (typeof cursor.rowsWritten === "number") {
+                                span.setAttribute("cloudflare.durable_object.response.rows_written", cursor.rowsWritten);
+                            }
+                            span.end();
+                        }
+                        else {
+                            // Abandoned: the work effectively ended at the last observed activity.
+                            span.end(lastActivity);
+                        }
+                    }
+                    catch {
+                        // Telemetry must never alter the cursor's behaviour.
+                    }
+                };
+                const entry = { owner, abandon: () => finish(false) };
+                pending.add(entry);
+                // A statement with no result columns (INSERT/UPDATE/DDL) has fully run
+                // by the time exec() returns; nothing will ever be iterated.
+                if (Array.isArray(cursor.columnNames) && cursor.columnNames.length === 0) {
+                    finish(true);
+                    return cursor;
+                }
+                const step = (fn, c, a) => {
+                    let r;
+                    try {
+                        r = fn.apply(c, a);
+                    }
+                    catch (error) {
+                        finish(false, error);
+                        throw error;
+                    }
+                    lastActivity = Date.now();
+                    if (r && r.done === true)
+                        finish(true);
+                    return r;
+                };
+                // One observer for the cursor and for raw() iterators: completion is
+                // toArray()/one()/iterator exhaustion; nothing is ever stepped by us.
+                const observe = (target) => {
+                    if (!target || typeof target !== "object")
+                        return target;
+                    const proxy = new Proxy(target, {
+                        get(c, p) {
+                            const v = Reflect.get(c, p, c);
+                            if (typeof v !== "function")
+                                return v;
+                            if (p === "toArray" || p === "one") {
+                                return (...a) => {
+                                    try {
+                                        const r = v.apply(c, a);
+                                        finish(true);
+                                        return r;
+                                    }
+                                    catch (error) {
+                                        finish(false, error);
+                                        throw error;
+                                    }
+                                };
+                            }
+                            if (p === "next")
+                                return (...a) => step(v, c, a);
+                            if (p === Symbol.iterator) {
+                                return () => {
+                                    const it = v.call(c);
+                                    return it === c ? proxy : observe(it);
+                                };
+                            }
+                            if (p === "raw")
+                                return (...a) => observe(v.apply(c, a));
+                            return v.bind(c);
+                        },
+                    });
+                    return proxy;
+                };
+                return observe(cursor);
+            };
+        },
+    });
+}
+/** INTERNAL child spans for DurableObjectStorage get/put/delete/list, alarms and SQL. */
+function wrapDurableObjectStorage(storage, startSpan, doId, pending = new Set()) {
     const wrapOp = (op) => async (...args) => {
         const underlying = storage[op];
         if (typeof underlying !== "function")
@@ -1884,11 +2107,10 @@ function wrapDurableObjectStorage(storage, startSpan) {
             return underlying.apply(storage, args);
         }
         const attrs = {};
+        if (doId)
+            attrs["cloudflare.durable_object.id"] = doId;
         const first = args[0];
-        if (typeof first === "string") {
-            attrs["cloudflare.do.storage.key"] = first;
-        }
-        else if (Array.isArray(first)) {
+        if (Array.isArray(first)) {
             attrs["cloudflare.do.storage.key_count"] = first.length;
         }
         else if (op === "list" &&
@@ -1898,8 +2120,17 @@ function wrapDurableObjectStorage(storage, startSpan) {
             attrs["cloudflare.do.storage.limit"] = first.limit;
         }
         const span = startSpan(`DO storage ${op}`, attrs, SpanKind.INTERNAL);
+        // Keys are user data: only the hash is ever emitted (omitted if hashing fails).
+        return runWithSpanKeyed(span, "cloudflare.do.storage.key", keysOf(first), () => Promise.resolve(underlying.apply(storage, args)));
+    };
+    const wrapAlarm = (op) => async (...args) => {
+        const underlying = storage[op];
+        if (isTracingSuppressed(context.active()))
+            return underlying.apply(storage, args);
+        const span = startSpan(`durable_object_alarms_${op}`, doId ? { "cloudflare.durable_object.id": doId } : {}, SpanKind.INTERNAL);
         return runWithSpan(span, () => Promise.resolve(underlying.apply(storage, args)));
     };
+    let tracedSql;
     // A dedicated proxy (not makeProxy) because `storage` is a VALUE property on
     // the state object, not a method — handlers there must be getters.
     return new Proxy(storage, {
@@ -1908,10 +2139,46 @@ function wrapDurableObjectStorage(storage, startSpan) {
             if ((prop === "get" || prop === "put" || prop === "delete" || prop === "list") && typeof val === "function") {
                 return wrapOp(prop);
             }
+            if ((prop === "getAlarm" || prop === "setAlarm" || prop === "deleteAlarm") &&
+                typeof val === "function") {
+                return wrapAlarm(prop);
+            }
+            if (prop === "sql" && val && typeof val === "object") {
+                return (tracedSql ??= wrapDurableObjectSql(val, startSpan, doId, pending));
+            }
             return typeof val === "function" ? val.bind(t) : val;
         },
     });
 }
+/** The DO id string from a raw DurableObjectState; undefined when unavailable. */
+function durableObjectIdOf(state) {
+    try {
+        const raw = state?.id?.toString?.();
+        return typeof raw === "string" && raw ? raw : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+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")
@@ -1919,7 +2186,18 @@ function wrapDurableObjectState(state, startSpan) {
     const s = state;
     if (!s.storage || typeof s.storage !== "object")
         return state;
-    const tracedStorage = wrapDurableObjectStorage(s.storage, startSpan);
+    let doId;
+    try {
+        const raw = s.id?.toString?.();
+        if (typeof raw === "string" && raw)
+            doId = raw;
+    }
+    catch {
+        // An id without a usable toString() just omits the attribute.
+    }
+    const pending = new Set();
+    pendingSqlSpans.set(s, pending);
+    const tracedStorage = wrapDurableObjectStorage(s.storage, startSpan, doId, pending);
     return new Proxy(s, {
         get(t, prop, _receiver) {
             if (prop === "storage")
@@ -1931,6 +2209,10 @@ function wrapDurableObjectState(state, startSpan) {
 }
 /** Prototype methods that are wrapped specially (never treated as RPC). */
 const DO_LIFECYCLE_METHODS = new Set(["fetch", "alarm", "constructor"]);
+/** WebSocket hibernation handlers: wrapped as named lifecycle spans, never as RPC. */
+const DO_WEBSOCKET_METHODS = ["webSocketMessage", "webSocketClose", "webSocketError"];
+for (const m of DO_WEBSOCKET_METHODS)
+    DO_LIFECYCLE_METHODS.add(m);
 const MAX_DO_RPC_METHODS = 32;
 /**
  * Decorate a Durable Object class:
@@ -1976,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") {
@@ -2011,9 +2316,11 @@ export function wrapDurableObjectClass(cls, opts = {}) {
                 "http.request.method": request.method,
                 "url.path": url.pathname,
                 "server.address": url.host,
+                "cloudflare.handler_type": "fetch",
+                ...doIdAttrs(this.__heystackState),
             }, SpanKind.SERVER, startCtx);
             try {
-                const response = (await context.with(trace.setSpan(startCtx, span), () => origFetch.call(this, request)));
+                const response = (await context.with(trace.setSpan(startCtx, span).setValue(DO_INVOCATION_KEY, span), () => origFetch.call(this, request)));
                 span.setAttribute("http.response.status_code", response.status);
                 span.setStatus({
                     code: response.status >= 500 ? SpanStatusCode.ERROR : SpanStatusCode.UNSET,
@@ -2030,7 +2337,7 @@ export function wrapDurableObjectClass(cls, opts = {}) {
             }
             finally {
                 span.end();
-                scheduleStateFlush(this.__heystackState);
+                scheduleStateFlush(this.__heystackState, span);
             }
         };
     }
@@ -2039,9 +2346,9 @@ export function wrapDurableObjectClass(cls, opts = {}) {
             if (isTracingSuppressed(context.active())) {
                 return origAlarm.apply(this, args);
             }
-            const span = startSpan("DO alarm", {}, SpanKind.INTERNAL);
+            const span = startSpan("DO alarm", { "cloudflare.handler_type": "alarm", ...doIdAttrs(this.__heystackState) }, SpanKind.INTERNAL);
             try {
-                return await context.with(trace.setSpan(context.active(), span), () => origAlarm.apply(this, args));
+                return await context.with(trace.setSpan(context.active(), span).setValue(DO_INVOCATION_KEY, span), () => origAlarm.apply(this, args));
             }
             catch (error) {
                 span.recordException(error instanceof Error ? error : new Error(String(error)));
@@ -2053,22 +2360,20 @@ export function wrapDurableObjectClass(cls, opts = {}) {
             }
             finally {
                 span.end();
-                scheduleStateFlush(this.__heystackState);
+                scheduleStateFlush(this.__heystackState, span);
             }
         };
     }
-    for (const method of rpcMethods) {
+    const className = Base.name || "DurableObject";
+    const wrapMethod = (method, spanName, attrs) => {
         const orig = proto[method];
         Wrapped.prototype[method] = async function (...args) {
             if (isTracingSuppressed(context.active())) {
                 return orig.apply(this, args);
             }
-            const span = startSpan(`DO rpc ${method}`, {
-                "rpc.system": "cloudflare.durable_object",
-                "rpc.method": method,
-            }, SpanKind.SERVER);
+            const span = startSpan(spanName, { ...attrs, ...doIdAttrs(this.__heystackState) }, SpanKind.SERVER);
             try {
-                return await context.with(trace.setSpan(context.active(), span), () => orig.apply(this, args));
+                return await context.with(trace.setSpan(context.active(), span).setValue(DO_INVOCATION_KEY, span), () => orig.apply(this, args));
             }
             catch (error) {
                 span.recordException(error instanceof Error ? error : new Error(String(error)));
@@ -2080,9 +2385,21 @@ export function wrapDurableObjectClass(cls, opts = {}) {
             }
             finally {
                 span.end();
-                scheduleStateFlush(this.__heystackState);
+                scheduleStateFlush(this.__heystackState, span);
             }
         };
+    };
+    for (const method of DO_WEBSOCKET_METHODS) {
+        if (typeof proto[method] === "function") {
+            wrapMethod(method, `DO ${className} ${method}`, { "cloudflare.handler_type": method });
+        }
+    }
+    for (const method of rpcMethods) {
+        wrapMethod(method, `DO rpc ${method}`, {
+            "rpc.system": "cloudflare.durable_object",
+            "rpc.method": method,
+            "cloudflare.handler_type": "rpc",
+        });
     }
     return Wrapped;
 }
@@ -2225,7 +2542,7 @@ export function wrapWorkflowEntrypointClass(cls, opts = {}) {
             return origRun.call(this, event, step, ...rest);
         }
         const attrs = workflowRunAttrs(event);
-        const span = startSpan("workflow run", attrs, SpanKind.INTERNAL);
+        const span = startSpan("workflow run", { ...attrs, "cloudflare.handler_type": "workflow" }, SpanKind.INTERNAL);
         try {
             return await context.with(trace.setSpan(context.active(), span), () => origRun.call(this, event, step && typeof step === "object"
                 ? wrapWorkflowStep(step, startSpan, this.__heystackState)
@@ -2246,25 +2563,155 @@ export function wrapWorkflowEntrypointClass(cls, opts = {}) {
     };
     return Wrapped;
 }
+// ---------------------------------------------------------------------------
+// WorkerEntrypoint CLASS instrumentation
+// ---------------------------------------------------------------------------
+/** Handler names and RpcTarget plumbing that are never treated as RPC methods. */
+const ENTRYPOINT_NON_RPC = new Set([
+    "constructor",
+    "fetch",
+    "tail",
+    "trace",
+    "scheduled",
+    "queue",
+    "email",
+    "test",
+    "then",
+    "toJSON",
+    "connect",
+    "tailStream",
+]);
+const ENTRYPOINT_BASES = new Set(["WorkerEntrypoint", "RpcTarget", "DurableObject"]);
+const MAX_ENTRYPOINT_RPC_METHODS = 64;
+/**
+ * Decorate a `WorkerEntrypoint` class (the target of a Service binding):
+ * - `fetch()` is traced exactly like an `instrument()`ed handler (SERVER span,
+ *   inbound `traceparent` continued, export drained via `ctx.waitUntil`).
+ * - every public RPC method gets a SERVER span `rpc <method>` with
+ *   `jsrpc.method` / `rpc.method`. Return values (including stubs, RpcTargets
+ *   and custom thenables), `this` and errors pass through untouched.
+ *
+ * RPC spans exist in DIRECT mode only. When Cloudflare native tracing is active
+ * it already emits `jsrpc` spans, so RPC calls pass straight through and `fetch`
+ * takes `instrument()`'s native path. Constructor, `#private`, `_underscore` and
+ * Symbol-keyed members are never wrapped.
+ *
+ *   export default wrapWorkerEntrypointClass(class Api extends WorkerEntrypoint { ... }, { service: "api" });
+ */
+export function wrapWorkerEntrypointClass(cls, cfg) {
+    const Base = cls;
+    const proto = Base.prototype;
+    const instances = new WeakMap();
+    // Enumerate public RPC methods without invoking any getter.
+    const rpcMethods = [];
+    try {
+        let p = Base.prototype;
+        for (let depth = 0; depth < 6 && p && p !== Object.prototype; depth++) {
+            const ctorName = p.constructor?.name;
+            if (depth > 0 && ctorName && ENTRYPOINT_BASES.has(ctorName))
+                break;
+            for (const key of Object.getOwnPropertyNames(p)) {
+                if (ENTRYPOINT_NON_RPC.has(key) || key.startsWith("_") || key.startsWith("#"))
+                    continue;
+                if (rpcMethods.includes(key) || rpcMethods.length >= MAX_ENTRYPOINT_RPC_METHODS)
+                    continue;
+                if (typeof Object.getOwnPropertyDescriptor(p, key)?.value === "function")
+                    rpcMethods.push(key);
+            }
+            p = Object.getPrototypeOf(p);
+        }
+    }
+    catch {
+        // Best-effort enumeration — a hostile prototype must never break decoration.
+    }
+    class Wrapped extends Base {
+        constructor(...args) {
+            // The entrypoint's own `this.env` bindings get traced too, parented to
+            // whichever RPC/fetch span is active when they are used.
+            const env = args[1];
+            const rawEnv = env;
+            if (cfg.instrumentBindings !== false && env && typeof env === "object") {
+                const native = cfg.nativeTracing === "direct" ? null : getNativeTracing(args[0], cfg.tracing);
+                if (native) {
+                    args[1] = nativeInstrumentedEnv(env, native, cfg);
+                }
+                else if (cfg.instrumentBindings) {
+                    args[1] = instrumentEnv(env, {
+                        startSpan: (name, attrs, kind) => trace.getTracer("heystack").startSpan(name, { attributes: attrs, kind }, context.active()),
+                        select: cfg.instrumentBindings,
+                    });
+                }
+            }
+            super(...args);
+            instances.set(this, { ctx: args[0], env: args[1], rawEnv });
+        }
+    }
+    try {
+        Object.defineProperty(Wrapped, "name", { value: Base.name, configurable: true });
+    }
+    catch {
+        // Non-configurable name: harmless.
+    }
+    const origFetch = proto.fetch;
+    if (typeof origFetch === "function") {
+        // Built once per instance (WorkerEntrypoint.fetch takes only the request).
+        const handlers = new WeakMap();
+        Wrapped.prototype.fetch = function (request) {
+            const inst = instances.get(this);
+            let handler = handlers.get(this);
+            if (!handler) {
+                handler = instrument({ fetch: (req) => origFetch.call(this, req) }, cfg);
+                handlers.set(this, handler);
+            }
+            return handler.fetch(request, inst?.rawEnv ?? this.env, inst?.ctx ?? this.ctx);
+        };
+    }
+    for (const method of rpcMethods) {
+        const orig = proto[method];
+        Wrapped.prototype[method] = function (...args) {
+            if (isTracingSuppressed(context.active()))
+                return orig.apply(this, args);
+            const inst = instances.get(this) ?? {
+                ctx: this.ctx,
+                env: this.env,
+            };
+            // Native tracing owns jsrpc spans: pass straight through.
+            if (cfg.nativeTracing !== "direct" && getNativeTracing(inst.ctx, cfg.tracing)) {
+                return orig.apply(this, args);
+            }
+            const apiKey = cfg.apiKey ?? inst.env?.HEYSTACK_API_KEY;
+            if (!apiKey) {
+                warnOnceNoKey();
+                return orig.apply(this, args);
+            }
+            const provider = ensureGlobalProvider({ ...cfg, apiKey });
+            requestDrainWired = true;
+            const span = trace.getTracer("heystack").startSpan(`rpc ${method}`, { kind: SpanKind.SERVER, attributes: { "jsrpc.method": method, "rpc.method": method, "cloudflare.handler_type": "rpc" } }, context.active());
+            // Only the three members the shared tracer helper uses; `end` also drains.
+            const tracked = {
+                recordException: (e) => span.recordException(e),
+                setStatus: (st) => span.setStatus(st),
+                end: () => {
+                    span.end();
+                    try {
+                        inst.ctx?.waitUntil?.(drainWithTimeout(provider));
+                    }
+                    catch {
+                        // A rejected host waitUntil must not break the RPC call.
+                    }
+                },
+            };
+            return runWithSpanPreservingReturn(tracked, () => context.with(trace.setSpan(context.active(), span), () => orig.apply(this, args)));
+        };
+    }
+    return Wrapped;
+}
 export async function withSpan(name, attrsOrFn, maybeFn) {
     const attrs = typeof attrsOrFn === "function" ? undefined : attrsOrFn;
     const fn = (typeof attrsOrFn === "function" ? attrsOrFn : maybeFn);
     const nativeTracing = nativeTracingFromContext();
     if (nativeTracing) {
-        return nativeTracing.enterSpan(name, async (nativeSpan) => {
-            const adapter = new NativeSpanAdapter(nativeSpan);
-            if (attrs)
-                adapter.setAttributes(attrs);
-            const nativeContext = trace.setSpan(context.active().setValue(NATIVE_TRACING_CONTEXT_KEY, nativeTracing), adapter);
-            try {
-                return await context.with(nativeContext, () => fn(adapter));
-            }
-            catch (err) {
-                adapter.recordException(err instanceof Error ? err : new Error(String(err)));
-                adapter.setStatus({ code: SpanStatusCode.ERROR, message: err instanceof Error ? err.message : String(err) });
-                throw err;
-            }
-        });
+        return runNativeSpan(nativeTracing, name, attrs ?? {}, fn);
     }
     const tracer = trace.getTracer("heystack");
     const span = tracer.startSpan(name, attrs ? { attributes: attrs } : undefined);
@@ -2313,3 +2760,5 @@ export { llmRequestAttrs as genAiRequestAttrs } from "./llm-enrich.js";
  * Workers AI results (`usage.prompt_tokens`/`completion_tokens`) included.
  */
 export { llmResponseAttrs as genAiResponseAttrs } from "./llm-enrich.js";
+export { NATIVELY_COVERED, NATIVE_PROPAGATES_EXTERNAL, shouldEnrichNatively, wrapSqlClient };
+export { matchRoute } from "./workers-routes.js";