autotel 3.5.0 → 3.7.0

package/dist/sampling-CR0Va1VB.d.ts

@@ -0,0 +1,351 @@
+import { s as Logger } from "./logger-BauSUhUv.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";
+/**
+ * Sampler interface - return true to trace, false to skip
+ */
+interface Sampler {
+  /**
+   * Decide whether to trace this operation
+   *
+   * @param context - Sampling context
+   * @returns true to trace, false to skip
+   */
+  shouldSample(context: SamplingContext): boolean;
+  /**
+   * Whether this sampler needs tail sampling (post-execution decision)
+   * If true, spans are always created and shouldKeepTrace() is called after execution
+   *
+   * @returns true if this sampler needs to evaluate after operation completes
+   */
+  needsTailSampling?(): boolean;
+  /**
+   * Re-evaluate sampling decision after operation completes (tail sampling)
+   * Only called if needsTailSampling() returns true
+   *
+   * @param context - Sampling context
+   * @param result - Operation result
+   * @returns true if this trace should be kept, false to drop it
+   */
+  shouldKeepTrace?(context: SamplingContext, result: OperationResult): boolean;
+}
+/**
+ * Context information for sampling decisions
+ */
+interface SamplingContext {
+  /** Operation name */
+  operationName: string;
+  /** Method arguments (for extracting user IDs, etc.) */
+  args: unknown[];
+  /** Optional metadata (e.g., feature flags, request headers) */
+  metadata?: Record<string, unknown>;
+  /** Optional span links for links-based sampling */
+  links?: Link[];
+}
+/**
+ * Result of a trace operation (for post-execution sampling)
+ */
+interface OperationResult {
+  /** Whether the operation succeeded */
+  success: boolean;
+  /** Duration in milliseconds */
+  duration: number;
+  /** Error if operation failed */
+  error?: Error;
+}
+/**
+ * Simple random sampler
+ *
+ * @example
+ * ```typescript
+ * new RandomSampler(0.1) // Sample 10% of requests
+ * ```
+ */
+declare class RandomSampler implements Sampler {
+  private readonly sampleRate;
+  constructor(sampleRate: number);
+  shouldSample(_context: SamplingContext): boolean;
+}
+/**
+ * Always sample (100% tracing)
+ */
+declare class AlwaysSampler implements Sampler {
+  shouldSample(_context: SamplingContext): boolean;
+}
+/**
+ * Never sample (0% tracing)
+ */
+declare class NeverSampler implements Sampler {
+  shouldSample(_context: SamplingContext): boolean;
+}
+/**
+ * Adaptive sampler that always traces errors and slow requests
+ *
+ * This is the recommended sampler for production use.
+ * It ensures you never miss critical issues while keeping costs down.
+ *
+ * Strategy:
+ * - Always trace errors (critical for debugging)
+ * - Always trace slow requests (performance issues)
+ * - Use baseline sample rate for successful fast requests
+ *
+ * **IMPORTANT - Tail Sampling Requirement:**
+ * This sampler uses tail sampling (makes decisions AFTER execution).
+ * You MUST use TailSamplingSpanProcessor for it to work correctly:
+ *
+ * - If using initInstrumentation(): TailSamplingSpanProcessor is auto-configured
+ * - If using custom TracerProvider: You MUST manually register TailSamplingSpanProcessor
+ *
+ * Without TailSamplingSpanProcessor, ALL spans are exported (defeating the cost savings).
+ *
+ * @see TailSamplingSpanProcessor
+ * @see README.md "Tail Sampling with Custom Providers" section
+ *
+ * @example
+ * ```typescript
+ * new AdaptiveSampler({
+ *   baselineSampleRate: 0.1,    // 10% of normal requests
+ *   slowThresholdMs: 1000,       // Requests > 1s are "slow"
+ *   alwaysSampleErrors: true,    // Always trace errors
+ *   alwaysSampleSlow: true       // Always trace slow requests
+ * })
+ * ```
+ */
+declare class AdaptiveSampler implements Sampler {
+  private baselineSampleRate;
+  private slowThresholdMs;
+  private alwaysSampleErrors;
+  private alwaysSampleSlow;
+  private linksBased;
+  private linksRate;
+  private logger?;
+  private readonly samplingDecisions;
+  private readonly operationResults;
+  constructor(options?: {
+    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) */
+    linksRate?: number;
+    logger?: Logger;
+  });
+  needsTailSampling(): boolean;
+  shouldSample(context: SamplingContext): boolean;
+  /**
+   * Check if any links point to sampled spans.
+   *
+   * A span is considered linked to a sampled span if any of its links
+   * have trace_flags with the sampled bit set (0x01).
+   *
+   * @param links - Array of span links to check
+   * @returns true if any linked span is sampled, false otherwise
+   */
+  hasSampledLink(links: Link[]): boolean;
+  /**
+   * Re-evaluate sampling decision after operation completes
+   *
+   * This allows us to always capture errors and slow requests,
+   * even if they weren't initially sampled.
+   *
+   * @param context - Sampling context
+   * @param result - Operation result
+   * @returns true if this operation should be kept (not discarded)
+   */
+  shouldKeepTrace(context: SamplingContext, result: OperationResult): boolean;
+}
+/**
+ * User-based sampler for consistent tracing
+ *
+ * Always samples requests from specific user IDs.
+ * Useful for debugging specific user issues or monitoring VIP users.
+ *
+ * @example
+ * ```typescript
+ * new UserIdSampler({
+ *   baselineSampleRate: 0.01,      // 1% of normal users
+ *   alwaysSampleUsers: ['vip_123'], // Always trace VIP users
+ *   extractUserId: (args) => args[0]?.userId // Extract user ID from first arg
+ * })
+ * ```
+ */
+declare class UserIdSampler implements Sampler {
+  private baselineSampleRate;
+  private alwaysSampleUsers;
+  private extractUserId;
+  private logger?;
+  constructor(options: {
+    baselineSampleRate?: number;
+    alwaysSampleUsers?: string[];
+    extractUserId: (args: unknown[]) => string | undefined;
+    logger?: Logger;
+  });
+  shouldSample(context: SamplingContext): boolean;
+  /**
+   * Add user IDs to always-sample list
+   */
+  addAlwaysSampleUsers(...userIds: string[]): void;
+  /**
+   * Remove user IDs from always-sample list
+   */
+  removeAlwaysSampleUsers(...userIds: string[]): void;
+  /**
+   * Simple hash function for consistent user sampling
+   */
+  private hashString;
+}
+/**
+ * Composite sampler that combines multiple samplers
+ *
+ * Samples if ANY of the child samplers returns true.
+ *
+ * @example
+ * ```typescript
+ * new CompositeSampler([
+ *   new UserIdSampler({ extractUserId: (args) => args[0]?.userId }),
+ *   new AdaptiveSampler({ baselineSampleRate: 0.1 })
+ * ])
+ * ```
+ */
+declare class CompositeSampler implements Sampler {
+  private readonly samplers;
+  constructor(samplers: Sampler[]);
+  shouldSample(context: SamplingContext): boolean;
+}
+/**
+ * Feature flag sampler
+ *
+ * Always samples requests with specific feature flags enabled.
+ * Perfect for correlating A/B test experiments with metrics.
+ *
+ * @example
+ * ```typescript
+ * new FeatureFlagSampler({
+ *   baselineSampleRate: 0.01,
+ *   alwaysSampleFlags: ['new_checkout', 'experimental_ui'],
+ *   extractFlags: (args, metadata) => metadata?.featureFlags
+ * })
+ * ```
+ */
+declare class FeatureFlagSampler implements Sampler {
+  private baselineSampleRate;
+  private alwaysSampleFlags;
+  private extractFlags;
+  private logger?;
+  constructor(options: {
+    baselineSampleRate?: number;
+    alwaysSampleFlags?: string[];
+    extractFlags: (args: unknown[], metadata?: Record<string, unknown>) => string[] | undefined;
+    logger?: Logger;
+  });
+  shouldSample(context: SamplingContext): boolean;
+  /**
+   * Add feature flags to always-sample list
+   */
+  addAlwaysSampleFlags(...flags: string[]): void;
+  /**
+   * Remove feature flags from always-sample list
+   */
+  removeAlwaysSampleFlags(...flags: string[]): void;
+}
+/**
+ * Named sampling presets for common environments.
+ * Use with `init({ sampling: 'production' })` or directly via factories.
+ */
+type SamplingPreset = 'development' | 'errors-only' | 'production' | 'off';
+/**
+ * Sampling preset factories.
+ *
+ * For most users, the string shorthand on `init()` is simpler:
+ * ```typescript
+ * init({ service: 'my-app', sampling: 'production' })
+ * ```
+ *
+ * Use factories when you need to customize:
+ * ```typescript
+ * init({ service: 'my-app', sampler: samplingPresets.production({ baselineSampleRate: 0.05 }) })
+ * ```
+ */
+declare const samplingPresets: {
+  /** 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.
+   * Pass overrides to tune (uses the same option names as AdaptiveSampler).
+   */
+  production: (overrides?: {
+    baselineSampleRate?: number;
+    slowThresholdMs?: number;
+    alwaysSampleErrors?: boolean;
+    alwaysSampleSlow?: boolean;
+  }) => AdaptiveSampler; /** Disable sampling entirely */
+  off: () => NeverSampler;
+};
+/**
+ * Resolve a preset string to a Sampler instance.
+ * Used internally by `init()` when `sampling` string is provided.
+ *
+ * @throws Error if preset is not recognized
+ */
+declare function resolveSamplingPreset(preset: SamplingPreset): Sampler;
+/**
+ * Create a Link from W3C trace context headers (e.g., from a message queue).
+ *
+ * This is useful for message consumers that need to link to the producer span.
+ * The headers should contain at least a `traceparent` header in W3C format.
+ *
+ * @param headers - Dictionary containing traceparent/tracestate headers
+ * @param attributes - Optional attributes for the link
+ * @returns Link object if context could be extracted, null otherwise
+ *
+ * @example
+ * ```typescript
+ * // In a Kafka consumer
+ * const headers = { traceparent: '00-abc123...-def456...-01' };
+ * const link = createLinkFromHeaders(headers);
+ * if (link) {
+ *   // Use with tracer.startActiveSpan options or ctx.addLink()
+ *   tracer.startActiveSpan('process.message', { links: [link] }, span => { ... });
+ * }
+ * ```
+ */
+declare function createLinkFromHeaders(headers: Record<string, string>, attributes?: Attributes): Link | null;
+/**
+ * Extract Links from a batch of messages for fan-in scenarios.
+ *
+ * Useful for batch processing where multiple producer spans should be linked.
+ * This enables tracing causality in event-driven architectures where a single
+ * consumer processes messages from multiple producers.
+ *
+ * @param messages - List of message objects
+ * @param headersKey - Key in each message containing trace headers (default: 'headers')
+ * @returns List of Link objects for all valid trace contexts
+ *
+ * @example
+ * ```typescript
+ * // Processing a batch of SQS/Kafka messages
+ * const messages = [
+ *   { body: '...', headers: { traceparent: '...' } },
+ *   { body: '...', headers: { traceparent: '...' } },
+ * ];
+ * const links = extractLinksFromBatch(messages);
+ *
+ * tracer.startActiveSpan('process.batch', { links }, span => {
+ *   for (const msg of messages) {
+ *     processMessage(msg);
+ *   }
+ * });
+ * ```
+ */
+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

