@heystack/otel 0.18.0 → 0.19.0

package/dist/workers-coverage.js

@@ -0,0 +1,22 @@
+export const NATIVELY_COVERED = Object.freeze({
+    d1: true,
+    kv: true,
+    r2: true,
+    durable_object: true,
+    queue: true,
+    ratelimit: true,
+    fetch: true,
+    // Cloudflare propagates Worker-to-Worker calls automatically and emits `jsrpc.*` spans.
+    service: true,
+    ai: false,
+    vectorize: false,
+    workflow: false,
+    hyperdrive: false,
+    analytics_engine: false,
+});
+/** Native tracing does not propagate trace context to external (non-Cloudflare) services. */
+export const NATIVE_PROPAGATES_EXTERNAL = false;
+/** `enrich?.[kind] ?? !table[kind]` — `table` is a test seam. */
+export function shouldEnrichNatively(kind, enrich, table = NATIVELY_COVERED) {
+    return enrich?.[kind] ?? !table[kind];
+}

package/dist/workers-native.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Cloudflare-native custom span support (WinterCG-safe: only `@opentelemetry/api`
+ * and relative modules — no `node:*`).
+ *
+ * Cloudflare's `ctx.tracing` custom span API exposes NO trace/span ids, so
+ * `NativeOtelSpan.spanContext()` always returns INVALID_SPAN_CONTEXT — ids are
+ * never fabricated.
+ */
+import { type Span, type SpanAttributes, type SpanAttributeValue, type SpanContext, type SpanStatus as ApiSpanStatus, type Link, type Exception, type TimeInput } from "@opentelemetry/api";
+type Attr = string | number | boolean | undefined;
+/** Minimal public surface exposed by Cloudflare's Workers custom-spans API. */
+export interface CloudflareSpan {
+    readonly isTraced?: boolean;
+    setAttribute(key: string, value: Attr): unknown;
+    setAttributes?(attributes: Record<string, Attr>): unknown;
+    recordException?(exception: unknown): void;
+    end?(): void;
+}
+/** `ExecutionContext.tracing` without importing the `cloudflare:workers` module. */
+export interface CloudflareTracing {
+    enterSpan<T, A extends unknown[]>(name: string, callback: (span: CloudflareSpan, ...args: A) => T, ...args: A): T;
+    startActiveSpan?<T>(name: string, callback: (span: CloudflareSpan) => T): T;
+    startSpan?(name: string): CloudflareSpan;
+    getActiveSpan?(): CloudflareSpan | undefined;
+}
+/** @deprecated Use {@link CloudflareSpan}. */
+export type CloudflareNativeSpan = CloudflareSpan;
+/** @deprecated Use {@link CloudflareTracing}. */
+export type CloudflareNativeTracing = CloudflareTracing;
+/**
+ * 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.
+ */
+export declare const NATIVE_TRACING_CONTEXT_KEY: symbol;
+export declare function nativeTracingFromContext(): CloudflareTracing | undefined;
+/** workers.ts registers its global ContextManager bootstrap here (avoids an import cycle). */
+export declare function setNativeContextInit(fn: () => void): void;
+/**
+ * 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.
+ */
+export declare class NativeOtelSpan implements Span {
+    private readonly nativeSpan;
+    private ended;
+    /** True once `recordException` stamped a specific `error.type` (the exception class). */
+    private errorTyped;
+    constructor(nativeSpan: CloudflareSpan);
+    spanContext(): SpanContext;
+    setAttribute(key: string, value: SpanAttributeValue): this;
+    setAttributes(attributes: SpanAttributes): this;
+    addEvent(name: string, attributesOrStartTime?: SpanAttributes | TimeInput): this;
+    addLink(_link: Link): this;
+    addLinks(_links: Link[]): this;
+    setStatus(status: ApiSpanStatus): this;
+    updateName(_name: string): this;
+    /** Calls the native `end` exactly once. */
+    end(_endTime?: TimeInput): void;
+    isRecording(): boolean;
+    recordException(exception: Exception, _time?: TimeInput): void;
+}
+/** Resolve the native tracer: explicit config override first, then `ctx.tracing`. */
+export declare function getNativeTracing(ctx: unknown, override?: CloudflareTracing): CloudflareTracing | null;
+export declare function runNativeSpan<T>(tracing: CloudflareTracing | null, name: string, attrs: Record<string, Attr>, fn: (span: NativeOtelSpan) => T | Promise<T>): Promise<T>;
+export {};

