@heystack/otel 0.18.0 → 0.19.0

package/dist/workers-bindings.js

@@ -7,9 +7,11 @@
 // 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 { context, INVALID_SPAN_CONTEXT, isSpanContextValid, SpanKind, SpanStatusCode, trace } from "@opentelemetry/api";
 import { isTracingSuppressed } from "@opentelemetry/core";
+import { scrubKeysAsync } from "./hash.js";
 import { makeTraceparent } from "./traceparent.js";
+import { nativeTracingFromContext, runNativeSpan } from "./workers-native.js";
 // ---------------------------------------------------------------------------
 // Duck-type detectors — conservative; require the distinctive method set
 // exactly as documented in the task brief.
@@ -61,6 +63,66 @@ function isAnalyticsEngineLike(b) {
 function isServiceLike(b) {
     return typeof b?.fetch === "function";
 }
+/**
+ * Adapt a callback-scoped `withSpan` to the immediate-return `startSpan` shape
+ * the legacy wrappers use. The callback stays open (pending promise) until the
+ * wrapper calls `end()`; calls made before the callback has run are buffered.
+ */
+function startSpanFromWithSpan(withSpan) {
+    return (name, attrs, kind) => {
+        let real;
+        const queue = [];
+        let release = () => undefined;
+        const done = new Promise((resolve) => { release = resolve; });
+        let ended = false;
+        const apply = (f) => {
+            if (real)
+                f(real);
+            else
+                queue.push(f);
+        };
+        void withSpan(name, attrs, kind, (s) => {
+            real = s;
+            for (const f of queue.splice(0))
+                f(s);
+            return done;
+        }).catch(() => undefined);
+        const deferred = {
+            spanContext: () => real?.spanContext() ?? INVALID_SPAN_CONTEXT,
+            setAttribute(k, v) { apply((s) => s.setAttribute(k, v)); return deferred; },
+            setAttributes(a) { apply((s) => s.setAttributes(a)); return deferred; },
+            addEvent(n, a) { apply((s) => s.addEvent(n, a)); return deferred; },
+            addLink() { return deferred; },
+            addLinks() { return deferred; },
+            setStatus(st) { apply((s) => s.setStatus(st)); return deferred; },
+            updateName() { return deferred; },
+            end() {
+                if (ended)
+                    return;
+                ended = true;
+                apply((s) => s.end());
+                release();
+            },
+            isRecording: () => real?.isRecording() ?? true,
+            recordException(e) { apply((s) => s.recordException(e)); },
+        };
+        return deferred;
+    };
+}
+/**
+ * Run an async operation inside a span: `withSpan` when native, else
+ * `startSpan` + {@link runWithSpan}.
+ */
+function traced(opts, name, attrs, kind, fn) {
+    if (opts.withSpan)
+        return opts.withSpan(name, attrs, kind, fn);
+    const span = opts.startSpan(name, attrs, kind);
+    return runWithSpan(span, () => fn(span));
+}
+/** Native name when `opts.nativeNames`, else the direct-mode name. */
+function nm(opts, direct, native) {
+    return opts.nativeNames ? native : direct;
+}
 // ---------------------------------------------------------------------------
 // Span lifecycle helper
 // ---------------------------------------------------------------------------
@@ -85,6 +147,68 @@ export async function runWithSpan(span, fn) {
         span.end();
     }
 }