package/dist/sampling-CR0Va1VB.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampling-CR0Va1VB.d.ts","names":[],"sources":["../src/sampling.ts"],"mappings":";;;;;;;cA+Ba,0BAAA;AAAA,cACA,+BAAA;;;AA+BuD;UAzBnD,OAAA;EA+Be;;;;;;EAxB9B,YAAA,CAAa,OAAA,EAAS,eAAA;EAgCtB;;;AAAY;AAMd;;EA9BE,iBAAA;EAoCa;;;;;;AAAA;AAWf;EArCE,eAAA,EAAiB,OAAA,EAAS,eAAA,EAAiB,MAAA,EAAQ,eAAA;AAAA;;;;UAMpC,eAAA;EAgCc;EA9B7B,aAAA;EAqCuB;EAnCvB,IAAA;EAmCsC;EAjCtC,QAAA,GAAW,MAAA;EAyCA;EAvCX,KAAA,GAAQ,IAAI;AAAA;;;;UAMG,eAAA;EAmCF;EAjCb,OAAA;EAiCsC;EA/BtC,QAAA;EAuCwB;EArCxB,KAAA,GAAQ,KAAK;AAAA;;;;;;AAuCyB;AAsCxC;;cAlEa,aAAA,YAAyB,OAAO;EAAA,iBACd,UAAA;cAAA,UAAA;EAO7B,YAAA,CAAa,QAAA,EAAU,eAAA;AAAA;;;;cAQZ,aAAA,YAAyB,OAAO;EAE3C,YAAA,CAAa,QAAA,EAAU,eAAA;AAAA;;;;cAQZ,YAAA,YAAwB,OAAO;EAE1C,YAAA,CAAa,QAAA,EAAU,eAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;AA8H0C;AAuEnE;;;;;;;cA/Ja,eAAA,YAA2B,OAAA;EAAA,QAC9B,kBAAA;EAAA,QACA,eAAA;EAAA,QACA,kBAAA;EAAA,QACA,gBAAA;EAAA,QACA,UAAA;EAAA,QACA,SAAA;EAAA,QACA,MAAA;EAAA,iBAGS,iBAAA;EAAA,iBAEA,gBAAA;cAGf,OAAA;IACE,kBAAA;IACA,eAAA;IACA,kBAAA;IACA,gBAAA,YA8JkB;IA5JlB,UAAA,YAwLJ;IAtLI,SAAA;IACA,MAAA,GAAS,MAAA;EAAA;EAmBb,iBAAA;EAKA,YAAA,CAAa,OAAA,EAAS,eAAA;EA+KJ;AAwBpB;;;;;;;;EAnLE,cAAA,CAAe,KAAA,EAAO,IAAA;EAoLO;;;;;;;;AAMQ;AAoBvC;EA1LE,eAAA,CAAgB,OAAA,EAAS,eAAA,EAAiB,MAAA,EAAQ,eAAA;AAAA;;;;;;;;;;;;;;;;cAuEvC,aAAA,YAAyB,OAAA;EAAA,QAC5B,kBAAA;EAAA,QACA,iBAAA;EAAA,QACA,aAAA;EAAA,QACA,MAAA;cAEI,OAAA;IACV,kBAAA;IACA,iBAAA;IACA,aAAA,GAAgB,IAAA;IAChB,MAAA,GAAS,MAAA;EAAA;EAQX,YAAA,CAAa,OAAA,EAAS,eAAA;EAwJK;;AAAK;EA5HhC,oBAAA,IAAwB,OAAA;EA2IA;;;EAlIxB,uBAAA,IAA2B,OAAA;EAqJhB;;;EAAA,QA5IH,UAAA;AAAA;;;;;;;;;;;;;;cAwBG,gBAAA,YAA4B,OAAA;EAAA,iBACV,QAAA;cAAA,QAAA,EAAU,OAAA;EAMvC,YAAA,CAAa,OAAA,EAAS,eAAA;AAAA;;AAoJxB;;;;;;;;AAAsE;AA0CtE;;;;;cA1Ka,kBAAA,YAA8B,OAAA;EAAA,QACjC,kBAAA;EAAA,QACA,iBAAA;EAAA,QACA,YAAA;EAAA,QAIA,MAAA;cAEI,OAAA;IACV,kBAAA;IACA,iBAAA;IACA,YAAA,GACE,IAAA,aACA,QAAA,GAAW,MAAA;IAEb,MAAA,GAAS,MAAA;EAAA;EAQX,YAAA,CAAa,OAAA,EAAS,eAAA;;;;EAsBtB,oBAAA,IAAwB,KAAA;EA8KxB;;;EArKA,uBAAA,IAA2B,KAAA;AAAA;;;;;KAejB,cAAA;;;;;;;;;;;;;;cAmBC,eAAA;;;;;;;;IAgBT,kBAAA;IACA,eAAA;IACA,kBAAA;IACA,gBAAA;EAAA,MACD,eAAA;;;;;;;;;iBAmBa,qBAAA,CAAsB,MAAA,EAAQ,cAAA,GAAiB,OAAO;;;;;;;;;;;;;;;;;;;;;;iBA0CtD,qBAAA,CACd,OAAA,EAAS,MAAA,kBACT,UAAA,GAAa,UAAA,GACZ,IAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA8Ca,qBAAA,CACd,QAAA,EAAU,KAAA;EAAA,CAAS,GAAA;AAAA,IACnB,UAAA,YACC,IAAI"}