package/dist/workers-native.js

@@ -0,0 +1,147 @@
+/**
+ * Cloudflare-native custom span support (WinterCG-safe: only `@opentelemetry/api`
+ * and relative modules — no `node:*`).
+ *
+ * Cloudflare's `ctx.tracing` custom span API exposes NO trace/span ids, so
+ * `NativeOtelSpan.spanContext()` always returns INVALID_SPAN_CONTEXT — ids are
+ * never fabricated.
+ */
+import { context, createContextKey, INVALID_SPAN_CONTEXT, trace, SpanStatusCode, } from "@opentelemetry/api";
+/**
+ * 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.
+ */
+export const NATIVE_TRACING_CONTEXT_KEY = createContextKey("heystack.cloudflare.native-tracing");
+export function nativeTracingFromContext() {
+    return context.active().getValue(NATIVE_TRACING_CONTEXT_KEY);
+}
+let contextInit;
+/** workers.ts registers its global ContextManager bootstrap here (avoids an import cycle). */
+export function setNativeContextInit(fn) {
+    contextInit = fn;
+}
+/**
+ * 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.
+ */
+export class NativeOtelSpan {
+    nativeSpan;
+    ended = false;
+    /** True once `recordException` stamped a specific `error.type` (the exception class). */
+    errorTyped = false;
+    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; drop the attribute.
+        }
+        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.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; }
+    setStatus(status) {
+        if (status.code === SpanStatusCode.ERROR) {
+            // Don't clobber the more specific class name a preceding recordException set.
+            if (!this.errorTyped)
+                this.setAttribute("error.type", "error");
+            if (status.message)
+                this.setAttribute("error.message", status.message);
+            this.setAttribute("otel.status_code", "ERROR");
+        }
+        return this;
+    }
+    updateName(_name) { return this; }
+    /** Calls the native `end` exactly once. */
+    end(_endTime) {
+        if (this.ended)
+            return;
+        this.ended = true;
+        try {
+            this.nativeSpan.end?.();
+        }
+        catch { /* never surface */ }
+    }
+    isRecording() { return this.nativeSpan.isTraced !== false; }
+    recordException(exception, _time) {
+        const error = exception instanceof Error ? exception : new Error(String(exception));
+        this.setAttribute("error.type", error.name || "Error");
+        this.errorTyped = true;
+        this.setAttribute("error.message", error.message);
+        if (error.stack)
+            this.setAttribute("exception.stacktrace", error.stack);
+        try {
+            this.nativeSpan.recordException?.(error);
+        }
+        catch { /* never surface */ }
+    }
+}
+/** Resolve the native tracer: explicit config override first, then `ctx.tracing`. */
+export function getNativeTracing(ctx, override) {
+    if (override && typeof override.enterSpan === "function")
+        return override;
+    const candidate = ctx?.tracing;
+    return candidate && typeof candidate.enterSpan === "function" ? candidate : null;
+}
+const NOOP_NATIVE_SPAN = { isTraced: false, setAttribute: () => undefined };
+export async function runNativeSpan(tracing, name, attrs, fn) {
+    contextInit?.();
+    const body = async (nativeSpan, ownsEnd) => {
+        const adapter = new NativeOtelSpan(nativeSpan);
+        for (const [key, value] of Object.entries(attrs)) {
+            if (value !== undefined)
+                adapter.setAttribute(key, value);
+        }
+        const base = tracing ? context.active().setValue(NATIVE_TRACING_CONTEXT_KEY, tracing) : context.active();
+        const nativeContext = trace.setSpan(base, 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;
+        }
+        finally {
+            if (ownsEnd)
+                adapter.end();
+        }
+    };
+    if (!tracing)
+        return body(NOOP_NATIVE_SPAN, false);
+    if (typeof tracing.startActiveSpan === "function") {
+        return tracing.startActiveSpan(name, (s) => body(s, true));
+    }
+    // enterSpan ends the span when the callback settles.
+    return tracing.enterSpan(name, (s) => body(s, false));
+}

