@heystack/otel 0.1.0 → 0.3.0

package/README.md

@@ -13,13 +13,15 @@ Always read your key from the environment — never paste it into source:
 HEYSTACK_API_KEY=sk_live_…
 ```
 
+> **Requires `@heystack/otel` `>=0.3.0`.** See [Migration](#migration--versioning) below.
+
 ## Runtime matrix
 
 | Runtime | Import | Notes |
 | --- | --- | --- |
-| Node / Express / Fastify / workers (long-running) | `@heystack/otel/node` | Auto-instrumentations + graceful shutdown. |
-| Next.js (`instrumentation.ts`) | `@heystack/otel/next` | Runtime-guarded; no-op on Edge. |
-| Cloudflare Workers / Edge | `@heystack/otel/workers` | Coming soon — the Node SDK can't run on Workers/Edge. |
+| Next.js — **any** deploy target (Vercel/Node **and** Cloudflare/OpenNext) | `@heystack/otel/next` | `registerHeystack` in `instrumentation.ts`. Auto-detects Node vs Cloudflare workerd and picks the right exporter. No-op on Edge. |
+| Standalone Cloudflare Workers (hand-written `export default { fetch }`) | `@heystack/otel/workers` | `instrument()` wraps your handler. Fetch-based exporter, flushes via `ctx.waitUntil`. |
+| Node / Express / Fastify / NestJS (long-running server) | `@heystack/otel/node` | `initHeystack`: auto-instrumentations + graceful shutdown. |
 | Anywhere (pure helpers) | `@heystack/otel` | `buildExporterConfig`, types. No Node SDK loaded. |
 
 ## Node / Express / etc.
@@ -34,7 +36,7 @@ initHeystack({ apiKey: process.env.HEYSTACK_API_KEY, service: "my-app" });
 
 This enables auto-instrumentations (HTTP, Express, etc.) so you get spans without manual wiring.
 
-## Next.js
+## Next.js (any deploy target, including Cloudflare/OpenNext)
 
 In `instrumentation.ts` at the project root:
 
@@ -45,11 +47,51 @@ export async function register() {
 }
 ```
 
-`apiKey` defaults to `process.env.HEYSTACK_API_KEY`. `registerHeystack` only initialises on the Node.js runtime — on the Edge runtime it's a no-op, so it's safe to call unconditionally.
+`apiKey` defaults to `process.env.HEYSTACK_API_KEY`. `registerHeystack` is **runtime-aware** and safe to call unconditionally:
+
+- **Vercel / Node deploys** → uses the Node OTel SDK (auto-instrumentations).
+- **Cloudflare / OpenNext (workerd)** → Next still reports `NEXT_RUNTIME === "nodejs"`, but the code actually runs on workerd where the Node SDK's `node:http` OTLP exporter can't send (it initializes and silently exports nothing). `registerHeystack` detects workerd and registers the **fetch-based** exporter instead, so framework spans actually ship. No separate setup or import needed.
+- **Edge runtime** → no-op (neither SDK can run there).
+
+## Standalone Cloudflare Workers
+
+For a hand-written Worker (`export default { fetch }`), wrap the handler with `instrument()`:
+
+```ts
+import { instrument } from "@heystack/otel/workers";
+
+export default instrument(
+  {
+    async fetch(req, env, ctx) {
+      return new Response("ok");
+    },
+  },
+  { service: "my-worker" }, // apiKey defaults to env.HEYSTACK_API_KEY
+);
+```
+
+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. Note: on workerd there is no async context manager, so cross-`await` parent→child context propagation is limited; spans still export, but automatic parent linking across `await` boundaries is not guaranteed.
+
+`instrument()` must be the **outermost** wrapper if other middleware also wraps the handler, so the request span covers everything inside:
+
+```ts
+export default instrument(withOtherMiddleware(worker), { service: "my-worker" });
+```
+
+Set the key as a secret: `wrangler secret put HEYSTACK_API_KEY`.
+
+## 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 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.
 
-## Workers / Edge
+## Migration / versioning
 
-Coming in `@heystack/otel/workers` — the Node SDK can't run on Workers/Edge, so a dedicated, fetch-based entry handles those runtimes.
+- **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

