@heystack/otel 0.15.0 → 0.17.0

package/dist/workers.d.ts

@@ -1,4 +1,4 @@
-import { type Span } from "@opentelemetry/api";
+import { SpanKind, 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";
@@ -92,6 +92,8 @@ export declare class HeystackSpanExporter implements SpanExporter {
     readonly ingestHost: string;
     private readonly headers;
     private shutdownState;
+    /** Exports rejected before network work because the in-flight cap was hit. */
+    droppedPending: number;
     /**
      * In-flight export fetches. Each `export()` adds its settled-when-the-POST-
      * completes promise here and removes it on `finally`. `forceFlush()` awaits
@@ -112,10 +114,21 @@ export declare class HeystackSpanExporter implements SpanExporter {
     waitUntil?: (p: Promise<unknown>) => void;
     constructor(options: HeystackOptions);
     export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void;
+    /**
+     * POST the batch with ONE bounded automatic retry for network errors / 429 /
+     * 5xx. Honours `Retry-After` (seconds form) on 429 within the total backoff
+     * cap; after retries are exhausted it preserves plain FAILED semantics via
+     * `resultCallback`. The returned promise never rejects.
+     */
+    private postWithRetry;
+    /** Reserve a tracked slot synchronously before starting any network work. */
+    private reservePending;
     /**
      * 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.
+     * Sets `outcome.borrowed` when (and only when) a real `waitUntil` received
+     * `p` — the signal the no-handoff advisory keys off.
      */
     private handOffToCloudflareContext;
     private warnedWaitUntilFailure;
@@ -235,13 +248,11 @@ export interface WorkersConfig {
 /** Minimal public surface exposed by Cloudflare's Workers custom-spans API. */
 export interface CloudflareNativeSpan {
     readonly isTraced: boolean;
-    setAttribute(key: string, value: string | number | boolean | undefined): void;
-    end(): void;
+    setAttribute(key: string, value?: string | number | boolean): void;
 }
 /** `ExecutionContext.tracing` without importing the `cloudflare:workers` module. */
 export interface CloudflareNativeTracing {
-    enterSpan<T>(name: string, callback: (span: CloudflareNativeSpan) => T): T;
-    startActiveSpan<T>(name: string, callback: (span: CloudflareNativeSpan) => T): T;
+    enterSpan<T, A extends unknown[]>(name: string, callback: (span: CloudflareNativeSpan, ...args: A) => T, ...args: A): T;
 }
 /**
  * A `BasicTracerProvider` with the underlying `HeystackSpanExporter` attached so
@@ -273,9 +284,9 @@ export declare function createTracerProvider(config: HeystackOptions & {
  * context across `await` boundaries — child spans created after an `await`
  * inside a handler are correctly parented to the request's root span.
  *
- * WinterCG-safe: it does NOT import `node:async_hooks`; instead it uses the
- * ALS global that the runtime exposes. Falls back to `SyncStackContextManager`
- * when the global is absent (Deno, Bun without globals, etc.).
+ * WinterCG-safe: it does NOT import the Node-only async_hooks builtin; instead
+ * it uses the ALS global that the runtime exposes. Falls back to
+ * `SyncStackContextManager` when the global is absent (Deno, Bun without globals, etc.).
  */
 export declare class AlsContextManager implements ContextManager {
     private _als;
@@ -311,10 +322,12 @@ export declare function __resetContextManager(): void;
  * 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.
+ * — no app hook needed. For other workerd setups without it, wrap your
+ * handler's ExecutionContext with {@link wrapExecutionContext} (every
+ * `ctx.waitUntil` then also schedules the export drain), 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;
@@ -328,21 +341,25 @@ export declare function initHeystackWorkers(config: WorkersConfig & {
  * isolate is torn down. Best-effort no-op if no provider is registered.
  */
 export declare function flushHeystack(): Promise<void>;
+export declare function wrapExecutionContext<Props>(ctx: ExecutionContext<Props>): ExecutionContext<Props>;
 /** Reset the singleton global provider. Internal/testing helper. */
 export declare function __resetProvider(): void;
-/** Reset the once-only no-key warning. Internal/testing helper. */
+/** Reset the once-only warnings. Internal/testing helper. */
 export declare function __resetWarnings(): void;
 /**
  * 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.
+ * a Worker may also export `queue` / `scheduled` / `tail` / `email` (and
+ * arbitrary other siblings). `instrument()` traces `fetch`, `queue`,
+ * `scheduled`, `email` and `tail` when present — every other sibling is
+ * forwarded untouched, so wrapping never drops a handler Cloudflare requires
+ * for deploy.
  */
 interface WorkerHandler<E> {
     fetch?(req: Request, env: E, ctx: ExecutionContext): Promise<Response> | Response;
     queue?(batch: MessageBatch<any>, env: E, ctx: ExecutionContext): Promise<void> | void;
     scheduled?(controller: ScheduledController, env: E, ctx: ExecutionContext): Promise<void> | void;
+    email?(message: ForwardableEmailMessage, env: E, ctx: ExecutionContext): Promise<void> | void;
+    tail?(events: TraceItem[], env: E, ctx: ExecutionContext): Promise<void> | void;
     [key: string]: unknown;
 }
 /**
@@ -370,8 +387,8 @@ interface WorkerHandler<E> {
  * 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.
+ * a traced wrapper; `queue`, `scheduled`, `email` and `tail` 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.
@@ -383,7 +400,7 @@ interface WorkerHandler<E> {
  * 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 {
+type Instrumented<E, H> = Omit<H, "fetch" | "queue" | "scheduled" | "email" | "tail"> & (H extends {
     fetch: unknown;
 } ? {
     fetch: (req: Request, env: E, ctx: ExecutionContext) => Promise<Response>;
@@ -395,6 +412,14 @@ type Instrumented<E, H> = Omit<H, "fetch" | "queue" | "scheduled"> & (H extends
     scheduled: unknown;
 } ? {
     scheduled: (controller: ScheduledController, env: E, ctx: ExecutionContext) => Promise<void>;
+} : unknown) & (H extends {
+    email: unknown;
+} ? {
+    email: (message: ForwardableEmailMessage, env: E, ctx: ExecutionContext) => Promise<void>;
+} : unknown) & (H extends {
+    tail: unknown;
+} ? {
+    tail: (events: TraceItem[], env: E, ctx: ExecutionContext) => Promise<void>;
 } : unknown);
 /**
  * Recover a handler's concrete env type from whichever traced entrypoint it
@@ -412,6 +437,52 @@ type EnvOf<H> = H extends {
     scheduled: (controller: ScheduledController, env: infer E, ctx: ExecutionContext) => unknown;
 } ? E : unknown;
 export declare function instrument<H extends WorkerHandler<any>>(handler: H, config: WorkersConfig): Instrumented<EnvOf<H>, H>;
+export interface InstrumentClassesOpts {
+    /**
+     * Factory that creates and starts a new span. Called at method-invocation
+     * time. For integration: omit it — the global `heystack` tracer is used with
+     * the active context (or the explicit `parentCtx`). For unit tests inject a
+     * fake so no global provider is required.
+     */
+    startSpan?: (name: string, attrs: Record<string, unknown>, kind?: SpanKind, parentCtx?: Context) => Span;
+}
+/**
+ * Decorate a Durable Object class:
+ * - constructor: wraps the incoming `state` so `state.storage` operations emit
+ *   INTERNAL child spans (`DO storage get|put|delete|list`) with key/count attrs.
+ * - `fetch()`: SERVER span named `<METHOD> <path>` (like instrument()'s fetch
+ *   wrapper), continuing an inbound W3C traceparent, recording status/duration.
+ * - `alarm()`: INTERNAL span.
+ * - RPC prototype methods: SERVER span `DO rpc <method>` with rpc.method attrs.
+ *
+ * Every root span schedules flushHeystack() via `state.waitUntil` so exports
+ * complete before isolate teardown. Instance arrow-function methods assigned in
+ * the constructor are not enumerable on the prototype and stay unwrapped.
+ *
+ *   export class Counter extends DurableObject {
+ *     // ...
+ *   }
+ *   export const Counter = wrapDurableObjectClass(BaseCounter); // or decorate in place
+ */
+export declare function wrapDurableObjectClass<C extends {
+    readonly prototype: object;
+}>(cls: C, opts?: InstrumentClassesOpts): C;
+/**
+ * Decorate a Cloudflare Workflows entrypoint class so its `run(event, step)`
+ * emits a `workflow run` INTERNAL span with workflow identity/schedule metadata
+ * (never payload content), and the handed-out
+ * step object's methods become traced versions (see {@link wrapWorkflowStep}):
+ * `step.do(name, fn)` → INTERNAL span named `step <name>` with success/error
+ * status (step retries manifest as whole-run replays by the engine and are not
+ * observable at this layer, so no retry attribute is emitted), and
+ * sleep/sleepUntil/waitForEvent/waitForName → short marker spans.
+ *
+ * Every completed run schedules flushHeystack() via the entrypoint state's
+ * `waitUntil` so exports survive isolate teardown.
+ */
+export declare function wrapWorkflowEntrypointClass<C extends {
+    readonly prototype: object;
+}>(cls: C, opts?: InstrumentClassesOpts): C;
 /**
  * Run `fn` inside a new child span named `name`. The span is automatically
  * parented to the currently-active span (via `context.active()`), started