package/dist/workers-propagation.d.ts

@@ -0,0 +1,24 @@
+export interface NativePropagation {
+    traceId: string;
+    spanId: string;
+}
+export declare const NATIVE_PROPAGATION_CONTEXT_KEY: symbol;
+/** One synthetic trace/span pair standing for the whole invocation. */
+export declare function createNativePropagation(random?: (n: number) => Uint8Array): NativePropagation;
+export declare function propagationTraceparent(p: NativePropagation): string;
+export declare function isAiGatewayHost(url: URL): boolean;
+/** Hostname allow-check: undefined = all hosts, [] = none; string = exact host, RegExp tests the host. */
+export declare function propagationTargetAllowed(hostname: string, targets: ReadonlyArray<string | RegExp> | undefined): boolean;
+/**
+ * Return `[input, init]` with `traceparent` (and `cf-aig-otel-*` for the AI
+ * Gateway) added. Never overwrites an existing header, never mutates the
+ * caller's objects, and never consumes a Request body (the Request itself is
+ * passed through; only `init.headers` carries the merged set).
+ */
+export declare function injectOutboundHeaders(input: RequestInfo | URL, init: RequestInit | undefined, opts: {
+    traceparent: string;
+    aiGateway?: {
+        traceId: string;
+        parentSpanId: string;
+    };
+}): [RequestInfo | URL, RequestInit];

package/dist/workers-propagation.js

@@ -0,0 +1,72 @@
+/**
+ * Native-mode trace propagation (WinterCG-safe: no node:* imports).
+ *
+ * Cloudflare's native spans expose no trace/span ids, so the SDK mints ONE
+ * synthetic pair per invocation. It is emitted on outbound headers and recorded
+ * on the root span as `heystack.propagation.*` link attributes; ingest turns
+ * those into span links. The synthetic ids are NOT Cloudflare's native ids.
+ */
+import { createContextKey } from "@opentelemetry/api";
+import { detectLLMProvider } from "./llm-enrich.js";
+export const NATIVE_PROPAGATION_CONTEXT_KEY = createContextKey("heystack.native-propagation");
+function randomHex(bytes, random) {
+    for (let attempt = 0; attempt < 4; attempt++) {
+        const buf = random(bytes);
+        let hex = "";
+        let nonZero = false;
+        for (const b of buf) {
+            if (b !== 0)
+                nonZero = true;
+            hex += b.toString(16).padStart(2, "0");
+        }
+        if (nonZero)
+            return hex;
+    }
+    return "1".padStart(bytes * 2, "0");
+}
+const defaultRandom = (n) => crypto.getRandomValues(new Uint8Array(n));
+/** One synthetic trace/span pair standing for the whole invocation. */
+export function createNativePropagation(random = defaultRandom) {
+    return { traceId: randomHex(16, random), spanId: randomHex(8, random) };
+}
+export function propagationTraceparent(p) {
+    return `00-${p.traceId}-${p.spanId}-01`;
+}
+export function isAiGatewayHost(url) {
+    return detectLLMProvider(url.hostname) === "cloudflare";
+}
+/** Hostname allow-check: undefined = all hosts, [] = none; string = exact host, RegExp tests the host. */
+export function propagationTargetAllowed(hostname, targets) {
+    if (!targets)
+        return true;
+    const host = hostname.toLowerCase();
+    for (const t of targets) {
+        try {
+            if (typeof t === "string" ? t.toLowerCase() === host : t.test(host))
+                return true;
+        }
+        catch {
+            // bad pattern: skip
+        }
+    }
+    return false;
+}
+/**
+ * Return `[input, init]` with `traceparent` (and `cf-aig-otel-*` for the AI
+ * Gateway) added. Never overwrites an existing header, never mutates the
+ * caller's objects, and never consumes a Request body (the Request itself is
+ * passed through; only `init.headers` carries the merged set).
+ */
+export function injectOutboundHeaders(input, init, opts) {
+    const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
+    if (!headers.has("traceparent"))
+        headers.set("traceparent", opts.traceparent);
+    if (opts.aiGateway) {
+        if (!headers.has("cf-aig-otel-trace-id"))
+            headers.set("cf-aig-otel-trace-id", opts.aiGateway.traceId);
+        if (!headers.has("cf-aig-otel-parent-span-id")) {
+            headers.set("cf-aig-otel-parent-span-id", opts.aiGateway.parentSpanId);
+        }
+    }
+    return [input, { ...(init ?? {}), headers }];
+}

