autotel 4.2.5 → 5.0.0

package/dist/metric.d.ts

@@ -1,7 +1,6 @@
-import { s as Logger } from "./logger-BauSUhUv.js";
-import { c as OutcomeStatus, n as EventAttributes, s as FunnelStatus } from "./event-subscriber-D1XLkPzi.js";
-import { t as MetricsCollector } from "./metric-testing-DXdK3-Q3.js";
-
+import { s as Logger } from "./logger-CN4xpzMd.js";
+import { c as OutcomeStatus, n as EventAttributes, s as FunnelStatus } from "./event-subscriber-CWh8sTGh.js";
+import { t as MetricsCollector } from "./metric-testing-CWm6UhaR.js";
 //#region src/metric.d.ts
 /**
  * Metrics class for tracking business metrics in OpenTelemetry

package/dist/metric.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metric.d.ts","names":[],"sources":["../src/metric.ts"],"mappings":";;;;;;;;;;;;;AAgGwB;AAIxB;;;;;UApCiB,YAAA;EA8MA;EA5Mf,IAAA;EAoQe;EAlQf,WAAA;EA6T8B;EA3T9B,IAAA;AAAA;;;;UAMe,cAAA;EA8BP;EA5BR,MAAA,GAAS,MAAA;;EAET,SAAA,GAAY,gBAAA;EAiE8B;;;;EA3D1C,SAAA;EAyI8B;;;;EAnI9B,OAAA;IACE,MAAA,GAAS,YAAA;IACT,MAAA,GAAS,YAAA;IACT,QAAA,GAAW,YAAA;IACX,KAAA,GAAQ,YAAA;EAAA;AAAA;AAAA,cAIC,MAAA;EAAA,QACH,WAAA;EAAA,QACA,YAAA;EAAA,QACA,aAAA;EAAA,QACA,cAAA;EAAA,QACA,cAAA;EAAA,QACA,MAAA;EAAA,QACA,SAAA;EAsRsB;AAgDhC;;;;;;;;;AAAwE;AAUxE;;;;AAA4B;;;;;;;;;;;;;;;;;;;;;cA1Sd,WAAA,UAAqB,OAAA,GAAS,cAAA;;;;;;;;;;;;;;;;;;;;;;;;EA8E1C,UAAA,CAAW,SAAA,UAAmB,UAAA,GAAa,eAAA;;;;;;;;;;;;;;;;;;;EA4C3C,eAAA,CACE,UAAA,UACA,MAAA,EAAQ,YAAA,EACR,UAAA,GAAa,eAAA;;;;;;;;;;;;;;;;;;;;;;;;EAqDf,YAAA,CACE,aAAA,UACA,MAAA,EAAQ,aAAA,EACR,UAAA,GAAa,eAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;EAwDf,UAAA,CACE,UAAA,UACA,KAAA,UACA,UAAA,GAAa,eAAA;AAAA;;;;;;;;;;;;;;iBAgDD,UAAA,CAAW,WAAA,UAAqB,MAAA,GAAS,MAAA,GAAS,MAAM;;;;iBAUxD,YAAA"}
+{"version":3,"file":"metric.d.ts","names":[],"sources":["../src/metric.ts"],"mappings":";;;;;;;;;;;;;;;;;;UAgEiB;;EAEf;;EAEA;;EAEA;;;;;UAMe;;EAEf,SAAS;;EAET,YAAY;;;;;EAMZ;;;;;EAMA;IACE,SAAS;IACT,SAAS;IACT,WAAW;IACX,QAAQ;;;cAIC;UACH;UACA;UACA;UACA;UACA;UACA;UACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAsCI,YAAA,qBAAqB,UAAS;;;;;;;;;;;;;;;;;;;;;;;;EA8E1C,WAAW,mBAAmB,aAAa;;;;;;;;;;;;;;;;;;;EA4C3C,gBACE,oBACA,QAAQ,cACR,aAAa;;;;;;;;;;;;;;;;;;;;;;;;EAqDf,aACE,uBACA,QAAQ,eACR,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;EAwDf,WACE,oBACA,eACA,aAAa;;;;;;;;;;;;;;;iBAgDD,WAAW,qBAAqB,SAAS,SAAS;;;;iBAUlD"}

package/dist/parse-error.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"parse-error.d.cts","names":[],"sources":["../src/parse-error.ts"],"mappings":";UAEiB,WAAA;EACf,OAAA;EACA,MAAA;EACA,GAAA;EACA,GAAA;EACA,IAAA;EACA,IAAA;EACA,OAAA,GAAU,MAAM;EAChB,GAAA;AAAA;AAAA,iBAwCc,UAAA,CAAW,KAAA,YAAiB,WAAW"}
+{"version":3,"file":"parse-error.d.cts","names":[],"sources":["../src/parse-error.ts"],"mappings":";UAEiB;EACf;EACA;EACA;EACA;EACA;EACA;EACA,UAAU;EACV;;iBAwCc,WAAW,iBAAiB"}

package/dist/parse-error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parse-error.d.ts","names":[],"sources":["../src/parse-error.ts"],"mappings":";UAEiB,WAAA;EACf,OAAA;EACA,MAAA;EACA,GAAA;EACA,GAAA;EACA,IAAA;EACA,IAAA;EACA,OAAA,GAAU,MAAM;EAChB,GAAA;AAAA;AAAA,iBAwCc,UAAA,CAAW,KAAA,YAAiB,WAAW"}
+{"version":3,"file":"parse-error.d.ts","names":[],"sources":["../src/parse-error.ts"],"mappings":";UAEiB;EACf;EACA;EACA;EACA;EACA;EACA;EACA,UAAU;EACV;;iBAwCc,WAAW,iBAAiB"}

package/dist/processors.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_canonical_log_line_processor = require('./canonical-log-line-processor-CcrDi6TO.cjs');
+const require_canonical_log_line_processor = require('./canonical-log-line-processor-DOjb6Kxy.cjs');
 let _opentelemetry_sdk_trace_base = require("@opentelemetry/sdk-trace-base");
 
 Object.defineProperty(exports, 'BatchSpanProcessor', {

package/dist/processors.d.cts

@@ -1,3 +1,3 @@
-import { n as CanonicalLogLineProcessor, t as CanonicalLogLineOptions } from "./canonical-log-line-processor-xvjMgtpF.cjs";
+import { n as CanonicalLogLineProcessor, t as CanonicalLogLineOptions } from "./canonical-log-line-processor-B4WgG-VS.cjs";
 import { BatchSpanProcessor, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
 export { BatchSpanProcessor, type CanonicalLogLineOptions, CanonicalLogLineProcessor, SimpleSpanProcessor };

package/dist/processors.d.ts

@@ -1,3 +1,3 @@
-import { n as CanonicalLogLineProcessor, t as CanonicalLogLineOptions } from "./canonical-log-line-processor-BcRuAdRk.js";
+import { n as CanonicalLogLineProcessor, t as CanonicalLogLineOptions } from "./canonical-log-line-processor-CL_J7gb5.js";
 import { BatchSpanProcessor, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
 export { BatchSpanProcessor, type CanonicalLogLineOptions, CanonicalLogLineProcessor, SimpleSpanProcessor };

package/dist/processors.js

@@ -1,4 +1,4 @@
-import { t as CanonicalLogLineProcessor } from "./canonical-log-line-processor-FLezvFCB.js";
+import { t as CanonicalLogLineProcessor } from "./canonical-log-line-processor-mKABvGP0.js";
 import { BatchSpanProcessor, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
 
 export { BatchSpanProcessor, CanonicalLogLineProcessor, SimpleSpanProcessor };

package/dist/register.d.cts

@@ -1 +1 @@
-export { };
+export {}

package/dist/register.d.ts

@@ -1 +1 @@
-export { };
+export {}

package/dist/{sampling-DfYhDJij.d.cts → sampling-BR9fkSwx.d.cts}

@@ -1,12 +1,34 @@
-import { s as Logger } from "./logger-BauSUhUv.cjs";
+import { s as Logger } from "./logger-CN4xpzMd.cjs";
 import { Attributes, Link } from "@opentelemetry/api";
-
 //#region src/sampling.d.ts
 /**
  * Tail sampling attribute keys (autotel-internal, not OTel semconv)
  */
 declare const AUTOTEL_SAMPLING_TAIL_KEEP = "autotel.sampling.tail.keep";
 declare const AUTOTEL_SAMPLING_TAIL_EVALUATED = "autotel.sampling.tail.evaluated";