package/dist/sampling-DfYhDJij.d.cts

@@ -0,0 +1,351 @@
+import { s as Logger } from "./logger-BauSUhUv.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";
+/**
+ * Sampler interface - return true to trace, false to skip
+ */
+interface Sampler {
+  /**
+   * Decide whether to trace this operation
+   *
+   * @param context - Sampling context
+   * @returns true to trace, false to skip
+   */
+  shouldSample(context: SamplingContext): boolean;
+  /**
+   * Whether this sampler needs tail sampling (post-execution decision)
+   * If true, spans are always created and shouldKeepTrace() is called after execution
+   *
+   * @returns true if this sampler needs to evaluate after operation completes
+   */
+  needsTailSampling?(): boolean;
+  /**
+   * Re-evaluate sampling decision after operation completes (tail sampling)
+   * Only called if needsTailSampling() returns true
+   *
+   * @param context - Sampling context
+   * @param result - Operation result
+   * @returns true if this trace should be kept, false to drop it
+   */
+  shouldKeepTrace?(context: SamplingContext, result: OperationResult): boolean;
+}
+/**
+ * Context information for sampling decisions
+ */
+interface SamplingContext {
+  /** Operation name */
+  operationName: string;
+  /** Method arguments (for extracting user IDs, etc.) */
+  args: unknown[];
+  /** Optional metadata (e.g., feature flags, request headers) */
+  metadata?: Record<string, unknown>;
+  /** Optional span links for links-based sampling */
+  links?: Link[];
+}
+/**
+ * Result of a trace operation (for post-execution sampling)
+ */
+interface OperationResult {
+  /** Whether the operation succeeded */
+  success: boolean;
+  /** Duration in milliseconds */
+  duration: number;
+  /** Error if operation failed */
+  error?: Error;
+}
+/**
+ * Simple random sampler
+ *
+ * @example
+ * ```typescript
+ * new RandomSampler(0.1) // Sample 10% of requests
+ * ```
+ */
+declare class RandomSampler implements Sampler {
+  private readonly sampleRate;
+  constructor(sampleRate: number);
+  shouldSample(_context: SamplingContext): boolean;
+}
+/**
+ * Always sample (100% tracing)
+ */
+declare class AlwaysSampler implements Sampler {
+  shouldSample(_context: SamplingContext): boolean;
+}
+/**
+ * Never sample (0% tracing)
+ */
+declare class NeverSampler implements Sampler {
+  shouldSample(_context: SamplingContext): boolean;
+}
+/**
+ * Adaptive sampler that always traces errors and slow requests
+ *
+ * This is the recommended sampler for production use.
+ * It ensures you never miss critical issues while keeping costs down.
+ *
+ * Strategy:
+ * - Always trace errors (critical for debugging)
+ * - Always trace slow requests (performance issues)
+ * - Use baseline sample rate for successful fast requests
+ *
+ * **IMPORTANT - Tail Sampling Requirement:**
+ * This sampler uses tail sampling (makes decisions AFTER execution).
+ * You MUST use TailSamplingSpanProcessor for it to work correctly:
+ *
+ * - If using initInstrumentation(): TailSamplingSpanProcessor is auto-configured
+ * - If using custom TracerProvider: You MUST manually register TailSamplingSpanProcessor
+ *
+ * Without TailSamplingSpanProcessor, ALL spans are exported (defeating the cost savings).
+ *
+ * @see TailSamplingSpanProcessor
+ * @see README.md "Tail Sampling with Custom Providers" section
+ *
+ * @example
+ * ```typescript
+ * new AdaptiveSampler({
+ *   baselineSampleRate: 0.1,    // 10% of normal requests
+ *   slowThresholdMs: 1000,       // Requests > 1s are "slow"
+ *   alwaysSampleErrors: true,    // Always trace errors
+ *   alwaysSampleSlow: true       // Always trace slow requests
+ * })
+ * ```
+ */
+declare class AdaptiveSampler implements Sampler {
+  private baselineSampleRate;
+  private slowThresholdMs;
+  private alwaysSampleErrors;
+  private alwaysSampleSlow;
+  private linksBased;
+  private linksRate;
+  private logger?;
+  private readonly samplingDecisions;
+  private readonly operationResults;
+  constructor(options?: {
+    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) */
+    linksRate?: number;
+    logger?: Logger;
+  });
+  needsTailSampling(): boolean;
+  shouldSample(context: SamplingContext): boolean;
+  /**
+   * Check if any links point to sampled spans.
+   *
+   * A span is considered linked to a sampled span if any of its links
+   * have trace_flags with the sampled bit set (0x01).
+   *
+   * @param links - Array of span links to check
+   * @returns true if any linked span is sampled, false otherwise
+   */
+  hasSampledLink(links: Link[]): boolean;
+  /**
+   * Re-evaluate sampling decision after operation completes
+   *
+   * This allows us to always capture errors and slow requests,
+   * even if they weren't initially sampled.
+   *
+   * @param context - Sampling context
+   * @param result - Operation result
+   * @returns true if this operation should be kept (not discarded)
+   */
+  shouldKeepTrace(context: SamplingContext, result: OperationResult): boolean;
+}
+/**
+ * User-based sampler for consistent tracing
+ *
+ * Always samples requests from specific user IDs.
+ * Useful for debugging specific user issues or monitoring VIP users.
+ *
+ * @example
+ * ```typescript
+ * new UserIdSampler({
+ *   baselineSampleRate: 0.01,      // 1% of normal users
+ *   alwaysSampleUsers: ['vip_123'], // Always trace VIP users
+ *   extractUserId: (args) => args[0]?.userId // Extract user ID from first arg
+ * })
+ * ```
+ */
+declare class UserIdSampler implements Sampler {
+  private baselineSampleRate;
+  private alwaysSampleUsers;
+  private extractUserId;
+  private logger?;
+  constructor(options: {
+    baselineSampleRate?: number;
+    alwaysSampleUsers?: string[];
+    extractUserId: (args: unknown[]) => string | undefined;
+    logger?: Logger;
+  });
+  shouldSample(context: SamplingContext): boolean;
+  /**
+   * Add user IDs to always-sample list
+   */
+  addAlwaysSampleUsers(...userIds: string[]): void;
+  /**
+   * Remove user IDs from always-sample list
+   */
+  removeAlwaysSampleUsers(...userIds: string[]): void;
+  /**
+   * Simple hash function for consistent user sampling
+   */
+  private hashString;
+}
+/**
+ * Composite sampler that combines multiple samplers
+ *
+ * Samples if ANY of the child samplers returns true.
+ *
+ * @example
+ * ```typescript
+ * new CompositeSampler([
+ *   new UserIdSampler({ extractUserId: (args) => args[0]?.userId }),
+ *   new AdaptiveSampler({ baselineSampleRate: 0.1 })
+ * ])
+ * ```
+ */
+declare class CompositeSampler implements Sampler {
+  private readonly samplers;
+  constructor(samplers: Sampler[]);
+  shouldSample(context: SamplingContext): boolean;
+}
+/**
+ * Feature flag sampler
+ *
+ * Always samples requests with specific feature flags enabled.
+ * Perfect for correlating A/B test experiments with metrics.
+ *
+ * @example
+ * ```typescript
+ * new FeatureFlagSampler({
+ *   baselineSampleRate: 0.01,
+ *   alwaysSampleFlags: ['new_checkout', 'experimental_ui'],
+ *   extractFlags: (args, metadata) => metadata?.featureFlags
+ * })
+ * ```
+ */
+declare class FeatureFlagSampler implements Sampler {
+  private baselineSampleRate;
+  private alwaysSampleFlags;
+  private extractFlags;
+  private logger?;
+  constructor(options: {
+    baselineSampleRate?: number;
+    alwaysSampleFlags?: string[];
+    extractFlags: (args: unknown[], metadata?: Record<string, unknown>) => string[] | undefined;
+    logger?: Logger;
+  });
+  shouldSample(context: SamplingContext): boolean;
+  /**
+   * Add feature flags to always-sample list
+   */
+  addAlwaysSampleFlags(...flags: string[]): void;
+  /**
+   * Remove feature flags from always-sample list
+   */
+  removeAlwaysSampleFlags(...flags: string[]): void;
+}
+/**
+ * Named sampling presets for common environments.
+ * Use with `init({ sampling: 'production' })` or directly via factories.
+ */
+type SamplingPreset = 'development' | 'errors-only' | 'production' | 'off';
+/**
+ * Sampling preset factories.
+ *
+ * For most users, the string shorthand on `init()` is simpler:
+ * ```typescript
+ * init({ service: 'my-app', sampling: 'production' })
+ * ```
+ *
+ * Use factories when you need to customize:
+ * ```typescript
+ * init({ service: 'my-app', sampler: samplingPresets.production({ baselineSampleRate: 0.05 }) })
+ * ```
+ */
+declare const samplingPresets: {
+  /** 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.
+   * Pass overrides to tune (uses the same option names as AdaptiveSampler).
+   */
+  production: (overrides?: {
+    baselineSampleRate?: number;
+    slowThresholdMs?: number;
+    alwaysSampleErrors?: boolean;
+    alwaysSampleSlow?: boolean;
+  }) => AdaptiveSampler; /** Disable sampling entirely */
+  off: () => NeverSampler;
+};
+/**
+ * Resolve a preset string to a Sampler instance.
+ * Used internally by `init()` when `sampling` string is provided.
+ *
+ * @throws Error if preset is not recognized
+ */
+declare function resolveSamplingPreset(preset: SamplingPreset): Sampler;
+/**
+ * Create a Link from W3C trace context headers (e.g., from a message queue).
+ *
+ * This is useful for message consumers that need to link to the producer span.
+ * The headers should contain at least a `traceparent` header in W3C format.
+ *
+ * @param headers - Dictionary containing traceparent/tracestate headers
+ * @param attributes - Optional attributes for the link
+ * @returns Link object if context could be extracted, null otherwise
+ *
+ * @example
+ * ```typescript
+ * // In a Kafka consumer
+ * const headers = { traceparent: '00-abc123...-def456...-01' };
+ * const link = createLinkFromHeaders(headers);
+ * if (link) {
+ *   // Use with tracer.startActiveSpan options or ctx.addLink()
+ *   tracer.startActiveSpan('process.message', { links: [link] }, span => { ... });
+ * }
+ * ```
+ */
+declare function createLinkFromHeaders(headers: Record<string, string>, attributes?: Attributes): Link | null;
+/**
+ * Extract Links from a batch of messages for fan-in scenarios.
+ *
+ * Useful for batch processing where multiple producer spans should be linked.
+ * This enables tracing causality in event-driven architectures where a single
+ * consumer processes messages from multiple producers.
+ *
+ * @param messages - List of message objects
+ * @param headersKey - Key in each message containing trace headers (default: 'headers')
+ * @returns List of Link objects for all valid trace contexts
+ *
+ * @example
+ * ```typescript
+ * // Processing a batch of SQS/Kafka messages
+ * const messages = [
+ *   { body: '...', headers: { traceparent: '...' } },
+ *   { body: '...', headers: { traceparent: '...' } },
+ * ];
+ * const links = extractLinksFromBatch(messages);
+ *
+ * tracer.startActiveSpan('process.batch', { links }, span => {
+ *   for (const msg of messages) {
+ *     processMessage(msg);
+ *   }
+ * });
+ * ```
+ */
+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