package/dist/workers-routes.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Route templating for Workers. `routes` patterns look like `/users/:id` or
+ * `/files/*`; the matched PATTERN (never the raw path) becomes `http.route`.
+ */
+/** First matching pattern wins; `:name` matches one segment, trailing `*` matches the rest. */
+export declare function matchRoute(pathname: string, routes: readonly string[]): string | undefined;
+/** Resolve `http.route`: `routeTemplate(req)` first, then `routes`. Never throws. */
+export declare function resolveRoute(req: Request, opts: {
+    routes?: readonly string[];
+    routeTemplate?: (req: Request) => string | undefined;
+}): string | undefined;

package/dist/workers-routes.js

@@ -0,0 +1,45 @@
+/**
+ * Route templating for Workers. `routes` patterns look like `/users/:id` or
+ * `/files/*`; the matched PATTERN (never the raw path) becomes `http.route`.
+ */
+const MAX_ROUTE_LEN = 256;
+function segs(p) {
+    return p.split("/").filter((s) => s !== "");
+}
+/** First matching pattern wins; `:name` matches one segment, trailing `*` matches the rest. */
+export function matchRoute(pathname, routes) {
+    const path = segs(pathname);
+    for (const pattern of routes) {
+        if (typeof pattern !== "string" || pattern === "")
+            continue;
+        const pat = segs(pattern);
+        const star = pat[pat.length - 1] === "*";
+        const fixed = star ? pat.slice(0, -1) : pat;
+        if (star ? path.length < fixed.length : path.length !== fixed.length)
+            continue;
+        const ok = fixed.every((p, i) => p[0] === ":" || p === path[i]);
+        if (ok)
+            return pattern;
+    }
+    return undefined;
+}
+/** Resolve `http.route`: `routeTemplate(req)` first, then `routes`. Never throws. */
+export function resolveRoute(req, opts) {
+    try {
+        const t = opts.routeTemplate?.(req);
+        if (typeof t === "string" && t !== "" && t.length <= MAX_ROUTE_LEN)
+            return t;
+    }
+    catch {
+        // a faulty user callback must never affect the request
+    }
+    if (opts.routes && opts.routes.length > 0) {
+        try {
+            return matchRoute(new URL(req.url).pathname, opts.routes);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}

package/dist/workers-sampler.d.ts

@@ -29,7 +29,16 @@ export declare function loadRemoteSamplingRate(opts: {
     apiKey: string;
     fetchImpl: typeof fetch;
 }): Promise<void>;
+export interface SamplerOptions {
+    /**
+     * Honour a REMOTE parent's sampled flag (an inbound `traceparent` `-01`/`-00`).
+     * Default `true`. When `false`, a remote parent gets the same ratio decision as
+     * a fresh root (over the continued trace id), so an untrusted caller can neither
+     * force recording nor suppress it. Local parents are always honoured.
+     */
+    trustRemoteParent?: boolean;
+}
 export declare function makeSampler(sampling?: {
     rate?: number;
     remote?: boolean;
-}): Sampler;
+}, opts?: SamplerOptions): Sampler;

package/dist/workers-sampler.js

@@ -74,16 +74,20 @@ export async function loadRemoteSamplingRate(opts) {
         /* fail open: leave rate at keep-all */
     }
 }