+/** Plain string keys from a string / string[] argument (anything else yields none). */
+export function keysOf(value) {
+    if (typeof value === "string")
+        return [value];
+    if (Array.isArray(value))
+        return value.filter((v) => typeof v === "string");
+    return [];
+}
+/** At most this many keys of a multi-key call are hashed and recorded. */
+const MAX_HASHED_KEYS = 10;
+/** Key hashes still in flight; exports drain these first so no span is flushed half-built. */
+const pendingKeyHashes = new Set();
+/** Resolves once every in-flight key hash has attached its attribute and ended its span. */
+export async function settlePendingKeyHashes() {
+    while (pendingKeyHashes.size > 0)
+        await Promise.allSettled([...pendingKeyHashes]);
+}
+/**
+ * Like {@link runWithSpan} for operations that carry user-controlled keys. The
+ * hash is computed concurrently with the call and attached under `attr` before
+ * the span ends; it can neither delay the call's result nor change its error.
+ * If hashing is impossible the attribute is omitted (never the raw key).
+ */
+export async function runWithSpanKeyed(span, attr, keys, fn, countAttr) {
+    // Bounded work per call: hash only the first MAX_HASHED_KEYS; the count is exact.
+    if (countAttr && keys.length > 0)
+        span.setAttribute(countAttr, keys.length);
+    const hashed = keys.length > 0 ? scrubKeysAsync(keys.slice(0, MAX_HASHED_KEYS)) : undefined;
+    try {
+        return await fn();
+    }
+    catch (err) {
+        recordSpanError(span, err);
+        throw err;
+    }
+    finally {
+        const end = () => {
+            try {
+                span.end();
+            }
+            catch {
+                // Telemetry must never surface errors.
+            }
+        };
+        if (hashed) {
+            const done = hashed.then((h) => {
+                try {
+                    if (h !== undefined)
+                        span.setAttribute(attr, h);
+                }
+                catch {
+                    // ignore
+                }
+                end();
+            }, end).finally(() => pendingKeyHashes.delete(done));
+            pendingKeyHashes.add(done);
+        }
+        else {
+            end();
+        }
+    }
+}
 function runSyncWithSpan(span, fn) {
     try {
         return fn();
@@ -113,7 +237,7 @@ function recordSpanError(span, error) {
     });
 }
 /** Trace a call without replacing synchronous, Promise, or custom thenable results. */
