@heystack/otel 0.18.0 → 0.19.1

package/dist/workers-coverage.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Which Cloudflare binding kinds Cloudflare's native tracing already spans.
+ * In native mode the SDK enriches ONLY the uncovered kinds so a D1/KV/R2/... call
+ * is never reported twice. WinterCG-safe: pure data, no imports.
+ */
+export type BindingKind = "d1" | "kv" | "r2" | "durable_object" | "queue" | "ai" | "vectorize" | "workflow" | "hyperdrive" | "analytics_engine" | "ratelimit" | "service" | "fetch";
+export declare const NATIVELY_COVERED: Readonly<Record<BindingKind, boolean>>;
+/** Native tracing does not propagate trace context to external (non-Cloudflare) services. */
+export declare const NATIVE_PROPAGATES_EXTERNAL = false;
+/** `enrich?.[kind] ?? !table[kind]` — `table` is a test seam. */
+export declare function shouldEnrichNatively(kind: BindingKind, enrich?: Partial<Record<BindingKind, boolean>>, table?: Readonly<Record<BindingKind, boolean>>): boolean;

package/dist/workers-coverage.js

@@ -0,0 +1,22 @@
+export const NATIVELY_COVERED = Object.freeze({
+    d1: true,
+    kv: true,
+    r2: true,
+    durable_object: true,
+    queue: true,
+    ratelimit: true,
+    fetch: true,
+    // Cloudflare propagates Worker-to-Worker calls automatically and emits `jsrpc.*` spans.
+    service: true,
+    ai: false,
+    vectorize: false,
+    workflow: false,
+    hyperdrive: false,
+    analytics_engine: false,
+});
+/** Native tracing does not propagate trace context to external (non-Cloudflare) services. */
+export const NATIVE_PROPAGATES_EXTERNAL = false;
+/** `enrich?.[kind] ?? !table[kind]` — `table` is a test seam. */
+export function shouldEnrichNatively(kind, enrich, table = NATIVELY_COVERED) {
+    return enrich?.[kind] ?? !table[kind];
+}

package/dist/workers-native.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Cloudflare-native custom span support (WinterCG-safe: only `@opentelemetry/api`
+ * and relative modules — no `node:*`).
+ *
+ * Cloudflare's `ctx.tracing` custom span API exposes NO trace/span ids, so
+ * `NativeOtelSpan.spanContext()` always returns INVALID_SPAN_CONTEXT — ids are
+ * never fabricated.
+ */
+import { type Span, type SpanAttributes, type SpanAttributeValue, type SpanContext, type SpanStatus as ApiSpanStatus, type Link, type Exception, type TimeInput } from "@opentelemetry/api";
+type Attr = string | number | boolean | undefined;
+/** Minimal public surface exposed by Cloudflare's Workers custom-spans API. */
+export interface CloudflareSpan {
+    readonly isTraced?: boolean;
+    setAttribute(key: string, value: Attr): unknown;
+    setAttributes?(attributes: Record<string, Attr>): unknown;
+    recordException?(exception: unknown): void;
+    end?(): void;
+}
+/** `ExecutionContext.tracing` without importing the `cloudflare:workers` module. */
+export interface CloudflareTracing {
+    enterSpan<T, A extends unknown[]>(name: string, callback: (span: CloudflareSpan, ...args: A) => T, ...args: A): T;
+    startActiveSpan?<T>(name: string, callback: (span: CloudflareSpan) => T): T;
+    startSpan?(name: string): CloudflareSpan;
+    getActiveSpan?(): CloudflareSpan | undefined;
+}
+/** @deprecated Use {@link CloudflareSpan}. */
+export type CloudflareNativeSpan = CloudflareSpan;
+/** @deprecated Use {@link CloudflareTracing}. */
+export type CloudflareNativeTracing = CloudflareTracing;
+/**
+ * Context key under which `runNativeSpan` / `withSpan` publish the request's
+ * Cloudflare native tracer, so nested helpers (and the fetch wrapper) can join
+ * the platform trace tree instead of creating OTel-provider spans.
+ */
+export declare const NATIVE_TRACING_CONTEXT_KEY: symbol;
+export declare function nativeTracingFromContext(): CloudflareTracing | undefined;
+/** workers.ts registers its global ContextManager bootstrap here (avoids an import cycle). */
+export declare function setNativeContextInit(fn: () => void): void;
+/**
+ * Adapts Cloudflare's deliberately-small Span API to the OTel API shape used by
+ * `withSpan`. Unsupported OTel operations degrade to attributes instead of
+ * creating a second exporter/provider.
+ */
+export declare class NativeOtelSpan implements Span {
+    private readonly nativeSpan;
+    private ended;
+    /** True once `recordException` stamped a specific `error.type` (the exception class). */
+    private errorTyped;
+    constructor(nativeSpan: CloudflareSpan);
+    spanContext(): SpanContext;
+    setAttribute(key: string, value: SpanAttributeValue): this;
+    setAttributes(attributes: SpanAttributes): this;
+    addEvent(name: string, attributesOrStartTime?: SpanAttributes | TimeInput): this;
+    addLink(_link: Link): this;
+    addLinks(_links: Link[]): this;
+    setStatus(status: ApiSpanStatus): this;
+    updateName(_name: string): this;
+    /** Calls the native `end` exactly once. */
+    end(_endTime?: TimeInput): void;
+    isRecording(): boolean;
+    recordException(exception: Exception, _time?: TimeInput): void;
+}
+/** Resolve the native tracer: explicit config override first, then `ctx.tracing`. */
+export declare function getNativeTracing(ctx: unknown, override?: CloudflareTracing): CloudflareTracing | null;
+export declare function runNativeSpan<T>(tracing: CloudflareTracing | null, name: string, attrs: Record<string, Attr>, fn: (span: NativeOtelSpan) => T | Promise<T>): Promise<T>;
+export {};