-export function makeSampler(sampling) {
+export function makeSampler(sampling, opts = {}) {
+    const parentBased = (root) => opts.trustRemoteParent === false
+        ? new ParentBasedSampler({ root, remoteParentSampled: root, remoteParentNotSampled: root })
+        : new ParentBasedSampler({ root });
     if (sampling?.remote) {
         // Dynamic rate: reads from the per-isolate ref that loadRemoteSamplingRate sets.
         // Starts at 1 (keep-all) until the config fetch resolves on the first request.
-        return new ParentBasedSampler({ root: new HeystackRatioSampler(() => _remoteRate.value) });
+        return parentBased(new HeystackRatioSampler(() => _remoteRate.value));
     }
     const rate = sampling?.rate;
     if (rate === undefined || rate >= 1)
         return new AlwaysOnSampler();
     // ParentBased: a sampled/dropped PARENT (local or remote via traceparent) wins,
     // so a distributed trace samples consistently; only the root uses the ratio.
-    return new ParentBasedSampler({ root: new HeystackRatioSampler(rate) });
+    // With trustRemoteParent=false a remote parent is re-decided by the ratio.
+    return parentBased(new HeystackRatioSampler(rate));
 }

package/dist/workers.d.ts

@@ -3,6 +3,10 @@ import { type Context, type ContextManager } from "@opentelemetry/api";
 import { BasicTracerProvider, type ReadableSpan, type SpanExporter } from "@opentelemetry/sdk-trace-base";
 import { type HeystackOptions } from "./core.js";
 import { type LLMGatewayConfig } from "./llm-enrich.js";
+import { wrapSqlClient } from "./workers-bindings.js";
+import { NATIVELY_COVERED, NATIVE_PROPAGATES_EXTERNAL, shouldEnrichNatively, type BindingKind } from "./workers-coverage.js";
+import { type CloudflareSpan, type CloudflareTracing } from "./workers-native.js";
+import { type SpanPrivacyOptions } from "./redact.js";
 declare const ExportResultCode: {
     readonly SUCCESS: 0;
     readonly FAILED: 1;
@@ -54,13 +58,15 @@ interface OtlpTracesPayload {
         }[];
     }[];
 }
+/** Per-span attribute transform applied at serialization (privacy pass). */
+type AttributeTransform = (attrs: Record<string, unknown>, span: ReadableSpan) => Record<string, unknown>;
 /**
  * Serialize a batch of ended spans into a single OTLP/JSON traces payload.
  *
  * All spans in a SimpleSpanProcessor batch share the same per-request provider,
  * hence the same resource, so we emit a single resourceSpans entry.
  */
