@heystack/otel 0.2.1 → 0.3.2

package/README.md

@@ -13,7 +13,7 @@ Always read your key from the environment — never paste it into source:
 HEYSTACK_API_KEY=sk_live_…
 ```
 
-> **Requires `@heystack/otel` `>=0.2.0`.** See [Migration](#migration--versioning) below.
+> **Requires `@heystack/otel` `>=0.3.0` (prefer `>=0.3.2`).** 0.3.2 fixes the no-op `suppressTracing` (feedback-loop guard) on the Workers/Next-on-OpenNext path and adds the Workers `nodejs_compat` requirement. See [Migration](#migration--versioning) below.
 
 ## Runtime matrix
 
@@ -36,6 +36,24 @@ initHeystack({ apiKey: process.env.HEYSTACK_API_KEY, service: "my-app" });
 
 This enables auto-instrumentations (HTTP, Express, etc.) so you get spans without manual wiring.
 
+### Slimming down auto-instrumentations (cost)
+
+The default `getNodeAutoInstrumentations()` eagerly patches **~40 libraries** (HTTP, DNS, fs, net, gRPC, and every popular DB/HTTP client). That adds startup time and per-call overhead even for libraries your app never uses. To load only what you need, pass your own `instrumentations` array:
+
+```ts
+import { initHeystack } from "@heystack/otel/node";
+import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";
+import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express";
+
+initHeystack({
+  apiKey: process.env.HEYSTACK_API_KEY,
+  service: "my-app",
+  instrumentations: [new HttpInstrumentation(), new ExpressInstrumentation()],
+});
+```
+
+`instrumentations` defaults to `[getNodeAutoInstrumentations()]`. Passing your own array replaces the default entirely (it's ignored when `autoInstrument: false`). `initHeystack` is also **idempotent** as of 0.3.2 — calling it again returns the already-started SDK (no duplicate instrumentations or signal handlers, which matters across Next dev-server reloads).
+
 ## Next.js (any deploy target, including Cloudflare/OpenNext)
 
 In `instrumentation.ts` at the project root:
@@ -70,6 +88,18 @@ export default instrument(
 );
 ```
 