package/dist/workers-native.js

@@ -0,0 +1,147 @@
+/**
+ * Cloudflare-native custom span support (WinterCG-safe: only `@opentelemetry/api`
+ * and relative modules — no `node:*`).
+ *
+ * Cloudflare's `ctx.tracing` custom span API exposes NO trace/span ids, so
+ * `NativeOtelSpan.spanContext()` always returns INVALID_SPAN_CONTEXT — ids are
+ * never fabricated.
+ */
+import { context, createContextKey, INVALID_SPAN_CONTEXT, trace, SpanStatusCode, } from "@opentelemetry/api";
+/**
+ * Context key under which `runNativeSpan` / `withSpan` publish the request's
+ * Cloudflare native tracer, so nested helpers (and the fetch wrapper) can join
+ * the platform trace tree instead of creating OTel-provider spans.
+ */
+export const NATIVE_TRACING_CONTEXT_KEY = createContextKey("heystack.cloudflare.native-tracing");
+export function nativeTracingFromContext() {
+    return context.active().getValue(NATIVE_TRACING_CONTEXT_KEY);
+}
+let contextInit;
+/** workers.ts registers its global ContextManager bootstrap here (avoids an import cycle). */
+export function setNativeContextInit(fn) {
+    contextInit = fn;
+}
+/**
+ * Adapts Cloudflare's deliberately-small Span API to the OTel API shape used by
+ * `withSpan`. Unsupported OTel operations degrade to attributes instead of
+ * creating a second exporter/provider.
+ */
+export class NativeOtelSpan {
+    nativeSpan;
+    ended = false;
+    /** True once `recordException` stamped a specific `error.type` (the exception class). */
+    errorTyped = false;
+    constructor(nativeSpan) {
+        this.nativeSpan = nativeSpan;
+    }
+    spanContext() { return INVALID_SPAN_CONTEXT; }
+    setAttribute(key, value) {
+        try {
+            if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+                this.nativeSpan.setAttribute(key, value);
+            }
+            else if (Array.isArray(value)) {
+                this.nativeSpan.setAttribute(key, JSON.stringify(value));
+            }
+        }
+        catch {
+            // Telemetry must never surface as an application error; drop the attribute.
+        }
+        return this;
+    }
+    setAttributes(attributes) {
+        for (const [key, value] of Object.entries(attributes)) {
+            if (value !== undefined)
+                this.setAttribute(key, value);
+        }
+        return this;
+    }
+    addEvent(name, attributesOrStartTime) {
+        const prefix = `event.${name}`;
+        this.setAttribute(prefix, true);
+        if (attributesOrStartTime && !Array.isArray(attributesOrStartTime) && typeof attributesOrStartTime === "object") {
+            for (const [key, value] of Object.entries(attributesOrStartTime)) {
+                if (value !== undefined)
+                    this.setAttribute(`${prefix}.${key}`, value);
+            }
+        }
+        return this;
+    }
+    addLink(_link) { return this; }
+    addLinks(_links) { return this; }
+    setStatus(status) {
+        if (status.code === SpanStatusCode.ERROR) {
+            // Don't clobber the more specific class name a preceding recordException set.
+            if (!this.errorTyped)
+                this.setAttribute("error.type", "error");
+            if (status.message)
+                this.setAttribute("error.message", status.message);
+            this.setAttribute("otel.status_code", "ERROR");
+        }
+        return this;
+    }
+    updateName(_name) { return this; }
+    /** Calls the native `end` exactly once. */
+    end(_endTime) {
+        if (this.ended)
+            return;
+        this.ended = true;
+        try {
+            this.nativeSpan.end?.();
+        }
+        catch { /* never surface */ }
+    }
+    isRecording() { return this.nativeSpan.isTraced !== false; }
+    recordException(exception, _time) {
+        const error = exception instanceof Error ? exception : new Error(String(exception));
+        this.setAttribute("error.type", error.name || "Error");
+        this.errorTyped = true;
+        this.setAttribute("error.message", error.message);
+        if (error.stack)
+            this.setAttribute("exception.stacktrace", error.stack);
+        try {
+            this.nativeSpan.recordException?.(error);
+        }
+        catch { /* never surface */ }
+    }
+}
+/** Resolve the native tracer: explicit config override first, then `ctx.tracing`. */
+export function getNativeTracing(ctx, override) {
+    if (override && typeof override.enterSpan === "function")
+        return override;
+    const candidate = ctx?.tracing;
+    return candidate && typeof candidate.enterSpan === "function" ? candidate : null;
+}
+const NOOP_NATIVE_SPAN = { isTraced: false, setAttribute: () => undefined };
+export async function runNativeSpan(tracing, name, attrs, fn) {
+    contextInit?.();
+    const body = async (nativeSpan, ownsEnd) => {
+        const adapter = new NativeOtelSpan(nativeSpan);
+        for (const [key, value] of Object.entries(attrs)) {
+            if (value !== undefined)
+                adapter.setAttribute(key, value);
+        }
+        const base = tracing ? context.active().setValue(NATIVE_TRACING_CONTEXT_KEY, tracing) : context.active();
+        const nativeContext = trace.setSpan(base, adapter);
+        try {
+            return await context.with(nativeContext, () => fn(adapter));
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            adapter.recordException(err);
+            adapter.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+            throw error;
+        }
+        finally {
+            if (ownsEnd)
+                adapter.end();
+        }
+    };
+    if (!tracing)
+        return body(NOOP_NATIVE_SPAN, false);
+    if (typeof tracing.startActiveSpan === "function") {
+        return tracing.startActiveSpan(name, (s) => body(s, true));
+    }
+    // enterSpan ends the span when the callback settles.
+    return tracing.enterSpan(name, (s) => body(s, false));
+}