@@ -2,8 +2,22 @@ import type { HeystackOptions } from "./core.js";
 /**
  * Call from Next.js instrumentation.ts:
  *   export function register() { registerHeystack({ service: "my-app" }); }
- * apiKey defaults to process.env.HEYSTACK_API_KEY. Only initialises on the Node.js
- * runtime — on Edge it's a no-op (the Node SDK can't run there).
+ * apiKey defaults to process.env.HEYSTACK_API_KEY.
+ *
+ * Runtime-aware: this runs on the Node.js runtime (NEXT_RUNTIME === "nodejs"),
+ * but that runtime can actually be Cloudflare workerd under OpenNext — where the
+ * Node SDK's node:http OTLP exporter silently sends nothing. We detect workerd
+ * 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` 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.
  */
 export declare function registerHeystack(o: Partial<HeystackOptions> & {
     service: string;

package/dist/next.js

@@ -1,23 +1,55 @@
 /**
  * Call from Next.js instrumentation.ts:
  *   export function register() { registerHeystack({ service: "my-app" }); }
- * apiKey defaults to process.env.HEYSTACK_API_KEY. Only initialises on the Node.js
- * runtime — on Edge it's a no-op (the Node SDK can't run there).
+ * apiKey defaults to process.env.HEYSTACK_API_KEY.
+ *
+ * Runtime-aware: this runs on the Node.js runtime (NEXT_RUNTIME === "nodejs"),
+ * but that runtime can actually be Cloudflare workerd under OpenNext — where the
+ * Node SDK's node:http OTLP exporter silently sends nothing. We detect workerd
+ * 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` 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.
  */
 export async function registerHeystack(o) {
-    // Next sets NEXT_RUNTIME to "nodejs" | "edge"
-    if (process.env.NEXT_RUNTIME !== "nodejs")
+    // Edge runtime can't run either SDK path — skip.
+    if (process.env.NEXT_RUNTIME === "edge")
         return;
     const apiKey = o.apiKey ?? process.env.HEYSTACK_API_KEY;
     if (!apiKey) {
         console.warn("[heystack] HEYSTACK_API_KEY not set — tracing disabled");
         return;
     }
-    const { initHeystack } = await import("./node.js");
-    initHeystack({
-        apiKey,
-        service: o.service,
-        endpoint: o.endpoint,
-        debug: o.debug,
-    });
+    // 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.WebSocketPair !== "undefined";
+    if (onWorkerd) {
+        const { initHeystackWorkers } = await import("./workers.js");
+        initHeystackWorkers({ apiKey, service: o.service, endpoint: o.endpoint });
+    }
+    else {
+        const { initHeystack } = await import("./node.js");
+        initHeystack({
+            apiKey,
+            service: o.service,
+            endpoint: o.endpoint,
+            debug: o.debug,
+        });
+    }
 }

package/dist/workers.d.ts

@@ -61,9 +61,33 @@ export declare class HeystackSpanExporter implements SpanExporter {
     private readonly url;
     private readonly headers;
     private shutdownState;
+    /**
+     * In-flight export fetches. Each `export()` adds its settled-when-the-POST-
+     * completes promise here and removes it on `finally`. `forceFlush()` awaits
+     * this set so callers (and `ctx.waitUntil`) genuinely wait for the network
+     * write before the isolate is torn down — otherwise traces are silently
+     * 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;
     shutdown(): Promise<void>;
+    /**
+     * Resolve only once every in-flight export fetch has settled. This is the
+     * guaranteed drain path: the OTel `SimpleSpanProcessor.forceFlush()` does not
+     * await our fire-and-forget fetch, so callers must await this directly (see
+     * `flushHeystack` and `instrument`).
+     */
     forceFlush(): Promise<void>;
 }
 export interface WorkersConfig {
@@ -71,16 +95,61 @@ 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
+ * flush paths can drain its in-flight fetches directly (the OTel processor's
+ * `forceFlush()` does not await our fire-and-forget fetch).
+ */
+export type HeystackTracerProvider = BasicTracerProvider & {
+    readonly heystackExporter: HeystackSpanExporter;
+};
 /**
  * Build a `BasicTracerProvider` wired to a `HeystackSpanExporter` via a
  * `SimpleSpanProcessor`. Exposed for advanced users who want to add manual
  * spans; for typical use prefer {@link instrument}.
  *
  * On Workers each request should get its own short-lived provider so its spans
- * can be flushed via `ctx.waitUntil(provider.forceFlush())`.
+ * can be flushed. IMPORTANT: to actually wait for the export network write you
+ * must drain the exporter — `await provider.heystackExporter.forceFlush()` (or
+ * `flushHeystack()`), not just `provider.forceFlush()`.
+ */
+export declare function createTracerProvider(config: HeystackOptions): HeystackTracerProvider;
+/**
+ * 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 declare function initHeystackWorkers(config: WorkersConfig & {
+    apiKey: string;
+}): HeystackTracerProvider;
+/**
+ * Force-flush any pending spans AND wait for the export network write to
+ * complete. This awaits both the OTel provider's `forceFlush()` (drains the
+ * span processor) and the exporter's own pending-fetch set (the part the OTel
+ * processor does not await) — so on workerd you can hand this to
+ * `ctx.waitUntil(flushHeystack())` and the POST genuinely finishes before the
+ * isolate is torn down. Best-effort no-op if no provider is registered.
  */
-export declare function createTracerProvider(config: HeystackOptions): BasicTracerProvider;
+export declare function flushHeystack(): Promise<void>;
+/** Reset the singleton global provider. Internal/testing helper. */
+export declare function __resetProvider(): void;
 /** Reset the once-only no-key warning. Internal/testing helper. */
 export declare function __resetWarnings(): void;
 interface FetchHandler<E> {
@@ -88,8 +157,13 @@ interface FetchHandler<E> {
 }
 /**
  * Wrap a Worker's default export so every request is auto-traced with a SERVER
- * span. The export is flushed via `ctx.waitUntil` so it completes after the
- * response is returned.
+ * 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(
@@ -97,6 +171,12 @@ interface FetchHandler<E> {
  *     { service: "my-worker" },
  *   );
  *
+ * TRACE TREE: `instrument()` sets up the singleton GLOBAL tracer provider and
+ * creates the per-request SERVER 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 SERVER span.
+ *
  * If no API key is available (neither `config.apiKey` nor
  * `env.HEYSTACK_API_KEY`), the handler runs untraced.
  */

package/dist/workers.js

@@ -17,6 +17,22 @@ 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 _cfAccessorLoaded = false;
+/** Best-effort, once-only resolve of OpenNext's `getCloudflareContext`. */
+async function loadCloudflareContextAccessor() {
+    if (_cfAccessorLoaded)
+        return;
+    _cfAccessorLoaded = true;
+    try {
+        const spec = "@opennextjs/cloudflare";
+        const m = (await import(/* @vite-ignore */ spec));
+        _getCloudflareContext = m.getCloudflareContext;
+    }
+    catch {
+        // Not on OpenNext (or the package isn't installed) — fall back silently.
+    }
+}
 /** Convert an OTel HrTime `[seconds, nanos]` tuple to a nanosecond string. */
 function hrTimeToUnixNano(time) {
     // BigInt math keeps full nanosecond precision without float rounding.
@@ -115,6 +131,24 @@ export class HeystackSpanExporter {
     url;
     headers;
     shutdownState = false;
+    /**
+     * In-flight export fetches. Each `export()` adds its settled-when-the-POST-
+     * completes promise here and removes it on `finally`. `forceFlush()` awaits
+     * this set so callers (and `ctx.waitUntil`) genuinely wait for the network
+     * write before the isolate is torn down — otherwise traces are silently
+     * 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;
@@ -136,7 +170,10 @@ export class HeystackSpanExporter {
             return;
         }
         const body = JSON.stringify(serializeSpans(spans));
-        fetch(this.url, { method: "POST", headers: this.headers, body })
+        // 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 })
             .then((res) => {
             if (res.ok) {
                 resultCallback({ code: ExportResultCode.SUCCESS });
@@ -154,13 +191,41 @@ export class HeystackSpanExporter {
                 error: error instanceof Error ? error : new Error(String(error)),
             });
         });
+        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.
+        try {
+            if (this.waitUntil) {
+                this.waitUntil(p);
+            }
+            else if (_getCloudflareContext) {
+                const cf = _getCloudflareContext();
+                cf?.ctx?.waitUntil?.(p);
+            }
+        }
+        catch {
+            // Not inside a request context (or unavailable) — rely on `pending` +
+            // manual flush. Never let this break the export.
+        }
     }
     shutdown() {
-        this.shutdownState = true;
-        return Promise.resolve();
+        return this.forceFlush().then(() => {
+            this.shutdownState = true;
+        });
     }
-    forceFlush() {
-        return Promise.resolve();
+    /**
+     * Resolve only once every in-flight export fetch has settled. This is the
+     * guaranteed drain path: the OTel `SimpleSpanProcessor.forceFlush()` does not
+     * await our fire-and-forget fetch, so callers must await this directly (see
+     * `flushHeystack` and `instrument`).
+     */
+    async forceFlush() {
+        await Promise.allSettled([...this.pending]);
     }
 }
 /**
@@ -169,14 +234,84 @@ export class HeystackSpanExporter {
  * spans; for typical use prefer {@link instrument}.
  *
  * On Workers each request should get its own short-lived provider so its spans
- * can be flushed via `ctx.waitUntil(provider.forceFlush())`.
+ * can be flushed. IMPORTANT: to actually wait for the export network write you
+ * must drain the exporter — `await provider.heystackExporter.forceFlush()` (or
+ * `flushHeystack()`), not just `provider.forceFlush()`.
  */
 export function createTracerProvider(config) {
     const exporter = new HeystackSpanExporter(config);
-    return new BasicTracerProvider({
+    const provider = new BasicTracerProvider({
         resource: new Resource({ [ATTR_SERVICE_NAME]: config.service }),
         spanProcessors: [new SimpleSpanProcessor(exporter)],
     });
+    // Attach the exporter so flush paths can await its in-flight fetches.
+    return Object.assign(provider, { heystackExporter: exporter });
+}
+// ---------------------------------------------------------------------------
+// Global tracer provider registration (for host frameworks, e.g. Next.js)
+// ---------------------------------------------------------------------------
+let _provider = null;
+/**
+ * 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);
+    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 doesn't pull in a context manager that may not run on
+    // workerd.
+    trace.setGlobalTracerProvider(_provider);
+    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
+ * span processor) and the exporter's own pending-fetch set (the part the OTel
+ * processor does not await) — so on workerd you can hand this to
+ * `ctx.waitUntil(flushHeystack())` and the POST genuinely finishes before the
+ * isolate is torn down. Best-effort no-op if no provider is registered.
+ */
+export async function flushHeystack() {
+    if (!_provider)
+        return;
+    if (typeof _provider.forceFlush === "function") {
+        await _provider.forceFlush();
+    }
+    // The processor's forceFlush does not await our fire-and-forget fetch, so
+    // drain the exporter's in-flight POSTs explicitly.
+    await _provider.heystackExporter.forceFlush();
+}
+/** Reset the singleton global provider. Internal/testing helper. */
+export function __resetProvider() {
+    _provider = null;
 }
 let warnedNoKey = false;
 function warnOnceNoKey() {
@@ -191,8 +326,13 @@ export function __resetWarnings() {
 }
 /**
  * Wrap a Worker's default export so every request is auto-traced with a SERVER
- * span. The export is flushed via `ctx.waitUntil` so it completes after the
- * response is returned.
+ * 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(
@@ -200,6 +340,12 @@ export function __resetWarnings() {
  *     { service: "my-worker" },
  *   );
  *
+ * TRACE TREE: `instrument()` sets up the singleton GLOBAL tracer provider and
+ * creates the per-request SERVER 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 SERVER span.
+ *
  * If no API key is available (neither `config.apiKey` nor
  * `env.HEYSTACK_API_KEY`), the handler runs untraced.
  */
@@ -212,12 +358,18 @@ export function instrument(handler, config) {
                 warnOnceNoKey();
                 return handler.fetch(req, env, ctx);
             }
-            const provider = createTracerProvider({
+            // Set up (once) the global provider so spans created via the global
+            // `trace.getTracer()` API — nested framework/library/manual spans —
+            // export too, yielding a trace tree rather than a lone SERVER span.
+            const provider = ensureGlobalProvider({
                 apiKey,
                 service: config.service,
                 endpoint: config.endpoint,
+                waitUntil: config.waitUntil,
             });
-            const tracer = provider.getTracer("@heystack/otel/workers");
+            // Create the SERVER span via the GLOBAL tracer so it shares the provider
+            // (and context) used by nested global spans.
+            const tracer = trace.getTracer("heystack");
             const url = new URL(req.url);
             const span = tracer.startSpan(`${req.method} ${url.pathname}`, {
                 kind: SpanKind.SERVER,
@@ -228,7 +380,14 @@ export function instrument(handler, config) {
                     "server.address": url.host,
                 },
             });
-            const flush = () => ctx.waitUntil(provider.forceFlush());
+            // 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));
                 span.setAttribute("http.response.status_code", response.status);

package/package.json

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