+/**
+ * How many events each kept event stands for, expressed as "1 in N".
+ *
+ * A query that counts sampled spans undercounts the population. Multiplying
+ * each kept event by this rate restores the estimate. Autotel records the
+ * attribute only when N exceeds 1, so fully captured spans stay clean.
+ */
+declare const AUTOTEL_SAMPLING_RATE = "autotel.sampling.rate";
+/**
+ * Map a string to a stable, evenly spread position in the unit interval.
+ *
+ * Two processes that hash the same key reach the same number, which is what
+ * lets independent services agree on one trace's sampling decision.
+ *
+ * The spread matters as much as the stability. Real sampling keys share long
+ * prefixes: `user_1000`, `user_1001`, `checkout-trace-0001`. A plain
+ * multiply-and-add hash lets that shared prefix dominate the high bits, so a
+ * whole key family lands in one narrow band and a rate of 0.1 keeps all of
+ * them or none of them. FNV-1a followed by the murmur3 finalizer mixes the
+ * low bits back through the word, so keys that differ in one character land
+ * far apart.
+ */
+declare function hashUnitInterval(value: string): number;
 /**
  * Sampler interface - return true to trace, false to skip
  */
@@ -34,6 +56,16 @@ interface Sampler {
    * @returns true if this trace should be kept, false to drop it
    */
   shouldKeepTrace?(context: SamplingContext, result: OperationResult): boolean;
+  /**
+   * How many events a kept event represents, as "1 in N".
+   *
+   * Autotel writes the result to {@link AUTOTEL_SAMPLING_RATE} so an analyst
+   * can reweight counts. Return 1 when the sampler keeps everything.
+   *
+   * @param context - Sampling context
+   * @returns Events represented per kept event
+   */
+  sampleRate?(context: SamplingContext): number;
 }
 /**
  * Context information for sampling decisions
@@ -68,9 +100,10 @@ interface OperationResult {
  * ```
  */
 declare class RandomSampler implements Sampler {
-  private readonly sampleRate;
-  constructor(sampleRate: number);
+  private readonly rate;
+  constructor(rate: number);
   shouldSample(_context: SamplingContext): boolean;
+  sampleRate(): number;
 }
 /**
  * Always sample (100% tracing)
@@ -131,8 +164,10 @@ declare class AdaptiveSampler implements Sampler {
     baselineSampleRate?: number;
     slowThresholdMs?: number;
     alwaysSampleErrors?: boolean;
-    alwaysSampleSlow?: boolean; /** Enable links-based sampling for event-driven architectures */
-    linksBased?: boolean; /** Sampling rate for spans linked to sampled spans (0.0-1.0) */
+    alwaysSampleSlow?: boolean;
+    /** Enable links-based sampling for event-driven architectures */
+    linksBased?: boolean;
+    /** Sampling rate for spans linked to sampled spans (0.0-1.0) */
     linksRate?: number;
     logger?: Logger;
   });