package/dist/workers-propagation.d.ts

@@ -0,0 +1,24 @@
+export interface NativePropagation {
+    traceId: string;
+    spanId: string;
+}
+export declare const NATIVE_PROPAGATION_CONTEXT_KEY: symbol;
+/** One synthetic trace/span pair standing for the whole invocation. */
+export declare function createNativePropagation(random?: (n: number) => Uint8Array): NativePropagation;
+export declare function propagationTraceparent(p: NativePropagation): string;
+export declare function isAiGatewayHost(url: URL): boolean;
+/** Hostname allow-check: undefined = all hosts, [] = none; string = exact host, RegExp tests the host. */
+export declare function propagationTargetAllowed(hostname: string, targets: ReadonlyArray<string | RegExp> | undefined): boolean;
+/**
+ * Return `[input, init]` with `traceparent` (and `cf-aig-otel-*` for the AI
+ * Gateway) added. Never overwrites an existing header, never mutates the
+ * caller's objects, and never consumes a Request body (the Request itself is
+ * passed through; only `init.headers` carries the merged set).
+ */
+export declare function injectOutboundHeaders(input: RequestInfo | URL, init: RequestInit | undefined, opts: {
+    traceparent: string;
+    aiGateway?: {
+        traceId: string;
+        parentSpanId: string;
+    };
+}): [RequestInfo | URL, RequestInit];

