import { SpanType } from "@graphorin/core";

//#region src/tracer/sampling.d.ts

/** @stable */
type SamplingDecisionMaker = 'parent-based' | 'always-on' | 'rate-limit';
/**
 * Per-span-type rate override. Applies on the probabilistic root path
 * AND to children of a sampled parent under `'parent-based'` -
 * `{ type: 'tool.execute', rate: 0.01 }` thins the per-call spans
 * inside every sampled `agent.run` trace. A child dropped by its rule
 * breaks the tree below it: its own descendants inherit
 * `parentSampled=false`.
 *
 * @stable
 */
interface SamplingRule {
  readonly type: SpanType | string;
  readonly rate: number;
}
/**
 * Configuration shape consumed by {@link createSampler}.
 *
 * @stable
 */
interface SamplingOptions {
  /** Default head-sampling rate. Must be in `[0, 1]`. Defaults to `1.0`. */
  readonly rate?: number;
  /** Per-type overrides. Last write wins on duplicate `type`. */
  readonly rules?: ReadonlyArray<SamplingRule>;
  /** Decision maker. Defaults to `'parent-based'`. */
  readonly decisionMaker?: SamplingDecisionMaker;
  /**
   * Cap for the `'rate-limit'` decision maker: at most this many root spans
   * are sampled per rolling 1-second window. `undefined` ⇒ no cap
   * (samples everything); `0` ⇒ sample nothing. Ignored by the other
   * decision makers.
   */
  readonly maxPerSecond?: number;
  /**
   * Clock for the `'rate-limit'` window. Defaults to `Date.now`.
   *
   * @internal
   */
  readonly now?: () => number;
  /**
   * Optional override for streaming-event sampling.
   * @see the streaming event family `tool.execute.{progress,partial}`.
   */
  readonly streaming?: {
    readonly eventSamplingRate?: number;
    readonly includeChunkContent?: 'none' | 'text-only' | 'all';
  };
  /**
   * Override for the random source. Useful for deterministic tests.
   *
   * @internal
   */
  readonly random?: () => number;
}
/**
 * @stable
 */
interface Sampler {
  /** Decide whether a span of the given type should be recorded. */
  shouldSample(type: SpanType | string, parentSampled?: boolean): boolean;
  /** Decide whether a span event of the given name should be recorded. */
  shouldRecordEvent(name: string): boolean;
  /** Returns whether chunk *content* should travel through the exporter. */
  shouldIncludeChunkContent(): boolean;
}
/**
 * Build a {@link Sampler} from the supplied options. The sampler is
 * intentionally inexpensive - every decision boils down to a single
 * `random < threshold` comparison.
 *
 * @stable
 */
declare function createSampler(opts?: SamplingOptions): Sampler;
//#endregion
export { Sampler, SamplingDecisionMaker, SamplingOptions, SamplingRule, createSampler };
//# sourceMappingURL=sampling.d.ts.map