@heystack/otel 0.1.0 → 0.2.1

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.2.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,49 @@ 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
+);
+```
+
+`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 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.
+- **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.2.0`** — 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,19 @@ 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` 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
+ * `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,45 @@
 /**
  * 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` 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
+ * `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.
+    const g = globalThis;
+    const onWorkerd = g.navigator?.userAgent === "Cloudflare-Workers" ||
+        (typeof g.caches?.default !== "undefined" && !g.process?.versions?.node);
+    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,23 @@ 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;
     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 {
@@ -72,15 +86,49 @@ export interface WorkersConfig {
     apiKey?: string;
     endpoint?: string;
 }
+/**
+ * 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): BasicTracerProvider;
+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: 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.
+ */
+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 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 +136,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(

package/dist/workers.js

@@ -115,6 +115,14 @@ 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();
     constructor(options) {
         const cfg = buildExporterConfig(options);
         this.url = cfg.url;
@@ -136,7 +144,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 +165,22 @@ export class HeystackSpanExporter {
                 error: error instanceof Error ? error : new Error(String(error)),
             });
         });
+        this.pending.add(p);
+        p.finally(() => this.pending.delete(p));
     }
     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 +189,65 @@ 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;
+/**
+ * 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.
+ */
+export function initHeystackWorkers(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.
+    trace.setGlobalTracerProvider(_provider);
+    return _provider;
+}
+/**
+ * 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 +262,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(
@@ -228,7 +304,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.2.1",
   "description": "Runtime-aware OpenTelemetry tracing that exports to Heystack (Node, Next.js, Workers).",
   "license": "MIT",
   "type": "module",