package/dist/workers-propagation.js

@@ -0,0 +1,72 @@
+/**
+ * Native-mode trace propagation (WinterCG-safe: no node:* imports).
+ *
+ * Cloudflare's native spans expose no trace/span ids, so the SDK mints ONE
+ * synthetic pair per invocation. It is emitted on outbound headers and recorded
+ * on the root span as `heystack.propagation.*` link attributes; ingest turns
+ * those into span links. The synthetic ids are NOT Cloudflare's native ids.
+ */
+import { createContextKey } from "@opentelemetry/api";
+import { detectLLMProvider } from "./llm-enrich.js";
+export const NATIVE_PROPAGATION_CONTEXT_KEY = createContextKey("heystack.native-propagation");
+function randomHex(bytes, random) {
+    for (let attempt = 0; attempt < 4; attempt++) {
+        const buf = random(bytes);
+        let hex = "";
+        let nonZero = false;
+        for (const b of buf) {
+            if (b !== 0)
+                nonZero = true;
+            hex += b.toString(16).padStart(2, "0");
+        }
+        if (nonZero)
+            return hex;
+    }
+    return "1".padStart(bytes * 2, "0");
+}
+const defaultRandom = (n) => crypto.getRandomValues(new Uint8Array(n));
+/** One synthetic trace/span pair standing for the whole invocation. */
+export function createNativePropagation(random = defaultRandom) {
+    return { traceId: randomHex(16, random), spanId: randomHex(8, random) };
+}
+export function propagationTraceparent(p) {
+    return `00-${p.traceId}-${p.spanId}-01`;
+}
+export function isAiGatewayHost(url) {
+    return detectLLMProvider(url.hostname) === "cloudflare";
+}
+/** Hostname allow-check: undefined = all hosts, [] = none; string = exact host, RegExp tests the host. */
+export function propagationTargetAllowed(hostname, targets) {
+    if (!targets)
+        return true;
+    const host = hostname.toLowerCase();
+    for (const t of targets) {
+        try {
+            if (typeof t === "string" ? t.toLowerCase() === host : t.test(host))
+                return true;
+        }
+        catch {
+            // bad pattern: skip
+        }
+    }
+    return false;
+}
+/**
+ * Return `[input, init]` with `traceparent` (and `cf-aig-otel-*` for the AI
+ * Gateway) added. Never overwrites an existing header, never mutates the
+ * caller's objects, and never consumes a Request body (the Request itself is
+ * passed through; only `init.headers` carries the merged set).
+ */
+export function injectOutboundHeaders(input, init, opts) {
+    const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
+    if (!headers.has("traceparent"))
+        headers.set("traceparent", opts.traceparent);
+    if (opts.aiGateway) {
+        if (!headers.has("cf-aig-otel-trace-id"))
+            headers.set("cf-aig-otel-trace-id", opts.aiGateway.traceId);
+        if (!headers.has("cf-aig-otel-parent-span-id")) {
+            headers.set("cf-aig-otel-parent-span-id", opts.aiGateway.parentSpanId);
+        }
+    }
+    return [input, { ...(init ?? {}), headers }];
+}

package/dist/workers-routes.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Route templating for Workers. `routes` patterns look like `/users/:id` or
+ * `/files/*`; the matched PATTERN (never the raw path) becomes `http.route`.
+ */
+/** First matching pattern wins; `:name` matches one segment, trailing `*` matches the rest. */
+export declare function matchRoute(pathname: string, routes: readonly string[]): string | undefined;
+/** Resolve `http.route`: `routeTemplate(req)` first, then `routes`. Never throws. */
+export declare function resolveRoute(req: Request, opts: {
+    routes?: readonly string[];
+    routeTemplate?: (req: Request) => string | undefined;
+}): string | undefined;