@@ -200,6 +235,85 @@ declare class UserIdSampler implements Sampler {
    */
   private hashString;
 }
+/**
+ * Consistent sampler: every service reaches the same verdict for one trace.
+ *
+ * `RandomSampler` rolls the dice per process, so an upstream service can keep
+ * a trace that its downstream drops, leaving a waterfall with holes in it.
+ * Hashing a key that travels with the request removes the disagreement. Pass
+ * the trace id, or any identifier every hop already shares.
+ *
+ * @example
+ * ```typescript
+ * new DeterministicSampler({
+ *   sampleRate: 0.1,
+ *   key: (context) => trace.getActiveSpan()?.spanContext().traceId,
+ * })
+ * ```
+ */
+declare class DeterministicSampler implements Sampler {
+  private readonly rate;
+  private readonly key;
+  constructor(options: {
+    /** Fraction of traces to keep, 0-1. */
+    sampleRate: number;
+    /** Identifier shared by every hop of the trace. */
+    key: (context: SamplingContext) => string | undefined;
+  });
+  shouldSample(context: SamplingContext): boolean;
+  sampleRate(): number;
+}
+/**
+ * Per-key target-rate sampler for workloads with uneven traffic.
+ *
+ * A single rate serves a skewed workload badly: 1% floods storage with the
+ * busiest endpoint and still loses the rare tenant whose failures you need.
+ * This sampler counts traffic per key over a rolling window, then sets each
+ * key its own rate so every key contributes roughly `targetPerKey` events.
+ * Quiet keys survive intact; loud keys get thinned.
+ *
+ * The first window keeps everything, because no traffic history exists yet.
+ * Rates take effect from the second window onward.
+ *
+ * @example
+ * ```typescript
+ * new KeyTargetRateSampler({
+ *   key: (context) => context.operationName,
+ *   targetPerKey: 10,     // ~10 events per key per window
+ *   windowMs: 30_000,
+ * })
+ * ```
+ */
+declare class KeyTargetRateSampler implements Sampler {
+  private readonly key;
+  private readonly targetPerKey;
+  private readonly windowMs;
+  private readonly maxKeys;
+  private counts;
+  private rates;
+  private windowStart;
+  constructor(options: {
+    /** Groups traffic. Use the operation, route, tenant, or status. */
+    key: (context: SamplingContext) => string | undefined;
+    /** Events to keep per key per window. Default 10. */
+    targetPerKey?: number;
+    /** Length of the counting window in milliseconds. Default 30000. */
+    windowMs?: number;
+    /** Distinct keys to track before overflowing into one bucket. Default 1000. */
+    maxKeys?: number;
+  });
+  /** Turn the window's observed counts into the next window's rates. */
+  private roll;
+  /**
+   * Resolve the key, collapsing into one bucket once the map is full.
+   *
+   * An unbounded key function would otherwise grow the map without limit,
+   * which turns a sampler meant to cut cost into a memory leak.
+   */
+  private resolveKey;
+  shouldSample(context: SamplingContext): boolean;
+  sampleRate(context: SamplingContext): number;
+}
 /**
  * Composite sampler that combines multiple samplers
  *
@@ -273,7 +387,9 @@ type SamplingPreset = 'development' | 'errors-only' | 'production' | 'off';
  * ```
  */
 declare const samplingPresets: {
-  /** Capture everything — best for local development and debugging */development: () => AlwaysSampler; /** Only bad outcomes — zero baseline, errors always kept */
+  /** Capture everything — best for local development and debugging */
+  development: () => AlwaysSampler;
+  /** Only bad outcomes — zero baseline, errors always kept */
   errorsOnly: () => AdaptiveSampler;
   /**
    * Balanced production defaults — 10% baseline + errors + slow traces.
@@ -284,7 +400,8 @@ declare const samplingPresets: {
     slowThresholdMs?: number;
     alwaysSampleErrors?: boolean;
     alwaysSampleSlow?: boolean;
-  }) => AdaptiveSampler; /** Disable sampling entirely */
+  }) => AdaptiveSampler;
+  /** Disable sampling entirely */
   off: () => NeverSampler;
 };
 /**
@@ -347,5 +464,5 @@ declare function extractLinksFromBatch(messages: Array<{
   [key: string]: unknown;
 }>, headersKey?: string): Link[];
 //#endregion
-export { samplingPresets as _, CompositeSampler as a, OperationResult as c, SamplingContext as d, SamplingPreset as f, resolveSamplingPreset as g, extractLinksFromBatch as h, AlwaysSampler as i, RandomSampler as l, createLinkFromHeaders as m, AUTOTEL_SAMPLING_TAIL_KEEP as n, FeatureFlagSampler as o, UserIdSampler as p, AdaptiveSampler as r, NeverSampler as s, AUTOTEL_SAMPLING_TAIL_EVALUATED as t, Sampler as u };
-//# sourceMappingURL=sampling-DfYhDJij.d.cts.map
+export { createLinkFromHeaders as _, AlwaysSampler as a, resolveSamplingPreset as b, FeatureFlagSampler as c, OperationResult as d, RandomSampler as f, UserIdSampler as g, SamplingPreset as h, AdaptiveSampler as i, KeyTargetRateSampler as l, SamplingContext as m, AUTOTEL_SAMPLING_TAIL_EVALUATED as n, CompositeSampler as o, Sampler as p, AUTOTEL_SAMPLING_TAIL_KEEP as r, DeterministicSampler as s, AUTOTEL_SAMPLING_RATE as t, NeverSampler as u, extractLinksFromBatch as v, samplingPresets as x, hashUnitInterval as y };
+//# sourceMappingURL=sampling-BR9fkSwx.d.cts.map

package/dist/sampling-BR9fkSwx.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampling-BR9fkSwx.d.cts","names":[],"sources":["../src/sampling.ts"],"mappings":";;;;;;cA+Ba;cACA;;;;;;;;cAUA;;;;;;;;;;;;;;;iBA0BG,iBAAiB;;;;UAoBhB;;;;;;;EAOf,aAAa,SAAS;;;;;;;EAQtB;;;;;;;;;EAUA,iBAAiB,SAAS,iBAAiB,QAAQ;;;;;;;;;;EAWnD,YAAY,SAAS;;;;;UAMN;;EAEf;;EAEA;;EAEA,WAAW;;EAEX,QAAQ;;;;;UAMO;;EAEf;;EAEA;;EAEA,QAAQ;;;;;;;;;;cAWG,yBAAyB;mBACP;EAAA,YAAA;EAM7B,aAAa,UAAU;EAIvB;;;;;cAQW,yBAAyB;EACpC,aAAa,UAAU;;;;;cAQZ,wBAAwB;EACnC,aAAa,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAsCZ,2BAA2B;UAC9B;UACA;UACA;UACA;UACA;UACA;UACA;mBAGS;mBAEA;EAGf,YAAA;IACE;IACA;IACA;IACA;;IAEA;;IAEA;IACA,SAAS;;EAmBb;EAKA,aAAa,SAAS;;;;;;;;;;EAoBtB,eAAe,OAAO;;;;;;;;;;;EAoBtB,gBAAgB,SAAS,iBAAiB,QAAQ;;;;;;;;;;;;;;;;;cAuEvC,yBAAyB;UAC5B;UACA;UACA;UACA;EAEI,YAAA;IACV;IACA;IACA,gBAAgB;IAChB,SAAS;;EAQX,aAAa,SAAS;;;;EA4BtB,wBAAwB;;;;EASxB,2BAA2B;;;;UASnB;;;;;;;;;;;;;;;;;;cAqBG,gCAAgC;mBAC1B;mBACA;EAEL,YAAA;;IAEV;;IAEA,MAAM,SAAS;;EASjB,aAAa,SAAS;EAStB;;;;;;;;;;;;;;;;;;;;;;;cA6BW,gCAAgC;mBAC1B;mBACA;mBACA;mBACA;UACT;UACA;UACA;EAEI,YAAA;;IAEV,MAAM,SAAS;;IAEf;;IAEA;;IAEA;;;UAgBM;;;;;;;UAmBA;EAQR,aAAa,SAAS;EAQtB,WAAW,SAAS;;;;;;;;;;;;;;;cAkBT,4BAA4B;mBACV;EAAA,YAAA,UAAU;EAMvC,aAAa,SAAS;;;;;;;;;;;;;;;;;cAoBX,8BAA8B;UACjC;UACA;UACA;UAIA;EAEI,YAAA;IACV;IACA;IACA,eACE,iBACA,WAAW;IAEb,SAAS;;EAQX,aAAa,SAAS;;;;EAsBtB,wBAAwB;;;;EASxB,2BAA2B;;;;;;KAejB;;;;;;;;;;;;;;cAgBC;;;;;;;;;EAec,aAAA;IACvB;IACA;IACA;IACA;QACD;;;;;;;;;;iBAmBa,sBAAsB,QAAQ,iBAAiB;;;;;;;;;;;;;;;;;;;;;;iBA+C/C,sBACd,SAAS,wBACT,aAAa,aACZ;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA8Ca,sBACd,UAAU;GAAS;IACnB,sBACC"}

package/dist/{sampling-CR0Va1VB.d.ts → sampling-CP3e7-Yr.d.ts}

@@ -1,12 +1,34 @@
-import { s as Logger } from "./logger-BauSUhUv.js";
+import { s as Logger } from "./logger-CN4xpzMd.js";
 import { Attributes, Link } from "@opentelemetry/api";
-
 //#region src/sampling.d.ts
 /**
  * Tail sampling attribute keys (autotel-internal, not OTel semconv)
  */
 declare const AUTOTEL_SAMPLING_TAIL_KEEP = "autotel.sampling.tail.keep";
 declare const AUTOTEL_SAMPLING_TAIL_EVALUATED = "autotel.sampling.tail.evaluated";
