@heystack/otel 0.4.2 → 0.5.0

package/dist/workers.d.ts

@@ -23,6 +23,11 @@ interface OtlpKeyValue {
     key: string;
     value: OtlpAnyValue;
 }
+interface OtlpSpanEvent {
+    timeUnixNano: string;
+    name: string;
+    attributes: OtlpKeyValue[];
+}
 interface OtlpSpan {
     traceId: string;
     spanId: string;
@@ -32,6 +37,7 @@ interface OtlpSpan {
     startTimeUnixNano: string;
     endTimeUnixNano: string;
     attributes: OtlpKeyValue[];
+    events: OtlpSpanEvent[];
     status: {
         code: number;
         message?: string;
@@ -54,6 +60,14 @@ interface OtlpTracesPayload {
  * hence the same resource, so we emit a single resourceSpans entry.
  */
 export declare function serializeSpans(spans: ReadableSpan[]): OtlpTracesPayload;
+/** Parse a W3C `traceparent`. Returns null for malformed or all-zero ids. */
+export declare function parseTraceparent(header: string | null): {
+    traceId: string;
+    spanId: string;
+    traceFlags: number;
+} | null;
+/** Add `value` to Access-Control-Expose-Headers without duplicating it. */
+export declare function appendExposeHeader(headers: Headers, value: string): void;
 /**
  * Test-only helper: run the self-span attribute check directly against a plain
  * attribute bag + ingest hostname, without constructing a ReadableSpan. The
@@ -61,6 +75,12 @@ export declare function serializeSpans(spans: ReadableSpan[]): OtlpTracesPayload
  * the exporter derives via `safeHostname(cfg.url)`.
  */
 export declare function isSelfSpanForTest(attrs: Record<string, unknown>, ingestHost: string): boolean;
+/**
+ * Reset the outbound-fetch instrumentation: restore the captured platform fetch
+ * (only when our wrapper is still the installed global) and clear the guard.
+ * Internal/testing helper.
+ */
+export declare function __resetFetchInstrumentation(): void;
 /**
  * A WinterCG-compatible OTLP/JSON span exporter. POSTs ended spans to the
  * Heystack ingest using the platform `fetch` — no Node built-ins.
@@ -68,7 +88,7 @@ export declare function isSelfSpanForTest(attrs: Record<string, unknown>, ingest
 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;
+    readonly ingestHost: string;
     private readonly headers;
     private shutdownState;
     /**
@@ -122,6 +142,23 @@ export interface WorkersConfig {
      * automatically borrows the request context's `ctx.waitUntil`.
      */
     waitUntil?: (p: Promise<unknown>) => void;
+    /**
+     * Optional hook called on each incoming request to supply identity context.
+     * Return `{ id }` to tag the SERVER span with `enduser.id`, `{ session }` for
+     * `session.id`, or `{ requestId }` to override `http.request.id` (otherwise
+     * the `cf-ray` request header is used as a fallback). Any field may be omitted.
+     */
+    getUser?: (req: Request) => {
+        id?: string;
+        session?: string;
+        requestId?: string;
+    } | undefined;
+    /**
+     * Declare which bindings to instrument with tracing (Task 5). Pass `true` to
+     * trace all bindings, or an array of binding names to trace selectively.
+     * Defaults to `false` (no binding tracing). Consumed by a later task.
+     */
+    instrumentBindings?: boolean | string[];
 }
 /**
  * A `BasicTracerProvider` with the underlying `HeystackSpanExporter` attached so
@@ -143,12 +180,31 @@ export type HeystackTracerProvider = BasicTracerProvider & {
  */
 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).
+ * An AsyncLocalStorage-backed ContextManager for the /workers entry. When the
+ * runtime exposes `globalThis.AsyncLocalStorage` (workerd and Node do), this
+ * manager is preferred over `SyncStackContextManager` because it propagates
+ * 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.).
+ */
+export declare class AlsContextManager implements ContextManager {
+    private _als;
+    constructor();
+    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;
+}
+/**
+ * A minimal SYNCHRONOUS, stack-based ContextManager — the fallback for the
+ * /workers entry when `globalThis.AsyncLocalStorage` is absent (any WinterCG
+ * runtime without the global). It makes `context.with()` propagate
+ * synchronously, which is enough for the exporter's `suppressTracing` to take
+ * effect — but it does NOT carry context across `await` boundaries.
  */
 export declare class SyncStackContextManager implements ContextManager {
     private _stack;
@@ -269,4 +325,22 @@ 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>;
+/**
+ * Run `fn` inside a new child span named `name`. The span is automatically
+ * parented to the currently-active span (via `context.active()`), started
+ * before `fn` and ended in `finally` — so the caller never needs to call
+ * `span.end()`. If `fn` throws, the exception is recorded on the span and
+ * the status is set to ERROR before re-throwing.
+ *
+ * Two call signatures are supported:
+ *   withSpan("name", async (span) => { ... })
+ *   withSpan("name", { attr: "value" }, async (span) => { ... })
+ */
+export declare function withSpan<T>(name: string, fn: (span: Span) => T | Promise<T>): Promise<T>;
+export declare function withSpan<T>(name: string, attrs: Record<string, string | number | boolean>, fn: (span: Span) => T | Promise<T>): Promise<T>;
+/**
+ * Add a named event (with optional attributes) to the currently-active span.
+ * No-op when no span is active.
+ */
+export declare function addEvent(name: string, attrs?: Record<string, string | number | boolean>): void;
 export type { Span };