@heystack/otel 0.2.1 → 0.3.0

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`.** See [Migration](#migration--versioning) below.
 
 ## Runtime matrix
 
@@ -70,6 +70,8 @@ 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. 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
@@ -83,12 +85,12 @@ Set the key as a secret: `wrangler secret put HEYSTACK_API_KEY`.
 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.
 
 ## Migration / versioning
 
-- **Pin `@heystack/otel` `>=0.2.0`** — the workerd-aware `/next` path and `initHeystackWorkers` / `flushHeystack` exports were added in 0.2.0.
+- **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,9 +29,16 @@ 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");
         initHeystackWorkers({ apiKey, service: o.service, endpoint: o.endpoint });

package/dist/workers.d.ts

@@ -69,6 +69,16 @@ 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;
     shutdown(): Promise<void>;
@@ -85,6 +95,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
@@ -110,10 +128,13 @@ export declare function createTracerProvider(config: HeystackOptions): HeystackT
  * (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;
@@ -150,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.
@@ -123,6 +139,16 @@ 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;
@@ -167,6 +193,25 @@ 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.
+        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() {
         return this.forceFlush().then(() => {
@@ -207,26 +252,45 @@ export function createTracerProvider(config) {
 // ---------------------------------------------------------------------------
 let _provider = null;
 /**
- * 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.
+ * 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`.
  */
-export function initHeystackWorkers(config) {
+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 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
@@ -276,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.
  */
@@ -288,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,

package/package.json

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