@heystack/otel 0.18.0 → 0.19.1

package/dist/workers.d.ts

@@ -3,6 +3,10 @@ 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";
 import { type LLMGatewayConfig } from "./llm-enrich.js";
+import { wrapSqlClient } from "./workers-bindings.js";
+import { NATIVELY_COVERED, NATIVE_PROPAGATES_EXTERNAL, shouldEnrichNatively, type BindingKind } from "./workers-coverage.js";
+import { type CloudflareSpan, type CloudflareTracing } from "./workers-native.js";
+import { type SpanPrivacyOptions } from "./redact.js";
 declare const ExportResultCode: {
     readonly SUCCESS: 0;
     readonly FAILED: 1;
@@ -54,13 +58,15 @@ interface OtlpTracesPayload {
         }[];
     }[];
 }
+/** Per-span attribute transform applied at serialization (privacy pass). */
+type AttributeTransform = (attrs: Record<string, unknown>, span: ReadableSpan) => Record<string, unknown>;
 /**
  * Serialize a batch of ended spans into a single OTLP/JSON traces payload.
  *
  * All spans in a SimpleSpanProcessor batch share the same per-request provider,
  * hence the same resource, so we emit a single resourceSpans entry.
  */
-export declare function serializeSpans(spans: ReadableSpan[]): OtlpTracesPayload;
+export declare function serializeSpans(spans: ReadableSpan[], transform?: AttributeTransform): OtlpTracesPayload;
 /** Parse a W3C `traceparent`. Returns null for malformed or all-zero ids. */
 export declare function parseTraceparent(header: string | null): {
     traceId: string;
@@ -112,7 +118,13 @@ export declare class HeystackSpanExporter implements SpanExporter {
      * the `pending` set + manual `flushHeystack()` when absent/unavailable.
      */
     waitUntil?: (p: Promise<unknown>) => void;
-    constructor(options: HeystackOptions);
+    /**
+     * Privacy pass on every exported span — redacts URL attributes (`url.full`,
+     * `http.url`, `http.target`, `url.query`, …) so spans from host frameworks
+     * (Next/OpenNext, manual spans) are covered too, not just Heystack's own.
+     */
+    private readonly privacy;
+    constructor(options: HeystackOptions & SpanPrivacyOptions);
     export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void;
     /**
      * POST the batch with ONE bounded automatic retry for network errors / 429 /
@@ -143,7 +155,7 @@ export declare class HeystackSpanExporter implements SpanExporter {
      */
     forceFlush(): Promise<void>;
 }
-export interface WorkersConfig {
+export interface WorkersConfig extends SpanPrivacyOptions {
     service: string;
     /** Defaults to env.HEYSTACK_API_KEY at request time if omitted. */
     apiKey?: string;
@@ -185,17 +197,33 @@ export interface WorkersConfig {
      * Defaults to `false` (no binding tracing). Consumed by a later task.
      */
     instrumentBindings?: boolean | string[];
+    /**
+     * Native mode only: per-kind override of which bindings the SDK enriches on
+     * top of Cloudflare's own spans. Default: only kinds Cloudflare does not trace
+     * (`ai`, `vectorize`, `workflow`, `hyperdrive`, `analytics_engine`). Set
+     * `{ ai: false }` to opt out or `{ d1: true }` to force-enrich a covered kind.
+     * Ignored when `instrumentBindings` is set explicitly.
+     */
+    nativeEnrichment?: Partial<Record<BindingKind, boolean>>;
     /**
      * Select the Workers tracing plane. `auto` (default) uses Cloudflare's native
      * tracer when `ctx.tracing` is available and otherwise falls back to direct
      * OTLP export. `native` prefers the platform tracer but still fails open when
      * unavailable. `direct` always uses Heystack's fetch exporter.
      *
-     * Native mode deliberately disables Heystack root/fetch/binding
-     * instrumentation: Cloudflare already emits those spans, and running both
-     * creates duplicate, disconnected trace trees.
+     * Native mode creates no OTel provider and does not re-instrument what
+     * Cloudflare already spans (fetch, D1, KV, R2, DO, Queues, rate limit,
+     * service bindings). It enriches only the uncovered binding kinds (Workers AI,
+     * Vectorize, Workflows, Analytics Engine; Hyperdrive via `wrapSqlClient`) as
+     * native child spans, gated by `nativeEnrichment` / an explicit
+     * `instrumentBindings`.
      */
     nativeTracing?: "auto" | "native" | "direct";
+    /**
+     * Explicit Cloudflare tracer (`ctx.tracing`) for contexts that have none of
+     * their own, e.g. Durable Objects. Preferred over `ctx.tracing` when set.
+     */
+    tracing?: CloudflareTracing;
     /**
      * Head-sampling configuration. When omitted (or `rate` >= 1), all traces are
      * kept. When `rate` < 1, a deterministic FNV-1a hash of the trace ID decides
@@ -204,7 +232,9 @@ export interface WorkersConfig {
      *
      * Note: head sampling is parent-respecting, so an incoming request carrying a
      * sampled `traceparent` is still recorded even at `rate: 0` (it is not an
-     * absolute kill-switch; it governs only fresh/root traces).
+     * absolute kill-switch; it governs only fresh/root traces) — unless
+     * `trustInboundSampling: false`, which makes the rate decide for inbound
+     * traces too.
      *
      * When `remote: true`, the sampling rate is fetched once per isolate from
      * `{endpoint}/v1/sampling/config` on the first request. Cold-isolate spans
@@ -215,6 +245,25 @@ export interface WorkersConfig {
         rate?: number;
         remote?: boolean;
     };
+    /**
+     * Whether an inbound W3C `traceparent` sampled flag (`-01` / `-00`) decides
+     * keep/drop for the request's trace. Default `true` (parent-based sampling,
+     * so a browser→Worker trace samples consistently). Set `false` on a Worker
+     * that receives traffic from callers you don't control: the trace id is
+     * still continued (correlation is kept) but the keep/drop decision is made
+     * by THIS Worker's `sampling` rate over the trace id, so a client can't force
+     * recording with `-01` (or hide its requests with `-00`). Only meaningful when
+     * `sampling` is set (with no rate every trace is kept anyway).
+     */
+    trustInboundSampling?: boolean;
+    /**
+     * Cloudflare geo attributes recorded on the SERVER span from `req.cf`.
+     * `"country"` (default) records only `geo.country`; `"full"` also records
+     * `geo.region`, `geo.city` and `geo.asn`; `false` records none. The end-user
+     * IP (`client.address`) is separate and off by default — see
+     * {@link SpanPrivacyOptions.captureClientIp}.
+     */
+    captureGeo?: "country" | "full" | false;
     /**
      * LLM/gen_ai capture for outbound calls to known providers (OpenAI, Anthropic,
      * Mistral, Google, CF AI Gateway). Metadata (model, tokens, latency,
@@ -243,17 +292,36 @@ export interface WorkersConfig {
         redact?: (text: string) => string;
         maxContentChars?: number;
         gateways?: LLMGatewayConfig[];
+        /**
+         * The Cloudflare AI Gateway exports its own OTel spans for these calls.
+         * When true the SDK's LLM span is marked `heystack.ai.delegated` so the
+         * call is counted once (by the gateway). Opt-in: without it the SDK span is
+         * the counted one, so an AI call isn't lost if the gateway's own export
+         * isn't configured. The `cf-aig-otel-*` headers are sent either way.
+         */
+        gatewayExport?: boolean;
     };
+    /**
+     * Path templates for `http.route`, e.g. `["/users/:id", "/files/*"]` (first
+     * match wins; a trailing `*` matches the rest). If neither this nor
+     * `routeTemplate` is set, `http.route` is omitted and Heystack templates the
+     * path server-side.
+     */
+    routes?: string[];
+    /** Compute the `http.route` template per request; wins over `routes`. */
+    routeTemplate?: (req: Request) => string | undefined;
+    /**
+     * Hostnames (exact string or RegExp) that receive `traceparent` (and AI
+     * Gateway headers) on native-mode outbound fetches. Default: every host except
+     * the Heystack ingest endpoint. `[]` disables propagation.
+     */
+    propagateTargets?: Array<string | RegExp>;
 }
-/** Minimal public surface exposed by Cloudflare's Workers custom-spans API. */
-export interface CloudflareNativeSpan {
-    readonly isTraced: boolean;
-    setAttribute(key: string, value?: string | number | boolean): void;
-}
-/** `ExecutionContext.tracing` without importing the `cloudflare:workers` module. */
-export interface CloudflareNativeTracing {
-    enterSpan<T, A extends unknown[]>(name: string, callback: (span: CloudflareNativeSpan, ...args: A) => T, ...args: A): T;
-}
+export type { CloudflareSpan, CloudflareTracing };
+/** @deprecated Use {@link CloudflareSpan}. */
+export type CloudflareNativeSpan = CloudflareSpan;
+/** @deprecated Use {@link CloudflareTracing}. */
+export type CloudflareNativeTracing = CloudflareTracing;
 /**
  * A `BasicTracerProvider` with the underlying `HeystackSpanExporter` attached so
  * flush paths can drain its in-flight fetches directly (the OTel processor's
@@ -272,10 +340,12 @@ export type HeystackTracerProvider = BasicTracerProvider & {
  * must drain the exporter — `await provider.heystackExporter.forceFlush()` (or
  * `flushHeystack()`), not just `provider.forceFlush()`.
  */
-export declare function createTracerProvider(config: HeystackOptions & {
+export declare function createTracerProvider(config: HeystackOptions & SpanPrivacyOptions & {
     sampling?: {
         rate?: number;
+        remote?: boolean;
     };
+    trustInboundSampling?: boolean;
 }): HeystackTracerProvider;
 /**
  * An AsyncLocalStorage-backed ContextManager for the /workers entry. When the
@@ -483,6 +553,22 @@ export declare function wrapDurableObjectClass<C extends {
 export declare function wrapWorkflowEntrypointClass<C extends {
     readonly prototype: object;
 }>(cls: C, opts?: InstrumentClassesOpts): C;
+/**
+ * Decorate a `WorkerEntrypoint` class (the target of a Service binding):
+ * - `fetch()` is traced exactly like an `instrument()`ed handler (SERVER span,
+ *   inbound `traceparent` continued, export drained via `ctx.waitUntil`).
+ * - every public RPC method gets a SERVER span `rpc <method>` with
+ *   `jsrpc.method` / `rpc.method`. Return values (including stubs, RpcTargets
+ *   and custom thenables), `this` and errors pass through untouched.
+ *
+ * RPC spans exist in DIRECT mode only. When Cloudflare native tracing is active
+ * it already emits `jsrpc` spans, so RPC calls pass straight through and `fetch`
+ * takes `instrument()`'s native path. Constructor, `#private`, `_underscore` and
+ * Symbol-keyed members are never wrapped.
+ *
+ *   export default wrapWorkerEntrypointClass(class Api extends WorkerEntrypoint { ... }, { service: "api" });
+ */
+export declare function wrapWorkerEntrypointClass<T extends new (...a: any[]) => object>(cls: T, cfg: WorkersConfig): T;
 /**
  * Run `fn` inside a new child span named `name`. The span is automatically
  * parented to the currently-active span (via `context.active()`), started
@@ -502,8 +588,8 @@ export declare function withSpan<T>(name: string, attrs: Record<string, string |
  * without `nodejs_compat`: the explicit context cannot be lost across async
  * boundaries. It falls back to the regular OTel tracer outside Cloudflare.
  */
-export declare function withCloudflareSpan<T>(ctx: ExecutionContext | CloudflareNativeTracing, name: string, fn: (span: Span) => T | Promise<T>): Promise<T>;
-export declare function withCloudflareSpan<T>(ctx: ExecutionContext | CloudflareNativeTracing, name: string, attrs: Record<string, string | number | boolean>, fn: (span: Span) => T | Promise<T>): Promise<T>;
+export declare function withCloudflareSpan<T>(ctx: ExecutionContext | CloudflareTracing, name: string, fn: (span: Span) => T | Promise<T>): Promise<T>;
+export declare function withCloudflareSpan<T>(ctx: ExecutionContext | CloudflareTracing, 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.
@@ -523,3 +609,6 @@ export { llmRequestAttrs as genAiRequestAttrs } from "./llm-enrich.js";
  */
 export { llmResponseAttrs as genAiResponseAttrs } from "./llm-enrich.js";
 export type { LLMGatewayConfig, LLMProvider } from "./llm-enrich.js";
+export { NATIVELY_COVERED, NATIVE_PROPAGATES_EXTERNAL, shouldEnrichNatively, wrapSqlClient };
+export { matchRoute } from "./workers-routes.js";
+export type { BindingKind };