@heystack/otel 0.6.0 → 0.8.0

package/README.md

@@ -90,7 +90,7 @@ export default instrument(
     getUser: (req) => ({
       id: req.headers.get("x-user-id") ?? undefined,
     }),
-    instrumentBindings: true,  // auto-trace D1/KV/R2/Vectorize
+    instrumentBindings: true,  // auto-trace D1/KV/R2/Vectorize/AI/Queues/Service bindings
   },
 );
 ```
@@ -116,8 +116,8 @@ Set the key as a secret: `wrangler secret put HEYSTACK_API_KEY`.
 | `service` | `string` | **Required.** Service name that appears in the Heystack console. |
 | `apiKey` | `string?` | Defaults to `env.HEYSTACK_API_KEY`. |
 | `getUser` | `(req: Request) => { id?, session?, requestId? } \| undefined` | Called per request. `id` → `enduser.id`, `session` → `session.id`, `requestId` → `http.request.id` (falls back to the `cf-ray` header). |
-| `instrumentBindings` | `boolean \| string[]` | `true` = auto child spans for all detected D1/KV/R2/Vectorize bindings; `string[]` = only the named bindings. Default `false`. |
-| `sampling` | `{ rate?: number }` | Head-sampling rate 0–1. `1` (default) keeps everything. `0.2` keeps ~20% of fresh root traces. Parent-respecting: a request that arrives with an inbound sampled `traceparent` is always recorded regardless of the rate. See [Head sampling](#head-sampling) below. |
+| `instrumentBindings` | `boolean \| string[]` | `true` = auto child spans for all detected D1 / KV / R2 / Vectorize / Workers AI / Queue producer / Service binding bindings; `string[]` = only the named bindings. Default `false`. |
+| `sampling` | `{ rate?: number } \| { remote: true }` | Head-sampling configuration. `{ rate }`: keep a deterministic fraction of fresh root traces (0–1; default `1` = keep all). `{ remote: true }`: fetch the rate from the Heystack config endpoint instead — lets you change it centrally without redeploying. Cold isolates keep all traffic until the first config fetch resolves; fails open if the config can't be reached. Parent-respecting in both modes: a request arriving with a sampled `traceparent` is always recorded. See [Head sampling](#head-sampling) below. |
 | `waitUntil` | `(p: Promise<unknown>) => void` | Override the isolate keep-alive hook; defaults to the auto-detected `ctx.waitUntil`. |
 | `endpoint` | `string?` | Override the ingest endpoint (advanced). |
 
@@ -138,6 +138,19 @@ The sampler is **deterministic by trace ID**: the same trace always makes the sa
 
 The `rate` governs **fresh root traces only** (no inbound `traceparent`, or `traceparent` with `sampled=0`). A request arriving with a sampled inbound `traceparent` (`sampled=1`) is always recorded — the parent's decision is respected, so a distributed trace is never split mid-flight by the child's sample rate.
 
+### Remote sampling
+
+`sampling: { remote: true }` lets Heystack control the rate centrally — change it from the dashboard without redeploying:
+
+```ts
+export default instrument(worker, {
+  service: "my-api",
+  sampling: { remote: true },
+});
+```
+
+On startup the worker fetches its configured rate from the Heystack config endpoint. **Cold isolates keep all traffic until that first fetch resolves** (fails open — nothing is dropped while loading). If the config endpoint can't be reached, the worker keeps everything. The same parent-respecting rule applies: a request with an inbound sampled `traceparent` is always recorded regardless of the fetched rate.
+
 ### Automatic tracing
 
 `instrument()` traces the following automatically, with no additional config:
@@ -146,7 +159,7 @@ The `rate` governs **fresh root traces only** (no inbound `traceparent`, or `tra
 - **Outbound `fetch`** — each outbound subrequest while a request span is active gets a CLIENT child span (`http.request.method`, `url.full`, `server.address`, `http.response.status_code`). A W3C `traceparent` header is injected into the subrequest so a downstream Heystack-instrumented service continues the same trace (distributed tracing across services). The exporter's own ingest POST is never traced.
 - **Queue consumers (`queue`)** — a CONSUMER span per batch, with `messaging.destination.name` (queue name) and `messaging.batch.message_count`.
 - **Scheduled handlers (`scheduled`)** — an INTERNAL span per invocation, with `controller.cron`.