-export declare function serializeSpans(spans: ReadableSpan[]): OtlpTracesPayload;
+export declare function serializeSpans(spans: ReadableSpan[], transform?: AttributeTransform): OtlpTracesPayload;
 /** Parse a W3C `traceparent`. Returns null for malformed or all-zero ids. */
 export declare function parseTraceparent(header: string | null): {
     traceId: string;
@@ -112,7 +118,13 @@ export declare class HeystackSpanExporter implements SpanExporter {
      * the `pending` set + manual `flushHeystack()` when absent/unavailable.
      */
     waitUntil?: (p: Promise<unknown>) => void;
-    constructor(options: HeystackOptions);
+    /**
+     * 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.
+     */
+    private readonly privacy;
+    constructor(options: HeystackOptions & SpanPrivacyOptions);
     export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void;
     /**
      * POST the batch with ONE bounded automatic retry for network errors / 429 /
@@ -143,7 +155,7 @@ export declare class HeystackSpanExporter implements SpanExporter {
      */
     forceFlush(): Promise<void>;
 }
-export interface WorkersConfig {
+export interface WorkersConfig extends SpanPrivacyOptions {
     service: string;
     /** Defaults to env.HEYSTACK_API_KEY at request time if omitted. */
     apiKey?: string;
@@ -185,17 +197,33 @@ export interface WorkersConfig {
      * Defaults to `false` (no binding tracing). Consumed by a later task.
      */
     instrumentBindings?: boolean | string[];
+    /**
+     * Native mode only: per-kind override of which bindings the SDK enriches on
+     * top of Cloudflare's own spans. Default: only kinds Cloudflare does not trace
+     * (`ai`, `vectorize`, `workflow`, `hyperdrive`, `analytics_engine`). Set
+     * `{ ai: false }` to opt out or `{ d1: true }` to force-enrich a covered kind.
+     * Ignored when `instrumentBindings` is set explicitly.
+     */
+    nativeEnrichment?: Partial<Record<BindingKind, boolean>>;
     /**
      * Select the Workers tracing plane. `auto` (default) uses Cloudflare's native
      * tracer when `ctx.tracing` is available and otherwise falls back to direct
      * OTLP export. `native` prefers the platform tracer but still fails open when
      * unavailable. `direct` always uses Heystack's fetch exporter.
      *
-     * Native mode deliberately disables Heystack root/fetch/binding
-     * instrumentation: Cloudflare already emits those spans, and running both
-     * creates duplicate, disconnected trace trees.
+     * Native mode creates no OTel provider and does not re-instrument what
+     * Cloudflare already spans (fetch, D1, KV, R2, DO, Queues, rate limit,
+     * service bindings). It enriches only the uncovered binding kinds (Workers AI,
+     * Vectorize, Workflows, Analytics Engine; Hyperdrive via `wrapSqlClient`) as
+     * native child spans, gated by `nativeEnrichment` / an explicit
+     * `instrumentBindings`.
      */
     nativeTracing?: "auto" | "native" | "direct";
+    /**
+     * Explicit Cloudflare tracer (`ctx.tracing`) for contexts that have none of
+     * their own, e.g. Durable Objects. Preferred over `ctx.tracing` when set.
+     */
+    tracing?: CloudflareTracing;
     /**
      * Head-sampling configuration. When omitted (or `rate` >= 1), all traces are
      * kept. When `rate` < 1, a deterministic FNV-1a hash of the trace ID decides
@@ -204,7 +232,9 @@ export interface WorkersConfig {
      *
      * Note: head sampling is parent-respecting, so an incoming request carrying a
      * sampled `traceparent` is still recorded even at `rate: 0` (it is not an
-     * absolute kill-switch; it governs only fresh/root traces).
+     * absolute kill-switch; it governs only fresh/root traces) — unless
+     * `trustInboundSampling: false`, which makes the rate decide for inbound
+     * traces too.
      *
      * When `remote: true`, the sampling rate is fetched once per isolate from
      * `{endpoint}/v1/sampling/config` on the first request. Cold-isolate spans
@@ -215,6 +245,25 @@ export interface WorkersConfig {
         rate?: number;
         remote?: boolean;
     };
+    /**
+     * Whether an inbound W3C `traceparent` sampled flag (`-01` / `-00`) decides
+     * keep/drop for the request's trace. Default `true` (parent-based sampling,
+     * so a browser→Worker trace samples consistently). Set `false` on a Worker
+     * that receives traffic from callers you don't control: the trace id is
+     * still continued (correlation is kept) but the keep/drop decision is made
+     * by THIS Worker's `sampling` rate over the trace id, so a client can't force
+     * recording with `-01` (or hide its requests with `-00`). Only meaningful when
+     * `sampling` is set (with no rate every trace is kept anyway).
+     */
+    trustInboundSampling?: boolean;
+    /**
+     * Cloudflare geo attributes recorded on the SERVER span from `req.cf`.
+     * `"country"` (default) records only `geo.country`; `"full"` also records
+     * `geo.region`, `geo.city` and `geo.asn`; `false` records none. The end-user
+     * IP (`client.address`) is separate and off by default — see
+     * {@link SpanPrivacyOptions.captureClientIp}.
+     */
+    captureGeo?: "country" | "full" | false;
     /**
      * LLM/gen_ai capture for outbound calls to known providers (OpenAI, Anthropic,
      * Mistral, Google, CF AI Gateway). Metadata (model, tokens, latency,
@@ -243,17 +292,36 @@ export interface WorkersConfig {
         redact?: (text: string) => string;
         maxContentChars?: number;
         gateways?: LLMGatewayConfig[];
+        /**
+         * The Cloudflare AI Gateway exports its own OTel spans for these calls.
+         * When true the SDK's LLM span is marked `heystack.ai.delegated` so the
+         * call is counted once (by the gateway). Opt-in: without it the SDK span is
+         * the counted one, so an AI call isn't lost if the gateway's own export
+         * isn't configured. The `cf-aig-otel-*` headers are sent either way.
+         */
+        gatewayExport?: boolean;
     };
+    /**
+     * Path templates for `http.route`, e.g. `["/users/:id", "/files/*"]` (first
+     * match wins; a trailing `*` matches the rest). If neither this nor
+     * `routeTemplate` is set, `http.route` is omitted and Heystack templates the
+     * path server-side.
+     */
+    routes?: string[];
+    /** Compute the `http.route` template per request; wins over `routes`. */
+    routeTemplate?: (req: Request) => string | undefined;
+    /**
+     * Hostnames (exact string or RegExp) that receive `traceparent` (and AI
+     * Gateway headers) on native-mode outbound fetches. Default: every host except
+     * the Heystack ingest endpoint. `[]` disables propagation.
+     */
+    propagateTargets?: Array<string | RegExp>;
 }
-/** Minimal public surface exposed by Cloudflare's Workers custom-spans API. */
-export interface CloudflareNativeSpan {
-    readonly isTraced: boolean;
-    setAttribute(key: string, value?: string | number | boolean): void;
-}
-/** `ExecutionContext.tracing` without importing the `cloudflare:workers` module. */
-export interface CloudflareNativeTracing {
-    enterSpan<T, A extends unknown[]>(name: string, callback: (span: CloudflareNativeSpan, ...args: A) => T, ...args: A): T;
-}
+export type { CloudflareSpan, CloudflareTracing };
+/** @deprecated Use {@link CloudflareSpan}. */
+export type CloudflareNativeSpan = CloudflareSpan;
+/** @deprecated Use {@link CloudflareTracing}. */
+export type CloudflareNativeTracing = CloudflareTracing;
 /**
  * A `BasicTracerProvider` with the underlying `HeystackSpanExporter` attached so
  * flush paths can drain its in-flight fetches directly (the OTel processor's
@@ -272,10 +340,12 @@ export type HeystackTracerProvider = BasicTracerProvider & {
  * must drain the exporter — `await provider.heystackExporter.forceFlush()` (or
  * `flushHeystack()`), not just `provider.forceFlush()`.
  */
-export declare function createTracerProvider(config: HeystackOptions & {
+export declare function createTracerProvider(config: HeystackOptions & SpanPrivacyOptions & {
     sampling?: {
         rate?: number;
+        remote?: boolean;
     };
+    trustInboundSampling?: boolean;
 }): HeystackTracerProvider;
 /**
  * An AsyncLocalStorage-backed ContextManager for the /workers entry. When the
@@ -483,6 +553,22 @@ export declare function wrapDurableObjectClass<C extends {
 export declare function wrapWorkflowEntrypointClass<C extends {
     readonly prototype: object;
 }>(cls: C, opts?: InstrumentClassesOpts): C;
+/**
+ * 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 declare function wrapWorkerEntrypointClass<T extends new (...a: any[]) => object>(cls: T, cfg: WorkersConfig): T;
 /**
  * Run `fn` inside a new child span named `name`. The span is automatically
  * parented to the currently-active span (via `context.active()`), started
@@ -502,8 +588,8 @@ export declare function withSpan<T>(name: string, attrs: Record<string, string |
  * without `nodejs_compat`: the explicit context cannot be lost across async
  * boundaries. It falls back to the regular OTel tracer outside Cloudflare.
  */
-export declare function withCloudflareSpan<T>(ctx: ExecutionContext | CloudflareNativeTracing, name: string, fn: (span: Span) => T | Promise<T>): Promise<T>;
-export declare function withCloudflareSpan<T>(ctx: ExecutionContext | CloudflareNativeTracing, name: string, attrs: Record<string, string | number | boolean>, fn: (span: Span) => T | Promise<T>): Promise<T>;
+export declare function withCloudflareSpan<T>(ctx: ExecutionContext | CloudflareTracing, name: string, fn: (span: Span) => T | Promise<T>): Promise<T>;
+export declare function withCloudflareSpan<T>(ctx: ExecutionContext | CloudflareTracing, name: string, attrs: Record<string, string | number | boolean>, fn: (span: Span) => T | Promise<T>): Promise<T>;
 /**
  * Add a named event (with optional attributes) to the currently-active span.
  * No-op when no span is active.
@@ -523,3 +609,6 @@ export { llmRequestAttrs as genAiRequestAttrs } from "./llm-enrich.js";
  */
 export { llmResponseAttrs as genAiResponseAttrs } from "./llm-enrich.js";
 export type { LLMGatewayConfig, LLMProvider } from "./llm-enrich.js";
+export { NATIVELY_COVERED, NATIVE_PROPAGATES_EXTERNAL, shouldEnrichNatively, wrapSqlClient };
+export { matchRoute } from "./workers-routes.js";
+export type { BindingKind };