package/dist/workers-routes.js

@@ -0,0 +1,45 @@
+/**
+ * Route templating for Workers. `routes` patterns look like `/users/:id` or
+ * `/files/*`; the matched PATTERN (never the raw path) becomes `http.route`.
+ */
+const MAX_ROUTE_LEN = 256;
+function segs(p) {
+    return p.split("/").filter((s) => s !== "");
+}
+/** First matching pattern wins; `:name` matches one segment, trailing `*` matches the rest. */
+export function matchRoute(pathname, routes) {
+    const path = segs(pathname);
+    for (const pattern of routes) {
+        if (typeof pattern !== "string" || pattern === "")
+            continue;
+        const pat = segs(pattern);
+        const star = pat[pat.length - 1] === "*";
+        const fixed = star ? pat.slice(0, -1) : pat;
+        if (star ? path.length < fixed.length : path.length !== fixed.length)
+            continue;
+        const ok = fixed.every((p, i) => p[0] === ":" || p === path[i]);
+        if (ok)
+            return pattern;
+    }
+    return undefined;
+}
+/** Resolve `http.route`: `routeTemplate(req)` first, then `routes`. Never throws. */
+export function resolveRoute(req, opts) {
+    try {
+        const t = opts.routeTemplate?.(req);
+        if (typeof t === "string" && t !== "" && t.length <= MAX_ROUTE_LEN)
+            return t;
+    }
+    catch {
+        // a faulty user callback must never affect the request
+    }
+    if (opts.routes && opts.routes.length > 0) {
+        try {
+            return matchRoute(new URL(req.url).pathname, opts.routes);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}

package/dist/workers-sampler.d.ts

@@ -29,7 +29,16 @@ export declare function loadRemoteSamplingRate(opts: {
     apiKey: string;
     fetchImpl: typeof fetch;
 }): Promise<void>;
+export interface SamplerOptions {
+    /**
+     * Honour a REMOTE parent's sampled flag (an inbound `traceparent` `-01`/`-00`).
+     * Default `true`. When `false`, a remote parent gets the same ratio decision as
+     * a fresh root (over the continued trace id), so an untrusted caller can neither
+     * force recording nor suppress it. Local parents are always honoured.
+     */
+    trustRemoteParent?: boolean;
+}
 export declare function makeSampler(sampling?: {
     rate?: number;
     remote?: boolean;
-}): Sampler;
+}, opts?: SamplerOptions): Sampler;

package/dist/workers-sampler.js

@@ -74,16 +74,20 @@ export async function loadRemoteSamplingRate(opts) {
         /* fail open: leave rate at keep-all */
     }
 }
-export function makeSampler(sampling) {
+export function makeSampler(sampling, opts = {}) {
+    const parentBased = (root) => opts.trustRemoteParent === false
+        ? new ParentBasedSampler({ root, remoteParentSampled: root, remoteParentNotSampled: root })
+        : new ParentBasedSampler({ root });
     if (sampling?.remote) {
         // Dynamic rate: reads from the per-isolate ref that loadRemoteSamplingRate sets.
         // Starts at 1 (keep-all) until the config fetch resolves on the first request.
-        return new ParentBasedSampler({ root: new HeystackRatioSampler(() => _remoteRate.value) });
+        return parentBased(new HeystackRatioSampler(() => _remoteRate.value));
     }
     const rate = sampling?.rate;
     if (rate === undefined || rate >= 1)
         return new AlwaysOnSampler();
     // ParentBased: a sampled/dropped PARENT (local or remote via traceparent) wins,
     // so a distributed trace samples consistently; only the root uses the ratio.
-    return new ParentBasedSampler({ root: new HeystackRatioSampler(rate) });
+    // With trustRemoteParent=false a remote parent is re-decided by the ratio.
+    return parentBased(new HeystackRatioSampler(rate));
 }