+As of **0.3.0** `instrument()` registers the **global** tracer provider and creates the per-request SERVER span via the global tracer, so nested spans created through the global `trace.getTracer()` API (framework/library/manual) also export — you get a trace tree, not a lone SERVER span.
+
+> **Requires `nodejs_compat` on workerd.** As of **0.3.2** the SDK registers an OpenTelemetry **ContextManager** at init (see below), backed by `AsyncLocalStorage` from `node:async_hooks`. On Cloudflare Workers that means your `wrangler.toml` must enable the Node.js compatibility flag:
+> ```toml
+> compatibility_flags = ["nodejs_compat"]
+> ```
+> If `node:async_hooks` is unavailable, the SDK transparently falls back to a synchronous stack-based ContextManager (no extra dependency) — suppression still works, but cross-`await` parent linking and per-request context isolation degrade to best-effort.
+
+### Why a ContextManager (0.3.2)
+
+`context.with(...)` in OpenTelemetry is a **no-op unless a ContextManager is registered** with the global API. Before 0.3.2 the Workers path registered only a tracer provider, so `suppressTracing()` — the primary defence against the self-trace feedback loop — silently did nothing in production (the exporter's own `POST /v1/traces` could be re-traced by host fetch auto-instrumentation, looping). As of **0.3.2** the SDK registers a ContextManager exactly once at init. With `AsyncLocalStorageContextManager` (the default, on Node and on workerd under `nodejs_compat`) you also get **cross-`await` parent→child span linking** and **per-request context isolation** — concurrent requests no longer share or clobber the active span.
+
 `instrument()` must be the **outermost** wrapper if other middleware also wraps the handler, so the request span covers everything inside:
 
 ```ts
@@ -78,17 +108,64 @@ export default instrument(withOtherMiddleware(worker), { service: "my-worker" })
 
 Set the key as a secret: `wrangler secret put HEYSTACK_API_KEY`.
 
+As of **0.3.1** `instrument()` **forwards every other handler your Worker exports** — `queue`, `scheduled`, `tail`, etc. — untouched, so wrapping never drops a handler Cloudflare requires for deploy (it previously returned only `{ fetch }`, which broke Queue/Cron Workers). On top of forwarding, `queue` and `scheduled` are themselves traced when present: each gets a root span via the global tracer (`queue <queueName>` as a CONSUMER span with batch attributes; `scheduled <cron>` as an INTERNAL span with the cron attribute), flushed via `ctx.waitUntil` just like `fetch`.
+
+### Durable Objects are NOT covered by `instrument()`
+
+`instrument()` wraps the keys of the **default-export handler object** (`fetch`/`queue`/`scheduled`/… ). **Durable Objects are separate named class exports**, so spreading the handler object does not touch them — a DO's `fetch`/`alarm` methods run **untraced** even when your Worker's default export is wrapped.
+
+To trace a Durable Object, instrument it manually with the global tracer (which `instrument()` / `initHeystackWorkers()` already registered) and flush per invocation:
+
+```ts
+import { trace, SpanKind, context } from "@opentelemetry/api";
+import { flushHeystack } from "@heystack/otel/workers";
+
+export class Counter {
+  async fetch(req: Request): Promise<Response> {
+    const tracer = trace.getTracer("heystack");
+    const span = tracer.startSpan(`DO ${new URL(req.url).pathname}`, {
+      kind: SpanKind.SERVER,
+    });
+    try {
+      return await context.with(trace.setSpan(context.active(), span), async () => {
+        // ...your DO logic...
+        return new Response("ok");
+      });
+    } finally {
+      span.end();
+      this.state.waitUntil(flushHeystack()); // ensure the export POST completes
+    }
+  }
+}
+```
+
+The default export still needs to be wrapped with `instrument()` (or `initHeystackWorkers()` called) so the global provider + ContextManager are registered before the DO runs.
+
 ## Flushing
 
 On Workers/edge the export is a `fetch()` POST, and the isolate can be torn down the instant your handler returns. **You must let that POST complete or the trace is silently dropped** — this is the #1 cause of flaky Workers tracing. `flushHeystack()` and `instrument()`'s built-in flush both await the in-flight fetch (not just the OTel span processor, which does *not* wait for it).
 
 - **Standalone Workers (`instrument()`)** — flushes automatically. After the response it `ctx.waitUntil`s a promise that drains both the span processor and the exporter's in-flight fetch, so the POST finishes before the isolate is killed. No action needed.
-- **Next on workerd (`registerHeystack`)** — there's no per-request `ExecutionContext`, so spans are **not** auto-flushed. For guaranteed delivery, `import { flushHeystack } from "@heystack/otel/workers"` and call it from a response hook (or `ctx.waitUntil(flushHeystack())` if you have a ctx) after handling a request. `flushHeystack()` awaits the export fetch.
+- **Next on Cloudflare/OpenNext (`registerHeystack`)** — as of **0.3.0** this flushes automatically when `@opennextjs/cloudflare` is present: the export runs inside the Cloudflare request context, so the exporter borrows that request's `ctx.waitUntil` (via OpenNext's `getCloudflareContext`) to keep the isolate alive until the POST completes. **No manual hook needed.** For other workerd setups *without* `@opennextjs/cloudflare`, `import { flushHeystack } from "@heystack/otel/workers"` and call it from a response hook (or `ctx.waitUntil(flushHeystack())` if you have a ctx) — or pass an explicit `waitUntil` to `initHeystackWorkers` (highest priority). `flushHeystack()` awaits the export fetch.
 - **Node (`initHeystack`)** — flushes on `SIGTERM`/`SIGINT` automatically.
 
+## No feedback loop with host fetch auto-instrumentation
+
+As of **0.3.1** the exporter **suppresses tracing for its own ingest POST**, and **0.3.2 makes that suppression actually take effect in production**. On Next/OpenNext the host auto-instruments outbound `fetch`, so without this the exporter's `POST /v1/traces` became a CLIENT span → exported → re-captured → a sustained loop (wall-to-wall identical `fetch POST .../v1/traces` spans). The POST runs inside an OpenTelemetry tracing-suppressed context (`suppressTracing`) — but `context.with()` is a no-op unless a ContextManager is registered, which 0.3.1 did not do, so suppression silently did nothing. **0.3.2 registers a ContextManager** (see [Why a ContextManager](#why-a-contextmanager-032)), so the POST is genuinely suppressed.
+
+As belt-and-suspenders the exporter also drops any span whose HTTP target points at the configured ingest origin. As of **0.3.2** that match is **hostname-accurate**: full-URL attributes (`url.full`, `http.url`) are parsed and compared on `.hostname` (case-insensitive, port-stripped) so a sibling domain like `myingest.heystack.dev` is no longer a false positive and an explicit port like `ingest.heystack.dev:443` is correctly matched; host-only attributes (`server.address`, `net.peer.name`, `net.peer.hostname`, `http.host`, `peer.address`) are port-stripped and compared by hostname.
+
 ## Migration / versioning
 
-- **Pin `@heystack/otel` `>=0.2.0`** — the workerd-aware `/next` path and `initHeystackWorkers` / `flushHeystack` exports were added in 0.2.0.
+- **`0.3.2`** — runtime-correctness fixes:
+  - **ContextManager registered (CRITICAL).** 0.3.1's `suppressTracing` was a no-op because no ContextManager was registered, so the exporter's ingest POST could still be re-traced into a feedback loop. 0.3.2 registers an `AsyncLocalStorageContextManager` (Node + workerd under `nodejs_compat`; sync stack-manager fallback otherwise) so suppression works — and as a bonus you get cross-`await` span parenting + per-request context isolation. **Workers now require `nodejs_compat`.** New dependency: `@opentelemetry/context-async-hooks`.
+  - **Hostname-accurate self-span filter** (no sibling-domain false positives; `host:port` now matched; more host-only attrs covered).
+  - **OpenNext accessor race fixed** — the `getCloudflareContext` accessor loads eagerly and early exports that fire before it resolves still get handed to `ctx.waitUntil`; accessor/`waitUntil` failures are now logged (once) instead of silently swallowed.
+  - **Node SDK hardening** — `initHeystack` is idempotent (cached singleton) and registers SIGTERM/SIGINT handlers at most once (no leak across Next dev reloads); new optional `instrumentations` field to load a slimmer instrumentation set.
+  - **Drain timeout** — `instrument()`'s `ctx.waitUntil` flush is raced against an ~8s timeout so a hung ingest can't pin the isolate to its CPU limit.
+  - **Bundler hints** — `/next`'s runtime-selected dynamic imports carry `@vite-ignore` + `webpackIgnore` so a Node build doesn't bundle the workers path (and vice-versa).
+- **`0.3.1`** — `instrument()` now **forwards `queue`/`scheduled`/`tail` (and any other handler)** instead of returning only `{ fetch }`, and traces `queue`/`scheduled`; the exporter **suppresses self-tracing** on its ingest POST (note: only effective from 0.3.2, which registers the ContextManager). Both are production-reproduced bug fixes; upgrade is recommended for any Queue/Cron Worker or Next-on-OpenNext app.
+- **Pin `@heystack/otel` `>=0.3.0`** — 0.3.0 makes Next-on-OpenNext auto-flush via the Cloudflare request context, hardens workerd detection (uses the `WebSocketPair` global so it survives `nodejs_compat`), and has `instrument()` set the global provider so nested spans export. The workerd-aware `/next` path and `initHeystackWorkers` / `flushHeystack` exports were added in 0.2.0.
 - The pre-0.1.0 top-level default `initHeystack({ apiKey })` is **gone**. Use the subpath entries: `@heystack/otel/node`, `@heystack/otel/next`, `@heystack/otel/workers`. The root `@heystack/otel` entry now exposes only pure helpers (`buildExporterConfig`, types).
 
 ## Verify it's working

package/dist/next.d.ts

@@ -10,9 +10,12 @@ import type { HeystackOptions } from "./core.js";
  * and use the fetch-based exporter (@heystack/otel/workers) instead. On the Edge
  * runtime neither SDK can run, so it's a no-op.
  *
- * FLUSH (workerd): there is no per-request `ExecutionContext` on this path, so
- * spans are NOT auto-flushed and the export fetch may be cut off when the
- * isolate is torn down. For guaranteed delivery, import and call
+ * FLUSH (workerd): there is no per-request `ExecutionContext` handed to this
+ * function, but on Next-on-OpenNext the export runs inside the Cloudflare
+ * request context, so the exporter automatically borrows that request's
+ * `ctx.waitUntil` (via `@opennextjs/cloudflare`'s `getCloudflareContext`) to
+ * keep the isolate alive until the export POST completes — no app hook needed.
+ * For other workerd setups without `@opennextjs/cloudflare`, import and call
  * `flushHeystack()` from `@heystack/otel/workers` in a response hook (or via
  * `ctx.waitUntil(flushHeystack())` if you have a ctx) — it awaits the export.
  */

package/dist/next.js

@@ -9,9 +9,12 @@
  * and use the fetch-based exporter (@heystack/otel/workers) instead. On the Edge
  * runtime neither SDK can run, so it's a no-op.
  *
- * FLUSH (workerd): there is no per-request `ExecutionContext` on this path, so
- * spans are NOT auto-flushed and the export fetch may be cut off when the
- * isolate is torn down. For guaranteed delivery, import and call
+ * FLUSH (workerd): there is no per-request `ExecutionContext` handed to this
+ * function, but on Next-on-OpenNext the export runs inside the Cloudflare
+ * request context, so the exporter automatically borrows that request's
+ * `ctx.waitUntil` (via `@opennextjs/cloudflare`'s `getCloudflareContext`) to
+ * keep the isolate alive until the export POST completes — no app hook needed.
+ * For other workerd setups without `@opennextjs/cloudflare`, import and call
  * `flushHeystack()` from `@heystack/otel/workers` in a response hook (or via
  * `ctx.waitUntil(flushHeystack())` if you have a ctx) — it awaits the export.
  */
@@ -26,15 +29,28 @@ export async function registerHeystack(o) {
     }
     // Detect Cloudflare workerd (OpenNext / Workers). NEXT_RUNTIME is "nodejs" there,
     // but the Node SDK's node:http exporter can't send — use the fetch exporter instead.
+    //
+    // The old heuristic combined `caches.default` with `!process.versions.node`,
+    // which is WRONG under `nodejs_compat`: that compat layer polyfills
+    // `process.versions.node`, so the `!` is false and we'd pick the Node path
+    // (which silently exports nothing). Use Cloudflare-only signals that survive
+    // nodejs_compat instead: the `Cloudflare-Workers` UA and the `WebSocketPair`
+    // global (a Workers-only global present even under nodejs_compat).
     const g = globalThis;
     const onWorkerd = g.navigator?.userAgent === "Cloudflare-Workers" ||
-        (typeof g.caches?.default !== "undefined" && !g.process?.versions?.node);
+        typeof g.WebSocketPair !== "undefined";
     if (onWorkerd) {
-        const { initHeystackWorkers } = await import("./workers.js");
+        // Bundler-ignore hints: a Node build must not eagerly bundle the workers
+        // path (and a workers build must not bundle the node path) — the import is
+        // runtime-selected per environment. `@vite-ignore` covers Vite/Rollup;
+        // `webpackIgnore` covers Next/Turbopack/webpack.
+        const { initHeystackWorkers } = await import(
+        /* @vite-ignore */ /* webpackIgnore: true */ "./workers.js");
         initHeystackWorkers({ apiKey, service: o.service, endpoint: o.endpoint });
     }
     else {
-        const { initHeystack } = await import("./node.js");
+        const { initHeystack } = await import(
+        /* @vite-ignore */ /* webpackIgnore: true */ "./node.js");
         initHeystack({
             apiKey,
             service: o.service,

package/dist/node.d.ts

@@ -1,12 +1,33 @@
 import { NodeSDK } from "@opentelemetry/sdk-node";
+import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
 import { type HeystackOptions } from "./core.js";
+/**
+ * The element type the NodeSDK `instrumentations` config accepts (an OTel
+ * `Instrumentation` or array thereof). Derived from `getNodeAutoInstrumentations`
+ * so we don't take a direct dependency on `@opentelemetry/instrumentation` just
+ * for a type.
+ */
+type InstrumentationConfigItem = ReturnType<typeof getNodeAutoInstrumentations>[number];
 export interface NodeOptions extends HeystackOptions {
     /** Enable OTel diagnostic logging to console to confirm export. */
     debug?: boolean;
     /** Set false to skip auto-instrumentations (you'll then only get framework/manual spans). Default true. */
     autoInstrument?: boolean;
+    /**
+     * Provide your own instrumentation array instead of the default
+     * `getNodeAutoInstrumentations()`. Use this to load a slimmer set (the default
+     * eagerly patches ~40 libraries — DNS, fs, net, gRPC, every popular DB/HTTP
+     * client — which adds startup cost and overhead even for libs you don't use).
+     * Ignored when `autoInstrument === false`. Example:
+     *   import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";
+     *   initHeystack({ ..., instrumentations: [new HttpInstrumentation()] });
+     */
+    instrumentations?: InstrumentationConfigItem[];
 }
 /** Initialise Heystack tracing on a Node runtime. Call once, as early as possible. Returns the started SDK. */
 export declare function initHeystack(o: NodeOptions): NodeSDK;
-/** Flush + shutdown the SDK on SIGTERM/SIGINT so short-lived processes don't lose the last batch. */
+/** Flush + shutdown the SDK on SIGTERM/SIGINT so short-lived processes don't lose the last batch. Registers handlers at most once. */
 export declare function shutdownOnSignals(sdk: NodeSDK): void;
+/** Reset the cached SDK + signal-handler guard. Internal/testing helper. */
+export declare function __resetNodeSdk(): void;
+export {};

package/dist/node.js

@@ -3,22 +3,47 @@ import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
 import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
 import { diag, DiagConsoleLogger, DiagLogLevel } from "@opentelemetry/api";
 import { buildExporterConfig } from "./core.js";
+/**
+ * Process-level guard so SIGTERM/SIGINT handlers are registered AT MOST ONCE,
+ * even if `initHeystack` is called repeatedly (e.g. Next dev server reloads).
+ * Without this, every re-init leaked another pair of signal listeners and
+ * eventually tripped Node's MaxListenersExceededWarning.
+ */
+let _signalHandlersRegistered = false;
+/**
+ * Cached singleton SDK. `initHeystack` is meant to be called once; on repeat
+ * calls we return the already-started SDK instead of constructing/starting a
+ * second NodeSDK (which would double-register instrumentations and signal
+ * handlers).
+ */
+let _sdk = null;
 /** Initialise Heystack tracing on a Node runtime. Call once, as early as possible. Returns the started SDK. */
 export function initHeystack(o) {
+    // Idempotent: a second call returns the cached SDK rather than starting a new
+    // one (which would duplicate instrumentations + signal handlers).
+    if (_sdk)
+        return _sdk;
     if (o.debug)
         diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.DEBUG);
     const cfg = buildExporterConfig(o);
+    const instrumentations = o.autoInstrument === false
+        ? []
+        : (o.instrumentations ?? [getNodeAutoInstrumentations()]);
     const sdk = new NodeSDK({
         serviceName: o.service,
         traceExporter: new OTLPTraceExporter({ url: cfg.url, headers: cfg.headers }),
-        instrumentations: o.autoInstrument === false ? [] : [getNodeAutoInstrumentations()],
+        instrumentations,
     });
     sdk.start();
     shutdownOnSignals(sdk);
+    _sdk = sdk;
     return sdk;
 }
-/** Flush + shutdown the SDK on SIGTERM/SIGINT so short-lived processes don't lose the last batch. */
+/** Flush + shutdown the SDK on SIGTERM/SIGINT so short-lived processes don't lose the last batch. Registers handlers at most once. */
 export function shutdownOnSignals(sdk) {
+    if (_signalHandlersRegistered)
+        return;
+    _signalHandlersRegistered = true;
     const stop = () => {
         sdk
             .shutdown()
@@ -28,3 +53,8 @@ export function shutdownOnSignals(sdk) {
     process.once("SIGTERM", stop);
     process.once("SIGINT", stop);
 }
+/** Reset the cached SDK + signal-handler guard. Internal/testing helper. */
+export function __resetNodeSdk() {
+    _sdk = null;
+    _signalHandlersRegistered = false;
+}

package/dist/workers.d.ts

@@ -1,4 +1,5 @@
 import { type Span } from "@opentelemetry/api";
+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";
 declare const ExportResultCode: {
@@ -53,12 +54,21 @@ interface OtlpTracesPayload {
  * hence the same resource, so we emit a single resourceSpans entry.
  */
 export declare function serializeSpans(spans: ReadableSpan[]): OtlpTracesPayload;
+/**
+ * Test-only helper: run the self-span attribute check directly against a plain
+ * attribute bag + ingest hostname, without constructing a ReadableSpan. The
+ * `ingestHost` should be a bare hostname (lower-case, no port), matching what
+ * the exporter derives via `safeHostname(cfg.url)`.
+ */
+export declare function isSelfSpanForTest(attrs: Record<string, unknown>, ingestHost: string): boolean;
 /**
  * A WinterCG-compatible OTLP/JSON span exporter. POSTs ended spans to the
  * Heystack ingest using the platform `fetch` — no Node built-ins.
  */
 export declare class HeystackSpanExporter implements SpanExporter {
     private readonly url;
+    /** Hostname (no port) of the ingest endpoint, used to drop self-trace spans. */
+    private readonly ingestHost;
     private readonly headers;
     private shutdownState;
     /**
@@ -69,8 +79,27 @@ export declare class HeystackSpanExporter implements SpanExporter {
      * dropped on fast-responding Workers/edge handlers.
      */
     private readonly pending;
+    /**
+     * Optional `waitUntil` hook. When set, each in-flight export `fetch` is also
+     * handed to it so the runtime keeps the isolate alive until the POST
+     * completes — without any per-request hook in app code. This is the reliable
+     * delivery path on Next-on-OpenNext, where there is no `ExecutionContext`
+     * passed to `registerHeystack` but the export DOES run inside a Cloudflare
+     * request context whose `ctx.waitUntil` we can borrow. Falls back silently to
+     * the `pending` set + manual `flushHeystack()` when absent/unavailable.
+     */
+    waitUntil?: (p: Promise<unknown>) => void;
     constructor(options: HeystackOptions);
     export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void;
+    /**
+     * Hand `p` to the OpenNext Cloudflare request context's `ctx.waitUntil`.
+     * Resolves the accessor first (awaiting its in-flight load if needed) so an
+     * export that fired before the dynamic import settled is still covered.
+     */
+    private handOffToCloudflareContext;
+    private warnedWaitUntilFailure;
+    /** Log a waitUntil/accessor failure exactly once; never throw. */
+    private warnWaitUntilFailed;
     shutdown(): Promise<void>;
     /**
      * Resolve only once every in-flight export fetch has settled. This is the
@@ -85,6 +114,14 @@ export interface WorkersConfig {
     /** Defaults to env.HEYSTACK_API_KEY at request time if omitted. */
     apiKey?: string;
     endpoint?: string;
+    /**
+     * Optional override to keep the isolate alive until each export `fetch`
+     * completes. When provided this takes priority over the auto-detected
+     * OpenNext Cloudflare request context. Typically `ctx.waitUntil` from your
+     * Worker's `ExecutionContext`. If omitted on Next-on-OpenNext, the exporter
+     * automatically borrows the request context's `ctx.waitUntil`.
+     */
+    waitUntil?: (p: Promise<unknown>) => void;
 }
 /**
  * A `BasicTracerProvider` with the underlying `HeystackSpanExporter` attached so
@@ -105,15 +142,36 @@ export type HeystackTracerProvider = BasicTracerProvider & {
  * `flushHeystack()`), not just `provider.forceFlush()`.
  */
 export declare function createTracerProvider(config: HeystackOptions): HeystackTracerProvider;
+/**
+ * A minimal SYNCHRONOUS, stack-based ContextManager — the registered manager for
+ * the /workers entry (no `node:async_hooks`, so it works on any WinterCG runtime).
+ * It makes `context.with()` propagate synchronously, which is enough for the
+ * exporter's `suppressTracing` to take effect and for the belt-and-suspenders
+ * self-span filter — but it does NOT carry context across `await` boundaries (so
+ * cross-`await` parent linking and per-request isolation are best-effort).
+ */
+export declare class SyncStackContextManager implements ContextManager {
+    private _stack;
+    active(): Context;
+    with<A extends unknown[], F extends (...args: A) => ReturnType<F>>(ctx: Context, fn: F, thisArg?: ThisParameterType<F>, ...args: A): ReturnType<F>;
+    bind<T>(_ctx: Context, target: T): T;
+    enable(): this;
+    disable(): this;
+}
+/** Reset the context-manager registration guard. Internal/testing helper. */
+export declare function __resetContextManager(): void;
 /**
  * Register Heystack as the global tracer provider on a Workers/edge runtime
  * (workerd). Spans from the host framework (e.g. Next.js) export over fetch.
  * Use this instead of @heystack/otel/node when running on Cloudflare/edge.
  *
- * FLUSH: there is no per-request `ExecutionContext` on this path, so spans are
- * NOT auto-flushed. To guarantee delivery on workerd, call `flushHeystack()`
- * (which awaits the export fetch) from a response hook — or hand it to
- * `ctx.waitUntil(flushHeystack())` if you do have a ctx. Returns the provider.
+ * FLUSH: on Next-on-OpenNext (where `@opennextjs/cloudflare` is present) the
+ * exporter automatically borrows the Cloudflare request context's
+ * `ctx.waitUntil` so the export POST completes before the isolate is torn down
+ * — no app hook needed. For other workerd setups without it, call
+ * `flushHeystack()` (which awaits the export fetch) from a response hook, hand
+ * it to `ctx.waitUntil(flushHeystack())`, or pass an explicit `waitUntil` in
+ * the config (highest priority). Returns the provider.
  */
 export declare function initHeystackWorkers(config: WorkersConfig & {
     apiKey: string;
@@ -131,8 +189,18 @@ export declare function flushHeystack(): Promise<void>;
 export declare function __resetProvider(): void;
 /** Reset the once-only no-key warning. Internal/testing helper. */
 export declare function __resetWarnings(): void;
-interface FetchHandler<E> {
-    fetch: (req: Request, env: E, ctx: ExecutionContext) => Promise<Response> | Response;
+/**
+ * The shape of a Worker's default export. `fetch` is the common entrypoint, but
+ * a Worker may also export `queue` / `scheduled` / `tail` (and arbitrary other
+ * siblings). `instrument()` forwards ALL of these untouched except `fetch`
+ * (always traced) and `queue` / `scheduled` (traced when present) — so wrapping
+ * a Worker never drops a handler Cloudflare requires for deploy.
+ */
+interface WorkerHandler<E> {
+    fetch?: (req: Request, env: E, ctx: ExecutionContext) => Promise<Response> | Response;
+    queue?: (batch: MessageBatch, env: E, ctx: ExecutionContext) => Promise<void> | void;
+    scheduled?: (controller: ScheduledController, env: E, ctx: ExecutionContext) => Promise<void> | void;
+    [key: string]: unknown;
 }
 /**
  * Wrap a Worker's default export so every request is auto-traced with a SERVER
@@ -150,10 +218,40 @@ interface FetchHandler<E> {
  *     { service: "my-worker" },
  *   );
  *
+ * TRACE TREE: `instrument()` sets up the singleton GLOBAL tracer provider and
+ * creates the root span via the global tracer (`trace.getTracer("heystack")`).
+ * This means nested spans created through the global `trace.getTracer()` API
+ * (framework / library / your own manual spans) also flow to the exporter — you
+ * get a trace tree, not a lone root span.
+ *
+ * ALL HANDLERS FORWARDED: the returned object spreads `handler`, so sibling
+ * handlers a Worker exports (`tail`, `email`, etc.) are preserved — Cloudflare
+ * won't reject the deploy for a missing handler. `fetch` is always replaced with
+ * a traced wrapper; `queue` and `scheduled` are wrapped (and traced) when
+ * present; everything else is forwarded untouched.
+ *
  * If no API key is available (neither `config.apiKey` nor
  * `env.HEYSTACK_API_KEY`), the handler runs untraced.
  */
-export declare function instrument<E = unknown>(handler: FetchHandler<E>, config: WorkersConfig): {
+/**
+ * The instrumented result: the original handler with the traced entrypoints
+ * normalised to their full Worker signatures (so callers/tests can invoke them
+ * with `(arg, env, ctx)`), and every other sibling handler forwarded as-is. A
+ * traced key is present (and non-optional) exactly when it exists on the input
+ * handler, so a `{ fetch }` Worker yields a non-optional `fetch`.
+ */
+type Instrumented<E, H> = Omit<H, "fetch" | "queue" | "scheduled"> & (H extends {
+    fetch: unknown;
+} ? {
     fetch: (req: Request, env: E, ctx: ExecutionContext) => Promise<Response>;
-};
+} : unknown) & (H extends {
+    queue: unknown;
+} ? {
+    queue: (batch: MessageBatch, env: E, ctx: ExecutionContext) => Promise<void>;
+} : unknown) & (H extends {
+    scheduled: unknown;
+} ? {
+    scheduled: (controller: ScheduledController, env: E, ctx: ExecutionContext) => Promise<void>;
+} : unknown);
+export declare function instrument<E = unknown, H extends WorkerHandler<E> = WorkerHandler<E>>(handler: H, config: WorkersConfig): Instrumented<E, H>;
 export type { Span };

package/dist/workers.js

@@ -8,6 +8,8 @@
 // ships its own OTLP/JSON-over-fetch span exporter so it runs on Workers/Edge
 // where the Node SDK cannot.
 import { context, trace, SpanKind, SpanStatusCode, } from "@opentelemetry/api";
+import { suppressTracing } from "@opentelemetry/core";
+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";
@@ -17,6 +19,37 @@ import { buildExporterConfig } from "./core.js";
 // transitive dep of sdk-trace-base and isn't reliably resolvable, and keeping it
 // out guarantees no extra (potentially node-platform) code in the bundle.
 const ExportResultCode = { SUCCESS: 0, FAILED: 1 };
+let _getCloudflareContext;
+let _cfAccessorLoadPromise;
+/**
+ * Best-effort, once-only resolve of OpenNext's `getCloudflareContext`. The
+ * import is async, so the FIRST export(s) may run before it settles — see
+ * `export()`, which awaits this promise so those early exports still get handed
+ * to `ctx.waitUntil` once the accessor resolves (rather than relying solely on
+ * an explicit `flushHeystack()` that the OpenNext path doesn't call). Started
+ * eagerly at module init so the window is as small as possible.
+ */
+function loadCloudflareContextAccessor() {
+    if (_cfAccessorLoadPromise)
+        return _cfAccessorLoadPromise;
+    _cfAccessorLoadPromise = (async () => {
+        try {
+            const spec = "@opennextjs/cloudflare";
+            const m = (await import(/* @vite-ignore */ /* webpackIgnore: true */ spec));
+            _getCloudflareContext = m.getCloudflareContext;
+        }
+        catch {
+            // Not on OpenNext (or the package isn't installed) — fall back silently to
+            // the `pending` set + manual flush. This is the common, expected case off
+            // OpenNext, so it is intentionally NOT logged.
+        }
+    })();
+    return _cfAccessorLoadPromise;
+}
+// Kick off the accessor resolution eagerly at module load so it's ready (or
+// nearly so) by the time the first export runs, minimising the race where an
+// early export can't borrow `ctx.waitUntil`.
+void loadCloudflareContextAccessor();
 /** Convert an OTel HrTime `[seconds, nanos]` tuple to a nanosecond string. */
 function hrTimeToUnixNano(time) {
     // BigInt math keeps full nanosecond precision without float rounding.
@@ -105,6 +138,98 @@ export function serializeSpans(spans) {
     };
 }
 // ---------------------------------------------------------------------------
+// Self-span filtering (feedback-loop guard)
+//
+// On Next/OpenNext the host auto-instruments outbound `fetch`, so the exporter's
+// own POST to `/v1/traces` becomes a CLIENT span → exported → re-captured → a
+// sustained loop. The primary defence is exporting under a suppressed context
+// (see `export()`), but as belt-and-suspenders we also drop any span that
+// targets the ingest origin, so an upstream instrumentation that ignores
+// suppression still can't feed the loop.
+// ---------------------------------------------------------------------------
+/**
+ * Parse the hostname (no port) out of a URL, lower-cased; empty string if it
+ * can't be parsed. We compare on hostname rather than `host` so that an ingest
+ * URL like `ingest.heystack.dev` matches a captured span attribute of
+ * `ingest.heystack.dev:443` (and vice-versa).
+ */
+function safeHostname(url) {
+    try {
+        return new URL(url).hostname.toLowerCase();
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Strip a trailing `:port` from a bare host attribute and lower-case it, so a
+ * host-only attr like `ingest.heystack.dev:443` compares equal to the ingest
+ * hostname. IPv6 literals (`[::1]:443`) keep their bracketed form. Returns ""
+ * for anything that isn't a non-empty string.
+ */
+function hostnameOf(hostAttr) {
+    if (typeof hostAttr !== "string" || hostAttr === "")
+        return "";
+    const v = hostAttr.trim();
+    // Bracketed IPv6, optionally with a port: `[::1]` or `[::1]:443`.
+    if (v.startsWith("[")) {
+        const close = v.indexOf("]");
+        if (close !== -1)
+            return v.slice(0, close + 1).toLowerCase();
+        return v.toLowerCase();
+    }
+    // Strip a single trailing :port (host:port). A bare hostname has no colon.
+    const colon = v.lastIndexOf(":");
+    if (colon !== -1 && v.indexOf(":") === colon) {
+        return v.slice(0, colon).toLowerCase();
+    }
+    return v.toLowerCase();
+}
+/** Attributes that carry a full HTTP URL on a CLIENT/SERVER span. */
+const HTTP_URL_ATTRS = ["url.full", "http.url"];
+/** Host-only attributes (host[:port], no scheme/path). */
+const HTTP_HOST_ATTRS = [
+    "server.address",
+    "net.peer.name",
+    "net.peer.hostname",
+    "http.host",
+    "peer.address",
+];
+/**
+ * True if `span` looks like a request to the configured ingest origin — i.e. it
+ * is (or could be) the exporter's own self-trace. For full-URL attributes we
+ * parse the URL and compare its `.hostname` (case-insensitive, port stripped) so
+ * a sibling domain like `myingest.heystack.dev` is NOT a false positive and an
+ * explicit port like `ingest.heystack.dev:443` IS matched. For host-only attrs
+ * we strip any `:port` and compare hostname equality.
+ */
+function isSelfSpanAttrs(attrs, ingestHost) {
+    if (!ingestHost)
+        return false;
+    for (const key of HTTP_URL_ATTRS) {
+        const v = attrs[key];
+        if (typeof v === "string" && safeHostname(v) === ingestHost)
+            return true;
+    }
+    for (const key of HTTP_HOST_ATTRS) {
+        if (hostnameOf(attrs[key]) === ingestHost)
+            return true;
+    }
+    return false;
+}
+function isSelfSpan(span, ingestHost) {
+    return isSelfSpanAttrs(span.attributes, ingestHost);
+}
+/**
+ * Test-only helper: run the self-span attribute check directly against a plain
+ * attribute bag + ingest hostname, without constructing a ReadableSpan. The
+ * `ingestHost` should be a bare hostname (lower-case, no port), matching what
+ * the exporter derives via `safeHostname(cfg.url)`.
+ */
+export function isSelfSpanForTest(attrs, ingestHost) {
+    return isSelfSpanAttrs(attrs, ingestHost);
+}
+// ---------------------------------------------------------------------------
 // Exporter
 // ---------------------------------------------------------------------------
 /**
@@ -113,6 +238,8 @@ export function serializeSpans(spans) {
  */
 export class HeystackSpanExporter {
     url;
+    /** Hostname (no port) of the ingest endpoint, used to drop self-trace spans. */
+    ingestHost;
     headers;
     shutdownState = false;
     /**
@@ -123,9 +250,20 @@ export class HeystackSpanExporter {
      * dropped on fast-responding Workers/edge handlers.
      */
     pending = new Set();
+    /**
+     * Optional `waitUntil` hook. When set, each in-flight export `fetch` is also
+     * handed to it so the runtime keeps the isolate alive until the POST
+     * completes — without any per-request hook in app code. This is the reliable
+     * delivery path on Next-on-OpenNext, where there is no `ExecutionContext`
+     * passed to `registerHeystack` but the export DOES run inside a Cloudflare
+     * request context whose `ctx.waitUntil` we can borrow. Falls back silently to
+     * the `pending` set + manual `flushHeystack()` when absent/unavailable.
+     */
+    waitUntil;
     constructor(options) {
         const cfg = buildExporterConfig(options);
         this.url = cfg.url;
+        this.ingestHost = safeHostname(cfg.url);
         this.headers = {
             ...cfg.headers,
             "content-type": "application/json",
@@ -143,11 +281,25 @@ export class HeystackSpanExporter {
             resultCallback({ code: ExportResultCode.SUCCESS });
             return;
         }
-        const body = JSON.stringify(serializeSpans(spans));
+        // Belt-and-suspenders: drop the exporter's own self-trace spans (any span
+        // targeting the ingest origin) so an upstream instrumentation that ignores
+        // our suppressed context still can't feed the feedback loop.
+        const exportable = spans.filter((s) => !isSelfSpan(s, this.ingestHost));
+        if (exportable.length === 0) {
+            resultCallback({ code: ExportResultCode.SUCCESS });
+            return;
+        }
+        const body = JSON.stringify(serializeSpans(exportable));
         // Build the fetch chain as a promise we retain, so forceFlush() can await
         // the actual network write. It resolves (never rejects) once the POST has
         // completed (success or fail) and resultCallback has been invoked.
-        const p = fetch(this.url, { method: "POST", headers: this.headers, body })
+        //
+        // The POST runs inside a tracing-suppressed context so that host fetch
+        // auto-instrumentation (e.g. Next/OpenNext) does NOT create a CLIENT span
+        // for it — which would otherwise be exported and re-captured, a sustained
+        // feedback loop.
+        const p = context
+            .with(suppressTracing(context.active()), () => fetch(this.url, { method: "POST", headers: this.headers, body }))
             .then((res) => {
             if (res.ok) {
                 resultCallback({ code: ExportResultCode.SUCCESS });
@@ -167,6 +319,69 @@ export class HeystackSpanExporter {
         });
         this.pending.add(p);
         p.finally(() => this.pending.delete(p));
+        // Keep the isolate alive until the POST completes. Priority:
+        //   1. an explicit `waitUntil` override (set via initHeystackWorkers).
+        //   2. the OpenNext Cloudflare request context's `ctx.waitUntil` — the
+        //      export runs during request handling, so this is available there.
+        // Either path makes delivery reliable on workerd/OpenNext with no app hook.
+        // The `pending` set + `flushHeystack()` remain as the explicit fallback.
+        if (this.waitUntil) {
+            try {
+                this.waitUntil(p);
+            }
+            catch (error) {
+                this.warnWaitUntilFailed("explicit waitUntil", error);
+            }
+        }
+        else {
+            // The accessor loads asynchronously, so the first export(s) may run before
+            // it resolves. Borrow `ctx.waitUntil` synchronously if it's already
+            // available; otherwise await the in-flight accessor load so even those
+            // early exports get handed to waitUntil once it resolves. `p` is already
+            // in `pending`, so a manual `flushHeystack()` covers it regardless.
+            this.handOffToCloudflareContext(p);
+        }
+    }
+    /**
+     * Hand `p` to the OpenNext Cloudflare request context's `ctx.waitUntil`.
+     * Resolves the accessor first (awaiting its in-flight load if needed) so an
+     * export that fired before the dynamic import settled is still covered.
+     */
+    handOffToCloudflareContext(p) {
+        const attempt = () => {
+            if (!_getCloudflareContext)
+                return;
+            try {
+                const cf = _getCloudflareContext();
+                cf?.ctx?.waitUntil?.(p);
+            }
+            catch (error) {
+                // #15: a real failure inside getCloudflareContext (e.g. called outside a
+                // request context) was previously swallowed silently. Name it once so it
+                // is diagnosable, then fall back to the `pending` set + manual flush.
+                this.warnWaitUntilFailed("getCloudflareContext", error);
+            }
+        };
+        if (_getCloudflareContext) {
+            attempt();
+        }
+        else {
+            // Accessor not resolved yet — await its load, then try once.
+            void loadCloudflareContextAccessor().then(attempt);
+        }
+    }
+    warnedWaitUntilFailure = false;
+    /** Log a waitUntil/accessor failure exactly once; never throw. */
+    warnWaitUntilFailed(where, error) {
+        if (this.warnedWaitUntilFailure)
+            return;
+        this.warnedWaitUntilFailure = true;
+        const msg = error instanceof Error ? error.message : String(error);
+        // console.debug so it's quiet by default but visible when debugging dropped
+        // traces; the export still completes via the `pending` set + manual flush.
+        console.debug(`[heystack] could not hand export to ${where} (${msg}); ` +
+            "falling back to pending-set flush. Trace delivery may be best-effort " +
+            "unless you call flushHeystack() or pass an explicit waitUntil.");
     }
     shutdown() {
         return this.forceFlush().then(() => {
@@ -206,27 +421,125 @@ export function createTracerProvider(config) {
 // Global tracer provider registration (for host frameworks, e.g. Next.js)
 // ---------------------------------------------------------------------------
 let _provider = null;
+// ---------------------------------------------------------------------------
+// Context manager registration (makes suppressTracing() actually work)
+//
+// `context.with(...)` is a NO-OP unless a ContextManager is registered with the
+// global OTel API. Without one, `suppressTracing(context.active())` produces a
+// context that is never made active, so the exporter's POST is NOT suppressed
+// in production and host fetch auto-instrumentation can re-trace it (feedback
+// loop). We therefore register a manager exactly ONCE in `ensureGlobalProvider`.
+//
+// We register a dependency-free SYNCHRONOUS stack manager (below). Deliberately
+// NOT AsyncLocalStorageContextManager: that statically imports `node:async_hooks`,
+// which would break `import "@heystack/otel/workers"` on a bare workerd without
+// `nodejs_compat` (and on other WinterCG runtimes) — defeating the whole point of
+// this entry being node-builtin-free. The sync manager covers the critical path:
+// the exporter's POST runs synchronously inside the suppressed `context.with`, so
+// `suppressTracing` takes effect. Trade-off: no cross-`await` context propagation,
+// so deep nested-span parenting is limited on the edge (documented).
+// ---------------------------------------------------------------------------
 /**
- * Register Heystack as the global tracer provider on a Workers/edge runtime
- * (workerd). Spans from the host framework (e.g. Next.js) export over fetch.
- * Use this instead of @heystack/otel/node when running on Cloudflare/edge.
+ * A minimal SYNCHRONOUS, stack-based ContextManager — the registered manager for
+ * the /workers entry (no `node:async_hooks`, so it works on any WinterCG runtime).
+ * It makes `context.with()` propagate synchronously, which is enough for the
+ * exporter's `suppressTracing` to take effect and for the belt-and-suspenders
+ * self-span filter — but it does NOT carry context across `await` boundaries (so
+ * cross-`await` parent linking and per-request isolation are best-effort).
+ */
+export class SyncStackContextManager {
+    _stack = [];
+    active() {
+        return this._stack[this._stack.length - 1] ?? ROOT_CONTEXT;
+    }
+    with(ctx, fn, thisArg, ...args) {
+        this._stack.push(ctx);
+        try {
+            return fn.call(thisArg, ...args);
+        }
+        finally {
+            this._stack.pop();
+        }
+    }
+    bind(_ctx, target) {
+        return target;
+    }
+    enable() {
+        return this;
+    }
+    disable() {
+        this._stack = [];
+        return this;
+    }
+}
+let _contextManagerRegistered = false;
+/**
+ * Register a global OTel ContextManager exactly once, so that
+ * `context.with(suppressTracing(...))` in the exporter is actually honoured —
+ * otherwise suppression is a no-op and the exporter's POST can be re-traced.
  *
- * FLUSH: there is no per-request `ExecutionContext` on this path, so spans are
- * NOT auto-flushed. To guarantee delivery on workerd, call `flushHeystack()`
- * (which awaits the export fetch) from a response hook — or hand it to
- * `ctx.waitUntil(flushHeystack())` if you do have a ctx. Returns the provider.
+ * We register a synchronous, dependency-free stack manager. This keeps the
+ * /workers entry WinterCG-safe (no `node:async_hooks` import → works on bare
+ * workerd WITHOUT nodejs_compat, Deno, Bun, etc.). It fully covers the critical
+ * path (the export fetch runs synchronously inside the suppressed `context.with`,
+ * and per-request root spans). Trade-off: it does not propagate context across
+ * `await` boundaries, so deep nested-span parenting is limited on the edge — an
+ * acceptable, documented limitation (workerd has no async context manager by
+ * default regardless).
  */
-export function initHeystackWorkers(config) {
+function ensureContextManager() {
+    if (_contextManagerRegistered)
+        return;
+    _contextManagerRegistered = true;
+    context.setGlobalContextManager(new SyncStackContextManager().enable());
+}
+/** Reset the context-manager registration guard. Internal/testing helper. */
+export function __resetContextManager() {
+    _contextManagerRegistered = false;
+}
+/**
+ * Build (once) and register the singleton global tracer provider. Wires the
+ * exporter's `waitUntil` (explicit override > nothing here; the auto-detected
+ * OpenNext context is resolved lazily inside the exporter) and kicks off the
+ * best-effort load of OpenNext's `getCloudflareContext` accessor so the
+ * exporter can borrow `ctx.waitUntil` during request handling. Shared by
+ * `initHeystackWorkers` and `instrument`.
+ */
+function ensureGlobalProvider(config) {
     if (_provider)
         return _provider;
     _provider = createTracerProvider(config);
-    // register as the global provider so framework spans flow to our exporter.
-    // BasicTracerProvider.register() also wires context/propagation, but on
-    // workerd we only need the global tracer provider — set it directly so it's
-    // deterministic and doesn't pull in a context manager that may not run here.
+    if (config.waitUntil)
+        _provider.heystackExporter.waitUntil = config.waitUntil;
+    // Best-effort: resolve OpenNext's context accessor so the exporter can borrow
+    // `ctx.waitUntil` during request handling. Guarded; fails closed when absent.
+    void loadCloudflareContextAccessor();
+    // Register as the global provider so framework / global-API spans flow to our
+    // exporter. We set it directly (rather than provider.register()) so it's
+    // deterministic and so we control exactly which ContextManager is registered.
     trace.setGlobalTracerProvider(_provider);
+    // Register a ContextManager (once) so `context.with(suppressTracing(...))` in
+    // the exporter actually takes effect — without one, `context.with` is a no-op
+    // and suppression silently does nothing in production.
+    ensureContextManager();
     return _provider;
 }
+/**
+ * Register Heystack as the global tracer provider on a Workers/edge runtime
+ * (workerd). Spans from the host framework (e.g. Next.js) export over fetch.
+ * Use this instead of @heystack/otel/node when running on Cloudflare/edge.
+ *
+ * FLUSH: on Next-on-OpenNext (where `@opennextjs/cloudflare` is present) the
+ * exporter automatically borrows the Cloudflare request context's
+ * `ctx.waitUntil` so the export POST completes before the isolate is torn down
+ * — no app hook needed. For other workerd setups without it, call
+ * `flushHeystack()` (which awaits the export fetch) from a response hook, hand
+ * it to `ctx.waitUntil(flushHeystack())`, or pass an explicit `waitUntil` in
+ * the config (highest priority). Returns the provider.
+ */
+export function initHeystackWorkers(config) {
+    return ensureGlobalProvider(config);
+}
 /**
  * Force-flush any pending spans AND wait for the export network write to
  * complete. This awaits both the OTel provider's `forceFlush()` (drains the
@@ -260,40 +573,60 @@ function warnOnceNoKey() {
 export function __resetWarnings() {
     warnedNoKey = false;
 }
-/**
- * Wrap a Worker's default export so every request is auto-traced with a SERVER
- * span.
- *
- * FLUSH (CRITICAL on Workers/edge): the export is a `fetch()` POST. After
- * `span.end()` we `ctx.waitUntil` a promise that awaits BOTH the provider's
- * span processor AND the exporter's in-flight fetch, so the network write
- * completes before the isolate is torn down. Without this, fast-responding
- * handlers return before the POST finishes and the trace is silently dropped.
- *
- *   import { instrument } from "@heystack/otel/workers";
- *   export default instrument(
- *     { async fetch(req, env, ctx) { return new Response("ok"); } },
- *     { service: "my-worker" },
- *   );
- *
- * If no API key is available (neither `config.apiKey` nor
- * `env.HEYSTACK_API_KEY`), the handler runs untraced.
- */
 export function instrument(handler, config) {
-    return {
-        async fetch(req, env, ctx) {
-            const apiKey = config.apiKey ?? env?.HEYSTACK_API_KEY;
-            // No key → run untraced (warn once).
-            if (!apiKey) {
-                warnOnceNoKey();
-                return handler.fetch(req, env, ctx);
-            }
-            const provider = createTracerProvider({
-                apiKey,
-                service: config.service,
-                endpoint: config.endpoint,
-            });
-            const tracer = provider.getTracer("@heystack/otel/workers");
+    // Resolve the API key + set up (once) the global provider. Returns null when
+    // no key is available so callers can run the handler untraced.
+    const setup = (env) => {
+        const apiKey = config.apiKey ?? env?.HEYSTACK_API_KEY;
+        if (!apiKey) {
+            warnOnceNoKey();
+            return null;
+        }
+        // The global provider lets spans created via the global `trace.getTracer()`
+        // API — nested framework/library/manual spans — export too, yielding a
+        // trace tree rather than a lone root span.
+        const provider = ensureGlobalProvider({
+            apiKey,
+            service: config.service,
+            endpoint: config.endpoint,
+            waitUntil: config.waitUntil,
+        });
+        return { provider, tracer: trace.getTracer("heystack") };
+    };
+    // Drain BOTH the provider's span processor AND the exporter's in-flight fetch
+    // via ctx.waitUntil. Awaiting only provider.forceFlush() would return before
+    // the export POST completes, letting the isolate be torn down and silently
+    // dropping the trace.
+    //
+    // #25: the drain is raced against an ~8s timeout so a hung forceFlush (e.g. an
+    // ingest that never responds) can't pin the isolate until the platform CPU
+    // timeout kills it. On timeout we stop waiting; the POST is still in-flight and
+    // may yet complete, we just don't block the isolate on it indefinitely.
+    const DRAIN_TIMEOUT_MS = 8_000;
+    const drain = (provider, ctx) => {
+        const drained = (async () => {
+            await provider.forceFlush().catch(() => { });
+            await provider.heystackExporter.forceFlush().catch(() => { });
+        })();
+        let timer;
+        const timeout = new Promise((resolve) => {
+            timer = setTimeout(resolve, DRAIN_TIMEOUT_MS);
+        });
+        ctx.waitUntil(Promise.race([drained, timeout]).finally(() => {
+            if (timer)
+                clearTimeout(timer);
+        }));
+    };
+    // Start from a shallow copy so EVERY sibling handler (tail, email, …) is
+    // forwarded untouched; we only override fetch/queue/scheduled below.
+    const wrapped = { ...handler };
+    const originalFetch = handler.fetch?.bind(handler);
+    if (originalFetch) {
+        wrapped.fetch = async (req, env, ctx) => {
+            const s = setup(env);
+            if (!s)
+                return originalFetch(req, env, ctx);
+            const { provider, tracer } = s;
             const url = new URL(req.url);
             const span = tracer.startSpan(`${req.method} ${url.pathname}`, {
                 kind: SpanKind.SERVER,
@@ -304,35 +637,90 @@ export function instrument(handler, config) {
                     "server.address": url.host,
                 },
             });
-            // waitUntil a promise that drains BOTH the provider's span processor and
-            // the exporter's in-flight fetch. Awaiting only provider.forceFlush()
-            // would return before the export POST completes, letting the isolate be
-            // torn down and silently dropping the trace.
-            const flush = () => ctx.waitUntil((async () => {
-                await provider.forceFlush().catch(() => { });
-                await provider.heystackExporter.forceFlush().catch(() => { });
-            })());
             try {
-                const response = await context.with(trace.setSpan(context.active(), span), () => handler.fetch(req, env, ctx));
+                const response = await context.with(trace.setSpan(context.active(), span), () => originalFetch(req, env, ctx));
                 span.setAttribute("http.response.status_code", response.status);
                 span.setStatus({
                     code: response.status >= 500 ? SpanStatusCode.ERROR : SpanStatusCode.UNSET,
                 });
                 span.end();
-                flush();
+                drain(provider, ctx);
                 return response;
             }
             catch (error) {
-                if (error instanceof Error)
-                    span.recordException(error);
+                span.recordException(error instanceof Error ? error : new Error(String(error)));
                 span.setStatus({
                     code: SpanStatusCode.ERROR,
                     message: error instanceof Error ? error.message : String(error),
                 });
                 span.end();
-                flush();
+                drain(provider, ctx);
                 throw error;
             }
-        },
-    };
+        };
+    }
+    const originalQueue = handler.queue?.bind(handler);
+    if (originalQueue) {
+        wrapped.queue = async (batch, env, ctx) => {
+            const s = setup(env);
+            if (!s)
+                return originalQueue(batch, env, ctx);
+            const { provider, tracer } = s;
+            const span = tracer.startSpan(`queue ${batch.queue}`, {
+                kind: SpanKind.CONSUMER,
+                attributes: {
+                    "messaging.batch.message_count": batch.messages.length,
+                    "messaging.destination.name": batch.queue,
+                },
+            });
+            try {
+                await context.with(trace.setSpan(context.active(), span), () => originalQueue(batch, env, ctx));
+                span.setStatus({ code: SpanStatusCode.UNSET });
+                span.end();
+                drain(provider, ctx);
+            }
+            catch (error) {
+                span.recordException(error instanceof Error ? error : new Error(String(error)));
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                span.end();
+                drain(provider, ctx);
+                throw error;
+            }
+        };
+    }
+    const originalScheduled = handler.scheduled?.bind(handler);
+    if (originalScheduled) {
+        wrapped.scheduled = async (controller, env, ctx) => {
+            const s = setup(env);
+            if (!s)
+                return originalScheduled(controller, env, ctx);
+            const { provider, tracer } = s;
+            const span = tracer.startSpan(`scheduled ${controller.cron}`, {
+                kind: SpanKind.INTERNAL,
+                attributes: {
+                    "controller.cron": controller.cron,
+                },
+            });
+            try {
+                await context.with(trace.setSpan(context.active(), span), () => originalScheduled(controller, env, ctx));
+                span.setStatus({ code: SpanStatusCode.UNSET });
+                span.end();
+                drain(provider, ctx);
+            }
+            catch (error) {
+                span.recordException(error instanceof Error ? error : new Error(String(error)));
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                span.end();
+                drain(provider, ctx);
+                throw error;
+            }
+        };
+    }
+    return wrapped;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heystack/otel",
-  "version": "0.2.1",
+  "version": "0.3.2",
   "description": "Runtime-aware OpenTelemetry tracing that exports to Heystack (Node, Next.js, Workers).",
   "license": "MIT",
   "type": "module",
@@ -22,6 +22,7 @@
   },
   "dependencies": {
     "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/core": "^1.30.0",
     "@opentelemetry/sdk-node": "^0.57.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.57.0",
     "@opentelemetry/auto-instrumentations-node": "^0.55.0",