autotel/dist/slo.d.cts

Write Once, Observe Anywhere

import { Attributes } from "@opentelemetry/api";
//#region src/slo.d.ts
type SloOutcome = 'good' | 'bad';
interface SloDefinition {
  /** Stable identifier used in metric attributes and alerts. */
  name: string;
  /** Required success ratio, expressed as a value between 0 and 1. */
  target: number;
  /** Rolling observation window in milliseconds. */
  windowMs: number;
}
interface SloTrackerOptions {
  /** Clock override for deterministic tests. */
  now?: () => number;
  /** Disable metric recording when calculations run outside an initialized SDK. */
  recordMetrics?: boolean;
}
interface SloSnapshot extends SloDefinition {
  observedAt: number;
  total: number;
  good: number;
  bad: number;
  /** Observed good-event ratio. Undefined until the tracker sees an event. */
  sli?: number;
  /** Fraction of events the objective permits to fail. */
  errorBudgetFraction: number;
  /** Fraction of the available error budget consumed in this window. */
  budgetConsumed: number;
  /** Remaining budget fraction. Negative values show overspend. */
  budgetRemaining: number;
  /** Observed failure ratio divided by the permitted failure ratio. */
  burnRate: number;
  meetsTarget: boolean;
}
interface SloTracker {
  readonly definition: Readonly<SloDefinition>;
  record(outcome: SloOutcome, attributes?: Attributes): SloSnapshot;
  snapshot(at?: number): SloSnapshot;
  forecast(options: SloForecastOptions): SloForecast;
  reset(): void;
}
interface SloForecastOptions {
  /** Recent observation period used to estimate the future failure rate. */
  baselineMs: number;
  /** Future period covered by the forecast. Must not exceed 4x the baseline. */
  lookaheadMs: number;
  /**
   * Expected eligible events during the lookahead. Defaults to the event rate
   * observed during the baseline.
   */
  expectedEventsInLookahead?: number;
}
interface SloForecast {
  name: string;
  target: number;
  observedAt: number;
  baselineMs: number;
  lookaheadMs: number;
  baselineTotal: number;
  baselineBad: number;
  baselineFailureRate: number;
  retainedTotal: number;
  retainedBad: number;
  projectedTotal: number;
  projectedBad: number;
  projectedSli?: number;
  /** Milliseconds until the retained and projected error budget is exhausted. */
  timeToExhaustionMs?: number;
  alerting: boolean;
  reason: 'no-baseline-traffic' | 'within-budget' | 'projected-budget-exhaustion';
}
interface BurnRateAlertOptions {
  shortWindow: SloSnapshot;
  longWindow: SloSnapshot;
  shortThreshold: number;
  longThreshold: number;
}
interface BurnRateAlertDecision {
  alerting: boolean;
  reason: 'burn-rate-thresholds-exceeded' | 'short-window-below-threshold' | 'long-window-below-threshold' | 'no-traffic';
  shortBurnRate: number;
  longBurnRate: number;
}
/**
 * Track good and bad events for one rolling-window service level objective.
 */
declare function createSloTracker(definition: SloDefinition, options?: SloTrackerOptions): SloTracker;
/**
 * Evaluate a dual-window burn-rate alert.
 *
 * Both windows must exceed their threshold. The short window catches a sharp
 * regression while the long window rejects brief spikes.
 */
declare function evaluateBurnRateAlert(options: BurnRateAlertOptions): BurnRateAlertDecision;
//#endregion
export { BurnRateAlertDecision, BurnRateAlertOptions, SloDefinition, SloForecast, SloForecastOptions, SloOutcome, SloSnapshot, SloTracker, SloTrackerOptions, createSloTracker, evaluateBurnRateAlert };
//# sourceMappingURL=slo.d.cts.map