-- **Binding calls** (when `instrumentBindings` is set) — a child span for every D1 query (`db.statement`), KV read/write, R2 operation, and Vectorize query.
+- **Binding calls** (when `instrumentBindings` is set) — a child span for every D1 query (`db.statement`), KV read/write, R2 operation, Vectorize query, Workers AI inference (`gen_ai.*` attributes including model name and token usage), Queue `.send`/`.sendBatch` (PRODUCER spans with `messaging.*` attributes), and Service binding `.fetch` calls (CLIENT spans with `traceparent` injected so calls to other Workers stitch into the same distributed trace).
 
 ### Client enrichment
 
@@ -292,6 +305,8 @@ As belt-and-suspenders the exporter also drops any span whose HTTP target points
 
 ## Migration / versioning
 
+- **`0.8.0`** — **`/workers`: Workers AI, Queue producer, and Service binding instrumentation.** `instrumentBindings: true` now auto-wraps three additional binding types: `env.AI.run()` emits CLIENT spans with `gen_ai.system`, `gen_ai.request.model`, and `gen_ai.usage.input_tokens`/`output_tokens` (streaming results are never consumed); Queue `.send`/`.sendBatch` emit PRODUCER spans with `messaging.*` attributes including batch size; Service binding `.fetch` emits a CLIENT span and injects a W3C `traceparent` header into the outgoing request so calls to other Workers appear in the same distributed trace. `startSpan` factory now accepts an optional `SpanKind` for correct CLIENT/PRODUCER categorisation. No breaking changes.
+- **`0.7.0`** — **`/workers`: remote sampling (`sampling: { remote: true }`).** New `sampling` variant that fetches the head-sampling rate from the Heystack config endpoint at runtime, so you can change it from the console without redeploying. Cold isolates keep all traffic until the first config fetch resolves (fails open). If the config endpoint is unreachable, the worker keeps everything. Same parent-respecting rule as `sampling: { rate }`. No breaking changes; existing `sampling: { rate }` configs are unchanged.
 - **`0.6.0`** — **`/workers`: head sampling (`sampling: { rate }`).** New optional `WorkersConfig` field: `sampling.rate` (0–1, default `1`). Keeps a deterministic fraction of fresh root traces — the drop decision is made in the worker before export (no egress, no ingest cost). Parent-respecting: requests arriving with a sampled `traceparent` are always recorded. Consistent with server-side sampling (same trace-ID hash). No breaking changes; all new options are optional. See [Head sampling](#head-sampling).
 - **`0.5.0`** — **`/workers`: identity enrichment, binding tracing, outbound-fetch tracing, manual span helpers.** New `WorkersConfig` options: `getUser` (attach `enduser.id`/`session.id`/`http.request.id` per request from a synchronous callback), `instrumentBindings` (auto child spans for D1/KV/R2/Vectorize — `true` = all detected, or a `string[]` to select). Outbound `fetch` calls made inside a traced handler automatically get CLIENT child spans with `traceparent` injection (distributed tracing across services). New ergonomic exports from `/workers`: `withSpan(name, attrs?, fn)` runs a function inside a named child span (auto-parented, exceptions recorded, `span.end()` in `finally`); `addEvent(name, attrs?)` adds an event to the active span. No breaking changes; all new options are optional.
 - **`0.4.3`** — **feedback-loop guard extended to the Node path (cost fix).** The self-instrumentation loop the Workers path fixed in 0.3.1/0.3.2 was still live on plain Node / Next-on-Node: the OTLP-over-`http` exporter's `POST /v1/traces` was auto-instrumented and re-exported, so ~77% of ingested spans in production were the exporter tracing itself — needless ingest + ClickHouse compute. 0.4.3 ignores ingest-host requests in the HTTP/undici auto-instrumentations **and** filters self-spans at the exporter boundary (covers caller-supplied `instrumentations` too). The hostname matcher is now a shared module used by both `/node` and `/workers`. No API change. **Action: upgrade and redeploy any Node/Next-on-Node app** — it cuts ingested span volume sharply.

package/dist/workers-bindings.d.ts

@@ -1,33 +1,51 @@
-import { type Span } from "@opentelemetry/api";
+import { SpanKind, type Span } from "@opentelemetry/api";
 export interface InstrumentBindingsOpts {
     /**
      * Factory that creates and starts a new child span. Called at binding method
      * invocation time (inside the traced handler scope), so `context.active()`
      * at that moment correctly parents to the root span.
      *
-     * For integration: pass `(name, attrs) => tracer.startSpan(name, { attributes: attrs }, context.active())`.
+     * For integration: pass `(name, attrs, kind) => tracer.startSpan(name, { attributes: attrs, kind }, context.active())`.
      * For unit tests: inject a fake so no global provider is required.
      */
-    startSpan: (name: string, attrs: Record<string, unknown>) => Span;
+    startSpan: (name: string, attrs: Record<string, unknown>, kind?: SpanKind) => Span;
     /**
-     * `true`  → auto-detect and wrap all D1/KV/R2/Vectorize bindings.
+     * `true`  → auto-detect and wrap all D1/KV/R2/Vectorize/AI/Queue/Service bindings.
      * `string[]` → only wrap bindings whose env key is listed.
      */
     select: boolean | string[];
 }
+/**
+ * Build a new args array for `fetch(input, init?)` with a `traceparent` header
+ * injected WITHOUT mutating the caller's original Request or init object.
+ *
+ * - `Request` first arg → rebuilt as `new Request(original, { headers })`.
+ * - String/URL first arg → spread a new init object with an augmented Headers.
+ */
+export declare function injectTraceparentArgs(args: any[], traceparent: string): any[];
 /**
  * Wrap an env object's Cloudflare bindings so that each binding operation
  * emits a child span under the currently-active OTel context.
  *
- * Detects binding type by duck-typing (D1: `prepare`; KV: `get`+`put`+`list`;
- * R2: `get`+`put`+`head`; Vectorize: `query`+`upsert`). Unrecognised bindings
- * are passed through unchanged.
+ * Detects binding type by duck-typing:
+ * - D1: `prepare`
+ * - R2: `get`+`put`+`head`
+ * - KV: `get`+`put`+`list`
+ * - Vectorize: `query`+`upsert`
+ * - Workers AI: `run` (without `prepare`)
+ * - Queue producer: `send`+`sendBatch`
+ * - Service binding / Fetcher: `fetch` (last branch; most generic)
+ *
+ * Unrecognised bindings are passed through unchanged.
  *
  * Each wrapped binding is a `Proxy` over the original — non-wrapped prototype
  * methods fall through to the real binding so no functionality is lost.
  *
+ * Service-binding spans inject a W3C `traceparent` header into outgoing
+ * requests so calls to other Workers stitch into one distributed trace.
+ *
  * @param env  - The Worker env / binding bag.
- * @param opts - `startSpan` factory + `select` filter.
+ * @param opts - `startSpan` factory (now accepts optional `SpanKind`) + `select` filter.
  * @returns A shallow copy of `env` with selected bindings replaced by proxies.
  */
 export declare function instrumentEnv<E extends Record<string, unknown>>(env: E, opts: InstrumentBindingsOpts): E;

package/dist/workers-bindings.js

@@ -1,13 +1,14 @@
 // ---------------------------------------------------------------------------
 // Cloudflare binding instrumentation for @heystack/otel/workers.
 //
-// Wraps D1, KV, R2, and Vectorize bindings with OTel child spans so that
-// every binding operation is visible as a child of the active request span.
+// Wraps D1, KV, R2, Vectorize, Workers AI, Queue producers, and Service
+// bindings with OTel child spans so that every binding operation is visible
+// as a child of the active request span.
 //
 // WinterCG-safe: no `node:*` imports. Span factory is injected so the logic
 // is pure and unit-testable without a global provider.
 // ---------------------------------------------------------------------------
-import { context, SpanStatusCode } from "@opentelemetry/api";
+import { context, SpanKind, SpanStatusCode } from "@opentelemetry/api";
 import { isTracingSuppressed } from "@opentelemetry/core";
 // ---------------------------------------------------------------------------
 // Duck-type detectors — conservative; require the distinctive method set
@@ -31,6 +32,24 @@ function isVectorizeLike(b) {
     return (typeof b?.query === "function" &&
         typeof b?.upsert === "function");
 }
+/**
+ * Workers AI: has `run` but NOT `prepare` (which would match D1 first anyway).
+ * The `prepare` exclusion is defensive — D1 is already matched before this branch.
+ */
+function isWorkersAILike(b) {
+    return (typeof b?.run === "function" &&
+        typeof b?.prepare !== "function");
+}
+/** Queue producer: exposes both `send` and `sendBatch`. */
+function isQueueLike(b) {
+    return (typeof b?.send === "function" &&
+        typeof b?.sendBatch === "function");
+}
+/** Service binding / Fetcher: last branch — anything with `.fetch`. Prior branches
+ *  exclude D1/R2/KV/Vectorize/AI/Queue, so order alone is sufficient. */
+function isServiceLike(b) {
+    return typeof b?.fetch === "function";
+}
 // ---------------------------------------------------------------------------
 // Span lifecycle helper
 // ---------------------------------------------------------------------------
@@ -161,21 +180,153 @@ function wrapVectorize(binding, opts, indexName) {
     });
 }
 // ---------------------------------------------------------------------------