+/**
+ * How many events each kept event stands for, expressed as "1 in N".
+ *
+ * A query that counts sampled spans undercounts the population. Multiplying
+ * each kept event by this rate restores the estimate. Autotel records the
+ * attribute only when N exceeds 1, so fully captured spans stay clean.
+ */
+declare const AUTOTEL_SAMPLING_RATE = "autotel.sampling.rate";
+/**
+ * Map a string to a stable, evenly spread position in the unit interval.
+ *
+ * Two processes that hash the same key reach the same number, which is what
+ * lets independent services agree on one trace's sampling decision.
+ *
+ * The spread matters as much as the stability. Real sampling keys share long
+ * prefixes: `user_1000`, `user_1001`, `checkout-trace-0001`. A plain
+ * multiply-and-add hash lets that shared prefix dominate the high bits, so a
+ * whole key family lands in one narrow band and a rate of 0.1 keeps all of
+ * them or none of them. FNV-1a followed by the murmur3 finalizer mixes the
+ * low bits back through the word, so keys that differ in one character land
+ * far apart.
+ */
+declare function hashUnitInterval(value: string): number;
 /**
  * Sampler interface - return true to trace, false to skip
  */
@@ -34,6 +56,16 @@ interface Sampler {
    * @returns true if this trace should be kept, false to drop it
    */
   shouldKeepTrace?(context: SamplingContext, result: OperationResult): boolean;
+  /**
+   * How many events a kept event represents, as "1 in N".
+   *
+   * Autotel writes the result to {@link AUTOTEL_SAMPLING_RATE} so an analyst
+   * can reweight counts. Return 1 when the sampler keeps everything.
+   *
+   * @param context - Sampling context
+   * @returns Events represented per kept event
+   */
+  sampleRate?(context: SamplingContext): number;
 }
 /**
  * Context information for sampling decisions
@@ -68,9 +100,10 @@ interface OperationResult {
  * ```
  */
 declare class RandomSampler implements Sampler {
-  private readonly sampleRate;
-  constructor(sampleRate: number);
+  private readonly rate;
+  constructor(rate: number);
   shouldSample(_context: SamplingContext): boolean;
+  sampleRate(): number;
 }
 /**
  * Always sample (100% tracing)
@@ -131,8 +164,10 @@ declare class AdaptiveSampler implements Sampler {
     baselineSampleRate?: number;
     slowThresholdMs?: number;
     alwaysSampleErrors?: boolean;
-    alwaysSampleSlow?: boolean; /** Enable links-based sampling for event-driven architectures */
-    linksBased?: boolean; /** Sampling rate for spans linked to sampled spans (0.0-1.0) */
+    alwaysSampleSlow?: boolean;
+    /** Enable links-based sampling for event-driven architectures */
+    linksBased?: boolean;
+    /** Sampling rate for spans linked to sampled spans (0.0-1.0) */
     linksRate?: number;
     logger?: Logger;
   });