-function runWithSpanPreservingReturn(span, fn) {
+export function runWithSpanPreservingReturn(span, fn) {
     try {
         const result = fn();
         if (isPromiseLike(result)) {
@@ -200,6 +324,8 @@ function wrapD1Statement(stmt, sql, opts) {
         const span = opts.startSpan(`D1 ${op}`, {
             "db.system": "d1",
             "db.statement": sql,
+            "db.system.name": "cloudflare-d1",
+            "db.query.text": sql,
         });
         return runWithSpan(span, () => stmt[op](...args));
     };
@@ -225,6 +351,7 @@ function wrapD1(binding, opts) {
             }
             const span = opts.startSpan("D1 batch", {
                 "db.system": "d1",
+                "db.system.name": "cloudflare-d1",
                 "db.operation.name": "batch",
                 "db.operation.batch.size": statements.length,
             });
@@ -235,6 +362,7 @@ function wrapD1(binding, opts) {
                 return binding.exec(query);
             const span = opts.startSpan("D1 exec", {
                 "db.system": "d1",
+                "db.system.name": "cloudflare-d1",
                 "db.operation.name": "exec",
             });
             return runWithSpan(span, () => binding.exec(query));
@@ -255,6 +383,7 @@ function wrapD1Session(session, opts) {
             }
             const span = opts.startSpan("D1 session batch", {
                 "db.system": "d1",
+                "db.system.name": "cloudflare-d1",
                 "db.operation.name": "batch",
                 "db.operation.batch.size": statements.length,
             });
@@ -266,39 +395,33 @@ function wrapD1Session(session, opts) {
 // KV wrappers
 // ---------------------------------------------------------------------------
 function wrapKV(binding, opts, namespace) {
-    const wrapOp = (op, getKey) => async (...args) => {
+    const wrapOp = (op, keyed = false) => async (...args) => {
         if (isTracingSuppressed(context.active())) {
             return binding[op](...args);
         }
-        const attrs = { "kv.namespace": namespace };
-        const key = getKey?.(...args);
-        if (key !== undefined)
-            attrs["kv.key"] = key;
-        const span = opts.startSpan(`KV ${op}`, attrs);
-        return runWithSpan(span, () => binding[op](...args));
+        const span = opts.startSpan(`KV ${op}`, { "kv.namespace": namespace });
+        return runWithSpanKeyed(span, "cloudflare.kv.query.keys", keyed ? keysOf(args[0]) : [], () => binding[op](...args), "cloudflare.kv.query.key_count");
     };
     return makeProxy(binding, {
-        get: wrapOp("get", (key) => key),
-        getWithMetadata: wrapOp("getWithMetadata", (key) => key),
-        put: wrapOp("put", (key) => key),
+        get: wrapOp("get", true),
+        getWithMetadata: wrapOp("getWithMetadata", true),
+        put: wrapOp("put", true),
         list: wrapOp("list"),
-        delete: wrapOp("delete", (key) => key),
+        delete: wrapOp("delete", true),
     });
 }
 // ---------------------------------------------------------------------------
 // R2 wrappers
 // ---------------------------------------------------------------------------
+/** R2 object keys are user data: only the hashed form is ever emitted. */
+const R2_KEY_ATTR = "cloudflare.r2.request.key";
 function wrapR2(binding, opts, bucket) {
-    const wrapOp = (op, getKey) => async (...args) => {
+    const wrapOp = (op, keyed = false) => async (...args) => {
         if (isTracingSuppressed(context.active())) {
             return binding[op](...args);
         }
-        const attrs = { "r2.bucket": bucket };
-        const key = getKey?.(...args);
-        if (key !== undefined)
-            attrs["r2.key"] = key;
-        const span = opts.startSpan(`R2 ${op}`, attrs);
-        return runWithSpan(span, () => binding[op](...args));
+        const span = opts.startSpan(`R2 ${op}`, { "r2.bucket": bucket });
+        return runWithSpanKeyed(span, R2_KEY_ATTR, keyed ? keysOf(args[0]) : [], () => binding[op](...args), "cloudflare.r2.request.key_count");
     };
     const wrapMultipart = (upload, key) => makeProxy(upload, {
         uploadPart: async (partNumber, ...args) => {
@@ -307,10 +430,9 @@ function wrapR2(binding, opts, bucket) {
             }
             const span = opts.startSpan("R2 uploadPart", {
                 "r2.bucket": bucket,
-                "r2.key": key,
                 "r2.multipart.part_number": partNumber,
             });
-            return runWithSpan(span, () => upload.uploadPart(partNumber, ...args));
+            return runWithSpanKeyed(span, R2_KEY_ATTR, [key], () => upload.uploadPart(partNumber, ...args));
         },
         abort: wrapMultipartOp("abort", upload, key),
         complete: wrapMultipartOp("complete", upload, key, (parts) => ({
@@ -323,28 +445,24 @@ function wrapR2(binding, opts, bucket) {
                 return upload[op](...args);
             const span = opts.startSpan(`R2 ${op}`, {
                 "r2.bucket": bucket,
-                "r2.key": key,
                 ...extraAttrs?.(...args),
             });
-            return runWithSpan(span, () => upload[op](...args));
+            return runWithSpanKeyed(span, R2_KEY_ATTR, [key], () => upload[op](...args));
         };
     }
     return makeProxy(binding, {
-        get: wrapOp("get", (key) => key),
-        put: wrapOp("put", (key) => key),
-        head: wrapOp("head", (key) => key),
-        delete: wrapOp("delete", (key) => key),
+        get: wrapOp("get", true),
+        put: wrapOp("put", true),
+        head: wrapOp("head", true),
+        delete: wrapOp("delete", true),
         list: wrapOp("list"),
         async createMultipartUpload(key, ...args) {
             if (isTracingSuppressed(context.active())) {
                 const upload = await binding.createMultipartUpload(key, ...args);
                 return wrapMultipart(upload, key);
             }
-            const span = opts.startSpan("R2 createMultipartUpload", {
-                "r2.bucket": bucket,
-                "r2.key": key,
-            });
-            const upload = await runWithSpan(span, () => binding.createMultipartUpload(key, ...args));
+            const span = opts.startSpan("R2 createMultipartUpload", { "r2.bucket": bucket });
+            const upload = await runWithSpanKeyed(span, R2_KEY_ATTR, [key], () => binding.createMultipartUpload(key, ...args));
             return wrapMultipart(upload, key);
         },
         resumeMultipartUpload(key, uploadId) {
@@ -360,18 +478,23 @@ function wrapVectorize(binding, opts, indexName) {
         if (isTracingSuppressed(context.active())) {
             return binding[op](...args);
         }
-        const span = opts.startSpan(`Vectorize ${op}`, {
-            "vectorize.index": indexName,
-        });
-        return runWithSpan(span, () => binding[op](...args));
+        const attrs = { "vectorize.index": indexName };
+        if (opts.nativeNames) {
+            attrs["cloudflare.binding.type"] = "vectorize";
+            attrs["cloudflare.binding.name"] = indexName;
+        }
+        return traced(opts, nm(opts, `Vectorize ${op}`, `vectorize_${op}`), attrs, undefined, () => binding[op](...args));
     };
-    return makeProxy(binding, {
+    const handlers = {
         query: wrapOp("query"),
         upsert: wrapOp("upsert"),
         insert: wrapOp("insert"),
         deleteByIds: wrapOp("deleteByIds"),
         getByIds: wrapOp("getByIds"),
-    });
+    };
+    if (opts.nativeNames && typeof binding.describe === "function")
+        handlers.describe = wrapOp("describe");
+    return makeProxy(binding, handlers);
 }
 // ---------------------------------------------------------------------------
 // Workers AI wrapper
@@ -385,11 +508,17 @@ function wrapWorkersAI(binding, opts, _name) {
             const attrs = {
                 "gen_ai.system": "cloudflare.workers_ai",
             };
+            if (opts.nativeNames) {
+                attrs["cloudflare.binding.type"] = "ai";
+                attrs["cloudflare.binding.name"] = _name;
+                attrs["gen_ai.provider.name"] = "cloudflare";
+                attrs["gen_ai.operation.name"] = "chat";
+            }
             if (typeof args[0] === "string") {
                 attrs["gen_ai.request.model"] = args[0];
             }
-            const span = opts.startSpan("AI run", attrs, SpanKind.CLIENT);
-            try {
+            // PRIVACY: never records prompts/completions — only model + token usage.
+            return traced(opts, nm(opts, "AI run", "ai_run"), attrs, SpanKind.CLIENT, async (span) => {
                 const result = await binding.run(...args);
                 // Best-effort usage extraction — never read/await/tee the stream.
                 try {
@@ -410,18 +539,7 @@ function wrapWorkersAI(binding, opts, _name) {
                     // Swallow — a weird shape must never throw.
                 }
                 return result;
-            }
-            catch (err) {
-                span.recordException(err instanceof Error ? err : new Error(String(err)));
-                span.setStatus({
-                    code: SpanStatusCode.ERROR,
-                    message: err instanceof Error ? err.message : String(err),
-                });
-                throw err;
-            }
-            finally {
-                span.end();
-            }
+            });
         },
     });
 }
@@ -432,6 +550,7 @@ function wrapQueue(binding, opts, name) {
     const baseAttrs = {
         "messaging.system": "cloudflare_queues",
         "messaging.destination.name": name,
+        "cloudflare.queue.name": name,
     };
     return makeProxy(binding, {
         send: async (...args) => {
@@ -481,8 +600,7 @@ function wrapWorkflow(binding, opts, name) {
         const count = getCount?.(...args);
         if (count !== undefined)
             attrs["cloudflare.workflow.batch.size"] = count;
-        const span = opts.startSpan(`Workflow ${op}`, attrs, kind);
-        return runWithSpan(span, () => binding[op](...args));
+        return traced(opts, nm(opts, `Workflow ${op}`, `workflow_${op}`), attrs, kind, () => binding[op](...args));
     };
     return makeProxy(binding, {
         get: wrapOp("get", SpanKind.CLIENT),
@@ -497,7 +615,7 @@ function wrapRateLimit(binding, opts, name) {
             if (isTracingSuppressed(context.active()))
                 return binding.limit(...args);
             const span = opts.startSpan("RateLimit limit", {
-                "cloudflare.binding.type": "rate_limit",
+                "cloudflare.binding.type": "ratelimit",
                 "cloudflare.binding.name": name,
             });
             return runWithSpan(span, () => binding.limit(...args));
@@ -509,7 +627,7 @@ function wrapAnalyticsEngine(binding, opts, name) {
         writeDataPoint(...args) {
             if (isTracingSuppressed(context.active()))
                 return binding.writeDataPoint(...args);
-            const span = opts.startSpan("AnalyticsEngine writeDataPoint", {
+            const span = opts.startSpan(nm(opts, "AnalyticsEngine writeDataPoint", "analytics_engine_writeDataPoint"), {
                 "cloudflare.binding.type": "analytics_engine",
                 "cloudflare.binding.name": name,
             });
@@ -557,8 +675,10 @@ function wrapService(binding, opts, name) {
             }
             const span = opts.startSpan(`Service ${name} fetch`, { "peer.service": name }, SpanKind.CLIENT);
             const sc = span.spanContext();
-            const traceparent = makeTraceparent(sc);
-            const injectedArgs = injectTraceparentArgs(args, traceparent);
+            // Native spans expose no ids (INVALID context): never inject an all-zero traceparent.
+            const injectedArgs = isSpanContextValid(sc)
+                ? injectTraceparentArgs(args, makeTraceparent(sc))
+                : args;
             return runWithSpan(span, () => binding.fetch(...injectedArgs));
         },
     });
@@ -594,7 +714,9 @@ function wrapDurableObjectStub(stub, opts, name) {
         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));
+        const injectedArgs = isSpanContextValid(sc)
+            ? injectTraceparentArgs(args, makeTraceparent(sc))
+            : args;
         return runWithSpanPreservingReturn(span, () => stub.fetch(...injectedArgs));
     };
     // workerd exposes RPC methods through a wildcard property hook, so method
@@ -699,7 +821,11 @@ function wrapWorkflowInstance(instance, opts, name) {
             if (instanceId !== undefined) {
                 attrs["cloudflare.workflow.instance_id"] = instanceId;
             }
-            const span = opts.startSpan(`Workflow ${method}`, attrs, SpanKind.CLIENT);
+            if (opts.nativeNames) {
+                attrs["cloudflare.binding.type"] = "workflow";
+                attrs["cloudflare.binding.name"] = name;
+            }
+            const span = opts.startSpan(nm(opts, `Workflow ${method}`, `workflow_${method}`), attrs, SpanKind.CLIENT);
             return runWithSpanPreservingReturn(span, () => underlying.apply(instance, args));
         };
     }
@@ -746,7 +872,7 @@ function wrapWorkflowBinding(binding, opts, name) {
                 attrs["cloudflare.workflow.instance_ids"] = batchIds;
                 attrs["cloudflare.workflow.batch.size"] = batchIds.length;
             }
-            const span = opts.startSpan(`Workflow ${op}`, attrs, SpanKind.CLIENT);
+            const span = opts.startSpan(nm(opts, `Workflow ${op}`, `workflow_${op}`), attrs, SpanKind.CLIENT);
             return runWithSpanPreservingReturn(span, () => mapReturn(binding[op](...args), (value) => wrapWorkflowBindingResult(value, op, opts, name, span)));
         };
     }
@@ -785,52 +911,201 @@ function wrapWorkflowBinding(binding, opts, name) {
  * @param opts - `startSpan` factory (now accepts optional `SpanKind`) + `select` filter.
  * @returns A shallow copy of `env` with selected bindings replaced by proxies.
  */
-export function instrumentEnv(env, opts) {
+export function instrumentEnv(env, rawOpts) {
+    if (typeof rawOpts.startSpan !== "function" && typeof rawOpts.withSpan !== "function") {
+        throw new TypeError("instrumentEnv requires opts.startSpan or opts.withSpan");
+    }
+    // withSpan wins: the legacy wrappers get an adapter so startSpan is never called.
+    const opts = rawOpts.withSpan
+        ? { ...rawOpts, startSpan: startSpanFromWithSpan(rawOpts.withSpan) }
+        : rawOpts;
     const result = { ...env };
-    const { select } = opts;
+    const { select, kindFilter } = opts;
+    const allow = (kind) => !kindFilter || kindFilter(kind);
+    // Direct mode: stamp binding type/name on every span a binding emits. Native
+    // mode (`withSpan`) already sets them where it enriches, and stays unchanged.
+    const stamped = (type, key) => {
+        if (rawOpts.withSpan)
+            return opts;
+        const base = opts.startSpan;
+        return {
+            ...opts,
+            startSpan: (name, attrs, kind) => base(name, { "cloudflare.binding.type": type, "cloudflare.binding.name": key, ...attrs }, kind),
+        };
+    };
     for (const key of Object.keys(env)) {
         // Filter: if select is an array, only wrap keys in the list.
         if (select !== true && !select.includes(key))
             continue;
         const binding = env[key];
         if (isD1Like(binding)) {
-            result[key] = wrapD1(binding, opts);
+            if (allow("d1"))
+                result[key] = wrapD1(binding, stamped("d1", key));
         }
         else if (isR2Like(binding)) {
             // R2 before KV — R2 also has `list`, so checking `head` first avoids mis-classifying.
-            result[key] = wrapR2(binding, opts, key);
+            if (allow("r2"))
+                result[key] = wrapR2(binding, stamped("r2", key), key);
         }
         else if (isKVLike(binding)) {
-            result[key] = wrapKV(binding, opts, key);
+            if (allow("kv"))
+                result[key] = wrapKV(binding, stamped("kv", key), key);
         }
         else if (isVectorizeLike(binding)) {
-            result[key] = wrapVectorize(binding, opts, key);
+            if (allow("vectorize"))
+                result[key] = wrapVectorize(binding, stamped("vectorize", key), key);
         }
         else if (isWorkersAILike(binding)) {
-            result[key] = wrapWorkersAI(binding, opts, key);
+            if (allow("ai"))
+                result[key] = wrapWorkersAI(binding, stamped("ai", key), key);
         }
         else if (isQueueLike(binding)) {
-            result[key] = wrapQueue(binding, opts, key);
+            if (allow("queue"))
+                result[key] = wrapQueue(binding, stamped("queue", key), key);
         }
         else if (isDurableObjectNamespaceLike(binding)) {
-            result[key] = wrapDurableObjectNamespace(binding, opts, key);
+            if (allow("durable_object"))
+                result[key] = wrapDurableObjectNamespace(binding, stamped("durable_object", key), key);
         }
         else if (isWorkflowBindingLike(binding)) {
-            result[key] = wrapWorkflowBinding(binding, opts, key);
+            if (allow("workflow"))
+                result[key] = wrapWorkflowBinding(binding, stamped("workflow", key), key);
         }
         else if (isWorkflowLike(binding)) {
-            result[key] = wrapWorkflow(binding, opts, key);
+            if (allow("workflow"))
+                result[key] = wrapWorkflow(binding, stamped("workflow", key), key);
         }
         else if (isRateLimitLike(binding)) {
-            result[key] = wrapRateLimit(binding, opts, key);
+            if (allow("ratelimit"))
+                result[key] = wrapRateLimit(binding, stamped("ratelimit", key), key);
         }
         else if (isAnalyticsEngineLike(binding)) {
-            result[key] = wrapAnalyticsEngine(binding, opts, key);
+            if (allow("analytics_engine"))
+                result[key] = wrapAnalyticsEngine(binding, stamped("analytics_engine", key), key);
         }
         else if (isServiceLike(binding)) {
-            result[key] = wrapService(binding, opts, key);
+            if (allow("service"))
+                result[key] = wrapService(binding, stamped("service", key), key);
         }
         // Unrecognised bindings are left as-is.
     }
     return result;
 }
+// ---------------------------------------------------------------------------
+// Hyperdrive: wrap the SQL client the app builds on top of the binding
+// ---------------------------------------------------------------------------
+/**
+ * Wrap a Postgres/MySQL client (postgres.js, pg, mysql2, ...) created from a
+ * Hyperdrive binding so each `query` / `unsafe` / `execute` call, and each
+ * tagged-template call when the client itself is callable (postgres.js
+ * `sql\`select 1\``), emits a `hyperdrive_query` span. `db.query.text` is
+ * recorded raw (template strings are joined with `?`; ingest sanitises). The
+ * ORIGINAL return value is passed through untouched; the span ends when it
+ * settles. Uses the request's native tracer when present, else the global one.
+ */
+export function wrapSqlClient(client, opts = {}) {
+    const traceCall = (args, run) => {
+        if (isTracingSuppressed(context.active()))
+            return run();
+        const attrs = { "cloudflare.binding.type": "hyperdrive" };
+        if (opts.name)
+            attrs["cloudflare.binding.name"] = opts.name;
+        if (opts.dbSystem)
+            attrs["db.system.name"] = opts.dbSystem;
+        const first = args[0];
+        if (Array.isArray(first) && "raw" in first)
+            attrs["db.query.text"] = first.join("?");
+        else if (typeof first === "string")
+            attrs["db.query.text"] = first;
+        else if (typeof first?.text === "string") {
+            attrs["db.query.text"] = first.text;
+        }
+        const native = nativeTracingFromContext();
+        const startSpan = () => native
+            ? startSpanFromWithSpan((n, at, _k, fn) => runNativeSpan(native, n, at, fn))("hyperdrive_query", attrs, SpanKind.CLIENT)
+            : trace.getTracer("heystack").startSpan("hyperdrive_query", {
+                attributes: attrs,
+                kind: SpanKind.CLIENT,
+            });
+        let result;
+        let span;
+        try {
+            result = run();
+        }
+        catch (error) {
+            span = startSpan();
+            recordSpanError(span, error);
+            span.end();
+            throw error;
+        }
+        if (!isPromiseLike(result)) {
+            // Synchronous result: nothing lazy to protect.
+            span = startSpan();
+            span.end();
+            return result;
+        }
+        // A plain native Promise is already running and `await` bypasses an own
+        // `then`, so observe it eagerly (safe: observing cannot start anything).
+        if (Object.getPrototypeOf(result) === Promise.prototype) {
+            return runWithSpanPreservingReturn(startSpan(), () => result);
+        }
+        // LAZY thenables (postgres.js `Query`) start executing inside `then()`, so we
+        // must never call `then` ourselves: a fragment nested in another query and
+        // never awaited would otherwise run standalone. Instead shadow `then` on the
+        // instance and start the span on the first consumer-driven call.
+        const origThen = result.then;
+        let started = false;
+        try {
+            Object.defineProperty(result, "then", {
+                configurable: true,
+                writable: true,
+                value: function (onOk, onErr) {
+                    if (started)
+                        return origThen.call(this, onOk, onErr);
+                    started = true;
+                    const sp = startSpan();
+                    return origThen.call(this, (v) => {
+                        try {
+                            sp.end();
+                        }
+                        catch { /* never alter the result */ }
+                        return onOk ? onOk(v) : v;
+                    }, (e) => {
+                        try {
+                            recordSpanError(sp, e);
+                            sp.end();
+                        }
+                        catch { /* never alter the result */ }
+                        if (onErr)
+                            return onErr(e);
+                        throw e;
+                    });
+                },
+            });
+        }
+        catch {
+            // Frozen / non-extensible: return untraced.
+        }
+        return result;
+    };
+    const methods = new Map();
+    return new Proxy(client, {
+        get(target, prop, receiver) {
+            const value = Reflect.get(target, prop, receiver);
+            if (typeof value !== "function")
+                return value;
+            if (prop === "query" || prop === "unsafe" || prop === "execute") {
+                let wrapped = methods.get(prop);
+                if (!wrapped) {
+                    wrapped = (...args) => traceCall(args, () => value.apply(target, args));
+                    methods.set(prop, wrapped);
+                }
+                return wrapped;
+            }
+            return value.bind(target);
+        },
+        apply(target, thisArg, args) {
+            return traceCall(args, () => Reflect.apply(target, thisArg, args));
+        },
+    });
+}

package/dist/workers-coverage.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Which Cloudflare binding kinds Cloudflare's native tracing already spans.
+ * In native mode the SDK enriches ONLY the uncovered kinds so a D1/KV/R2/... call
+ * is never reported twice. WinterCG-safe: pure data, no imports.
+ */
+export type BindingKind = "d1" | "kv" | "r2" | "durable_object" | "queue" | "ai" | "vectorize" | "workflow" | "hyperdrive" | "analytics_engine" | "ratelimit" | "service" | "fetch";
+export declare const NATIVELY_COVERED: Readonly<Record<BindingKind, boolean>>;
+/** Native tracing does not propagate trace context to external (non-Cloudflare) services. */
+export declare const NATIVE_PROPAGATES_EXTERNAL = false;
+/** `enrich?.[kind] ?? !table[kind]` — `table` is a test seam. */
+export declare function shouldEnrichNatively(kind: BindingKind, enrich?: Partial<Record<BindingKind, boolean>>, table?: Readonly<Record<BindingKind, boolean>>): boolean;