+// Workers AI wrapper
+// ---------------------------------------------------------------------------
+function wrapWorkersAI(binding, opts, _name) {
+    return makeProxy(binding, {
+        run: async (...args) => {
+            if (isTracingSuppressed(context.active())) {
+                return binding.run(...args);
+            }
+            const attrs = {
+                "gen_ai.system": "cloudflare.workers_ai",
+            };
+            if (typeof args[0] === "string") {
+                attrs["gen_ai.request.model"] = args[0];
+            }
+            const span = opts.startSpan("AI run", attrs, SpanKind.CLIENT);
+            try {
+                const result = await binding.run(...args);
+                // Best-effort usage extraction — never read/await/tee the stream.
+                try {
+                    if (result &&
+                        typeof result === "object" &&
+                        !(result instanceof ReadableStream) &&
+                        typeof result.usage === "object") {
+                        const usage = result.usage;
+                        if (typeof usage.prompt_tokens === "number") {
+                            span.setAttribute("gen_ai.usage.input_tokens", usage.prompt_tokens);
+                        }
+                        if (typeof usage.completion_tokens === "number") {
+                            span.setAttribute("gen_ai.usage.output_tokens", usage.completion_tokens);
+                        }
+                    }
+                }
+                catch {
+                    // 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();
+            }
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// Queue producer wrapper
+// ---------------------------------------------------------------------------
+function wrapQueue(binding, opts, name) {
+    const baseAttrs = {
+        "messaging.system": "cloudflare_queues",
+        "messaging.destination.name": name,
+    };
+    return makeProxy(binding, {
+        send: async (...args) => {
+            if (isTracingSuppressed(context.active())) {
+                return binding.send(...args);
+            }
+            const span = opts.startSpan("Queue send", { ...baseAttrs, "messaging.operation": "send" }, SpanKind.PRODUCER);
+            return runWithSpan(span, () => binding.send(...args));
+        },
+        sendBatch: async (...args) => {
+            if (isTracingSuppressed(context.active())) {
+                return binding.sendBatch(...args);
+            }
+            const batchAttrs = {
+                ...baseAttrs,
+                "messaging.operation": "sendBatch",
+            };
+            if (Array.isArray(args[0])) {
+                batchAttrs["messaging.batch.message_count"] = args[0].length;
+            }
+            const span = opts.startSpan("Queue sendBatch", batchAttrs, SpanKind.PRODUCER);
+            return runWithSpan(span, () => binding.sendBatch(...args));
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// Service binding / Fetcher wrapper + traceparent injection
+// ---------------------------------------------------------------------------
+/**
+ * Build a new args array for `fetch(input, init?)` with a `traceparent` header
+ * injected WITHOUT mutating the caller's original Request or init object.
+ *
+ * - `Request` first arg → rebuilt as `new Request(original, { headers })`.
+ * - String/URL first arg → spread a new init object with an augmented Headers.
+ */
+export function injectTraceparentArgs(args, traceparent) {
+    const [input, ...rest] = args;
+    if (input instanceof Request) {
+        const headers = new Headers(input.headers);
+        headers.set("traceparent", traceparent);
+        return [new Request(input, { headers }), ...rest];
+    }
+    // String or URL
+    const init = { ...(rest[0] ?? {}) };
+    const headers = new Headers(init.headers);
+    headers.set("traceparent", traceparent);
+    init.headers = headers;
+    return [input, init];
+}
+function wrapService(binding, opts, name) {
+    return makeProxy(binding, {
+        fetch: async (...args) => {
+            if (isTracingSuppressed(context.active())) {
+                return binding.fetch(...args);
+            }
+            const span = opts.startSpan(`Service ${name} fetch`, { "peer.service": name }, SpanKind.CLIENT);
+            const sc = span.spanContext();
+            const traceparent = `00-${sc.traceId}-${sc.spanId}-01`;
+            const injectedArgs = injectTraceparentArgs(args, traceparent);
+            return runWithSpan(span, () => binding.fetch(...injectedArgs));
+        },
+    });
+}
+// ---------------------------------------------------------------------------
 // Main export
 // ---------------------------------------------------------------------------
 /**
  * Wrap an env object's Cloudflare bindings so that each binding operation
  * emits a child span under the currently-active OTel context.
  *
- * Detects binding type by duck-typing (D1: `prepare`; KV: `get`+`put`+`list`;
- * R2: `get`+`put`+`head`; Vectorize: `query`+`upsert`). Unrecognised bindings
- * are passed through unchanged.
+ * Detects binding type by duck-typing:
+ * - D1: `prepare`
+ * - R2: `get`+`put`+`head`
+ * - KV: `get`+`put`+`list`
+ * - Vectorize: `query`+`upsert`
+ * - Workers AI: `run` (without `prepare`)
+ * - Queue producer: `send`+`sendBatch`
+ * - Service binding / Fetcher: `fetch` (last branch; most generic)
+ *
+ * Unrecognised bindings are passed through unchanged.
  *
  * Each wrapped binding is a `Proxy` over the original — non-wrapped prototype
  * methods fall through to the real binding so no functionality is lost.
  *
+ * Service-binding spans inject a W3C `traceparent` header into outgoing
+ * requests so calls to other Workers stitch into one distributed trace.
+ *
  * @param env  - The Worker env / binding bag.
- * @param opts - `startSpan` factory + `select` filter.
+ * @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) {
@@ -199,6 +350,15 @@ export function instrumentEnv(env, opts) {
         else if (isVectorizeLike(binding)) {
             result[key] = wrapVectorize(binding, opts, key);
         }
+        else if (isWorkersAILike(binding)) {
+            result[key] = wrapWorkersAI(binding, opts, key);
+        }
+        else if (isQueueLike(binding)) {
+            result[key] = wrapQueue(binding, opts, key);
+        }
+        else if (isServiceLike(binding)) {
+            result[key] = wrapService(binding, opts, key);
+        }
         // Unrecognised bindings are left as-is.
     }
     return result;

package/dist/workers-sampler.d.ts

@@ -2,12 +2,34 @@ import { type Sampler, type SamplingResult } from "@opentelemetry/sdk-trace-base
 import type { Context, Attributes, Link, SpanKind } from "@opentelemetry/api";
 export declare function fnv01(s: string): number;
 export declare function traceKept(traceId: string, rate: number): boolean;
+/** Test-only: set the remote rate directly. */
+export declare function __setRemoteRate(n: number): void;
+/** Test-only: read the current remote rate. */
+export declare function __getRemoteRate(): number;
 export declare class HeystackRatioSampler implements Sampler {
     private readonly rate;
-    constructor(rate: number);
+    constructor(rate: number | (() => number));
     shouldSample(_ctx: Context, traceId: string, _name: string, _kind: SpanKind, _attrs: Attributes, _links: Link[]): SamplingResult;
     toString(): string;
 }
+/**
+ * Fetch the sampling rate from the Heystack ingest config endpoint and update
+ * the module-level `_remoteRate` ref. Call once per isolate (guarded in
+ * `workers.ts` via `_remoteSamplingKicked`). Uses the provided `fetchImpl`
+ * (the captured pre-patch fetch) so the GET is never re-entered by outbound
+ * fetch instrumentation and is wrapped in `suppressTracing` at the call site
+ * in `workers.ts` (belt-and-suspenders against self-tracing).
+ *
+ * Fail-open: any network failure, non-200, or parse error leaves `_remoteRate`
+ * at its current value (initially 1 = keep-all). Remote sampling must never
+ * drop telemetry due to a config-service outage.
+ */
+export declare function loadRemoteSamplingRate(opts: {
+    endpoint: string;
+    apiKey: string;
+    fetchImpl: typeof fetch;
+}): Promise<void>;
 export declare function makeSampler(sampling?: {
     rate?: number;
+    remote?: boolean;
 }): Sampler;

package/dist/workers-sampler.js

@@ -16,23 +16,70 @@ export function traceKept(traceId, rate) {
         return false;
     return fnv01(traceId) < rate;
 }
+// Module-level mutable ref for the remote-loaded rate. Starts at 1 (keep-all)
+// so cold-isolate requests are fully preserved until the config fetch resolves.
+const _remoteRate = { value: 1 };
+/** Test-only: set the remote rate directly. */
+export function __setRemoteRate(n) {
+    _remoteRate.value = n;
+}
+/** Test-only: read the current remote rate. */
+export function __getRemoteRate() {
+    return _remoteRate.value;
+}
 export class HeystackRatioSampler {
     rate;
     constructor(rate) {
         this.rate = rate;
     }
     shouldSample(_ctx, traceId, _name, _kind, _attrs, _links) {
+        const rate = typeof this.rate === "function" ? this.rate() : this.rate;
         return {
-            decision: traceKept(traceId, this.rate)
+            decision: traceKept(traceId, rate)
                 ? SamplingDecision.RECORD_AND_SAMPLED
                 : SamplingDecision.NOT_RECORD,
         };
     }
     toString() {
-        return `HeystackRatioSampler{${this.rate}}`;
+        const r = typeof this.rate === "function" ? this.rate() : this.rate;
+        return `HeystackRatioSampler{${r}}`;
+    }
+}
+/**
+ * Fetch the sampling rate from the Heystack ingest config endpoint and update
+ * the module-level `_remoteRate` ref. Call once per isolate (guarded in
+ * `workers.ts` via `_remoteSamplingKicked`). Uses the provided `fetchImpl`
+ * (the captured pre-patch fetch) so the GET is never re-entered by outbound
+ * fetch instrumentation and is wrapped in `suppressTracing` at the call site
+ * in `workers.ts` (belt-and-suspenders against self-tracing).
+ *
+ * Fail-open: any network failure, non-200, or parse error leaves `_remoteRate`
+ * at its current value (initially 1 = keep-all). Remote sampling must never
+ * drop telemetry due to a config-service outage.
+ */
+export async function loadRemoteSamplingRate(opts) {
+    try {
+        const url = `${opts.endpoint.replace(/\/+$/, "")}/v1/sampling/config`;
+        const res = await opts.fetchImpl(url, {
+            headers: { Authorization: `Bearer ${opts.apiKey}` },
+        });
+        if (!res.ok)
+            return; // fail open — keep current rate
+        const cfg = (await res.json());
+        const r = Number(cfg?.trace_sample_rate);
+        if (Number.isFinite(r) && r >= 0 && r <= 1)
+            _remoteRate.value = r;
+    }
+    catch {
+        /* fail open: leave rate at keep-all */
     }
 }
 export function makeSampler(sampling) {
+    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) });
+    }
     const rate = sampling?.rate;
     if (rate === undefined || rate >= 1)
         return new AlwaysOnSampler();

package/dist/workers.d.ts

@@ -168,9 +168,15 @@ 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).
+     *
+     * When `remote: true`, the sampling rate is fetched once per isolate from
+     * `{endpoint}/v1/sampling/config` on the first request. Cold-isolate spans
+     * are kept (rate=1) until the fetch resolves. On any failure the rate stays
+     * at keep-all (fail-open). Incompatible with inline `rate` (remote wins).
      */
     sampling?: {
         rate?: number;
+        remote?: boolean;
     };
 }
 /**

package/dist/workers.js

@@ -13,10 +13,10 @@ import { ROOT_CONTEXT } from "@opentelemetry/api";
 import { Resource } from "@opentelemetry/resources";
 import { BasicTracerProvider, SimpleSpanProcessor, } from "@opentelemetry/sdk-trace-base";
 import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
-import { buildExporterConfig } from "./core.js";
+import { buildExporterConfig, DEFAULT_ENDPOINT } from "./core.js";
 import { isSelfSpanAttrs, safeHostname } from "./self-span.js";
 import { instrumentEnv } from "./workers-bindings.js";
-import { makeSampler } from "./workers-sampler.js";
+import { makeSampler, loadRemoteSamplingRate } from "./workers-sampler.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
@@ -696,7 +696,10 @@ export async function flushHeystack() {
 /** Reset the singleton global provider. Internal/testing helper. */
 export function __resetProvider() {
     _provider = null;
+    _remoteSamplingKicked = false;
 }
+/** Guard: the remote sampling config GET fires at most once per isolate. */
+let _remoteSamplingKicked = false;
 let warnedNoKey = false;
 function warnOnceNoKey() {
     if (warnedNoKey)
@@ -763,6 +766,22 @@ export function instrument(handler, config) {
             if (!s)
                 return originalFetch(req, env, ctx);
             const { provider, tracer } = s;
+            // Once per isolate: kick off the remote sampling config GET so the rate
+            // is available for subsequent requests without a redeploy. Uses the
+            // captured pre-patch fetch under suppressTracing — never self-traced,
+            // never looped. Fail-open: any error leaves the rate at 1 (keep-all).
+            if (config.sampling?.remote && !_remoteSamplingKicked) {
+                _remoteSamplingKicked = true;
+                const resolvedKey = config.apiKey ?? env?.HEYSTACK_API_KEY;
+                if (resolvedKey) {
+                    const ep = config.endpoint ?? DEFAULT_ENDPOINT;
+                    ctx.waitUntil(context.with(suppressTracing(context.active()), () => loadRemoteSamplingRate({
+                        endpoint: ep,
+                        apiKey: resolvedKey,
+                        fetchImpl: _originalFetch ?? fetch,
+                    })));
+                }
+            }
             const url = new URL(req.url);
             // FR5: continue an inbound W3C traceparent so tap→server is one trace.
             const parent = parseTraceparent(req.headers.get("traceparent"));
@@ -819,7 +838,7 @@ export function instrument(handler, config) {
             if (config.instrumentBindings) {
                 const binTracer = trace.getTracer("heystack");
                 handlerEnv = instrumentEnv(env, {
-                    startSpan: (name, attrs) => binTracer.startSpan(name, { attributes: attrs }, context.active()),
+                    startSpan: (name, attrs, kind) => binTracer.startSpan(name, { attributes: attrs, kind }, context.active()),
                     select: config.instrumentBindings,
                 });
             }

package/package.json

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