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