@@ -200,6 +235,85 @@ declare class UserIdSampler implements Sampler {
    */
   private hashString;
 }
+/**
+ * Consistent sampler: every service reaches the same verdict for one trace.
+ *
+ * `RandomSampler` rolls the dice per process, so an upstream service can keep
+ * a trace that its downstream drops, leaving a waterfall with holes in it.
+ * Hashing a key that travels with the request removes the disagreement. Pass
+ * the trace id, or any identifier every hop already shares.
+ *
+ * @example
+ * ```typescript
+ * new DeterministicSampler({
+ *   sampleRate: 0.1,
+ *   key: (context) => trace.getActiveSpan()?.spanContext().traceId,
+ * })
+ * ```
+ */
+declare class DeterministicSampler implements Sampler {
+  private readonly rate;
+  private readonly key;
+  constructor(options: {
+    /** Fraction of traces to keep, 0-1. */
+    sampleRate: number;
+    /** Identifier shared by every hop of the trace. */
+    key: (context: SamplingContext) => string | undefined;
+  });
+  shouldSample(context: SamplingContext): boolean;
+  sampleRate(): number;
+}
+/**
+ * Per-key target-rate sampler for workloads with uneven traffic.
+ *
+ * A single rate serves a skewed workload badly: 1% floods storage with the
+ * busiest endpoint and still loses the rare tenant whose failures you need.
+ * This sampler counts traffic per key over a rolling window, then sets each
+ * key its own rate so every key contributes roughly `targetPerKey` events.
+ * Quiet keys survive intact; loud keys get thinned.
+ *
+ * The first window keeps everything, because no traffic history exists yet.
+ * Rates take effect from the second window onward.
+ *
+ * @example
+ * ```typescript
+ * new KeyTargetRateSampler({
+ *   key: (context) => context.operationName,
+ *   targetPerKey: 10,     // ~10 events per key per window
+ *   windowMs: 30_000,
+ * })
+ * ```
+ */
+declare class KeyTargetRateSampler implements Sampler {
+  private readonly key;
+  private readonly targetPerKey;
+  private readonly windowMs;
+  private readonly maxKeys;
+  private counts;
+  private rates;
+  private windowStart;
+  constructor(options: {
+    /** Groups traffic. Use the operation, route, tenant, or status. */
+    key: (context: SamplingContext) => string | undefined;
+    /** Events to keep per key per window. Default 10. */
+    targetPerKey?: number;
+    /** Length of the counting window in milliseconds. Default 30000. */
+    windowMs?: number;
+    /** Distinct keys to track before overflowing into one bucket. Default 1000. */
+    maxKeys?: number;
+  });
+  /** Turn the window's observed counts into the next window's rates. */
+  private roll;
+  /**
+   * Resolve the key, collapsing into one bucket once the map is full.
+   *
+   * An unbounded key function would otherwise grow the map without limit,
+   * which turns a sampler meant to cut cost into a memory leak.
+   */
+  private resolveKey;
+  shouldSample(context: SamplingContext): boolean;
+  sampleRate(context: SamplingContext): number;
+}
 /**
  * Composite sampler that combines multiple samplers
  *
@@ -273,7 +387,9 @@ type SamplingPreset = 'development' | 'errors-only' | 'production' | 'off';
  * ```
  */
 declare const samplingPresets: {
-  /** Capture everything — best for local development and debugging */development: () => AlwaysSampler; /** Only bad outcomes — zero baseline, errors always kept */
+  /** Capture everything — best for local development and debugging */
+  development: () => AlwaysSampler;
+  /** Only bad outcomes — zero baseline, errors always kept */
   errorsOnly: () => AdaptiveSampler;
   /**
    * Balanced production defaults — 10% baseline + errors + slow traces.
@@ -284,7 +400,8 @@ declare const samplingPresets: {
     slowThresholdMs?: number;
     alwaysSampleErrors?: boolean;
     alwaysSampleSlow?: boolean;
-  }) => AdaptiveSampler; /** Disable sampling entirely */
+  }) => AdaptiveSampler;
+  /** Disable sampling entirely */
   off: () => NeverSampler;
 };
 /**
@@ -347,5 +464,5 @@ declare function extractLinksFromBatch(messages: Array<{
   [key: string]: unknown;
 }>, headersKey?: string): Link[];
 //#endregion
-export { samplingPresets as _, CompositeSampler as a, OperationResult as c, SamplingContext as d, SamplingPreset as f, resolveSamplingPreset as g, extractLinksFromBatch as h, AlwaysSampler as i, RandomSampler as l, createLinkFromHeaders as m, AUTOTEL_SAMPLING_TAIL_KEEP as n, FeatureFlagSampler as o, UserIdSampler as p, AdaptiveSampler as r, NeverSampler as s, AUTOTEL_SAMPLING_TAIL_EVALUATED as t, Sampler as u };
-//# sourceMappingURL=sampling-CR0Va1VB.d.ts.map
+export { createLinkFromHeaders as _, AlwaysSampler as a, resolveSamplingPreset as b, FeatureFlagSampler as c, OperationResult as d, RandomSampler as f, UserIdSampler as g, SamplingPreset as h, AdaptiveSampler as i, KeyTargetRateSampler as l, SamplingContext as m, AUTOTEL_SAMPLING_TAIL_EVALUATED as n, CompositeSampler as o, Sampler as p, AUTOTEL_SAMPLING_TAIL_KEEP as r, DeterministicSampler as s, AUTOTEL_SAMPLING_RATE as t, NeverSampler as u, extractLinksFromBatch as v, samplingPresets as x, hashUnitInterval as y };
+//# sourceMappingURL=sampling-CP3e7-Yr.d.ts.map

package/dist/sampling-CP3e7-Yr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampling-CP3e7-Yr.d.ts","names":[],"sources":["../src/sampling.ts"],"mappings":";;;;;;cA+Ba;cACA;;;;;;;;cAUA;;;;;;;;;;;;;;;iBA0BG,iBAAiB;;;;UAoBhB;;;;;;;EAOf,aAAa,SAAS;;;;;;;EAQtB;;;;;;;;;EAUA,iBAAiB,SAAS,iBAAiB,QAAQ;;;;;;;;;;EAWnD,YAAY,SAAS;;;;;UAMN;;EAEf;;EAEA;;EAEA,WAAW;;EAEX,QAAQ;;;;;UAMO;;EAEf;;EAEA;;EAEA,QAAQ;;;;;;;;;;cAWG,yBAAyB;mBACP;EAAA,YAAA;EAM7B,aAAa,UAAU;EAIvB;;;;;cAQW,yBAAyB;EACpC,aAAa,UAAU;;;;;cAQZ,wBAAwB;EACnC,aAAa,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAsCZ,2BAA2B;UAC9B;UACA;UACA;UACA;UACA;UACA;UACA;mBAGS;mBAEA;EAGf,YAAA;IACE;IACA;IACA;IACA;;IAEA;;IAEA;IACA,SAAS;;EAmBb;EAKA,aAAa,SAAS;;;;;;;;;;EAoBtB,eAAe,OAAO;;;;;;;;;;;EAoBtB,gBAAgB,SAAS,iBAAiB,QAAQ;;;;;;;;;;;;;;;;;cAuEvC,yBAAyB;UAC5B;UACA;UACA;UACA;EAEI,YAAA;IACV;IACA;IACA,gBAAgB;IAChB,SAAS;;EAQX,aAAa,SAAS;;;;EA4BtB,wBAAwB;;;;EASxB,2BAA2B;;;;UASnB;;;;;;;;;;;;;;;;;;cAqBG,gCAAgC;mBAC1B;mBACA;EAEL,YAAA;;IAEV;;IAEA,MAAM,SAAS;;EASjB,aAAa,SAAS;EAStB;;;;;;;;;;;;;;;;;;;;;;;cA6BW,gCAAgC;mBAC1B;mBACA;mBACA;mBACA;UACT;UACA;UACA;EAEI,YAAA;;IAEV,MAAM,SAAS;;IAEf;;IAEA;;IAEA;;;UAgBM;;;;;;;UAmBA;EAQR,aAAa,SAAS;EAQtB,WAAW,SAAS;;;;;;;;;;;;;;;cAkBT,4BAA4B;mBACV;EAAA,YAAA,UAAU;EAMvC,aAAa,SAAS;;;;;;;;;;;;;;;;;cAoBX,8BAA8B;UACjC;UACA;UACA;UAIA;EAEI,YAAA;IACV;IACA;IACA,eACE,iBACA,WAAW;IAEb,SAAS;;EAQX,aAAa,SAAS;;;;EAsBtB,wBAAwB;;;;EASxB,2BAA2B;;;;;;KAejB;;;;;;;;;;;;;;cAgBC;;;;;;;;;EAec,aAAA;IACvB;IACA;IACA;IACA;QACD;;;;;;;;;;iBAmBa,sBAAsB,QAAQ,iBAAiB;;;;;;;;;;;;;;;;;;;;;;iBA+C/C,sBACd,SAAS,wBACT,aAAa,aACZ;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA8Ca,sBACd,UAAU;GAAS;IACnB,sBACC"}