qa360 2.1.7 → 2.2.0

package/core/src/slo/slo-tracker.ts

@@ -0,0 +1,481 @@
+/**
+ * SLO Tracker
+ *
+ * Tracks Service Level Objectives and manages error budgets.
+ * Monitors SLO compliance and generates reports.
+ */
+
+import type {
+  SLO,
+  SLI,
+  SLIMeasurement,
+  SLOResult,
+  SLOReport,
+  SLOStatus,
+  SLOViolation,
+  ErrorBudget,
+  BurnRate
+} from './types.js';
+import { SLICalculator } from './sli-calculator.js';
+
+/**
+ * SLO Tracker Options
+ */
+export interface SLOTrackerOptions {
+  /** Warning threshold as % of target */
+  warningThreshold?: number;
+
+  /** Enable violation tracking */
+  trackViolations?: boolean;
+
+  /** Enable alerting */
+  enableAlerts?: boolean;
+
+  /** Alert callback */
+  onAlert?: (alert: SLOAlert) => void;
+}
+
+/**
+ * SLO Alert
+ */
+export interface SLOAlert {
+  sloId: string;
+  sloName: string;
+  severity: 'warning' | 'critical';
+  message: string;
+  currentValue: number;
+  target: number;
+  errorBudgetRemaining: number;
+  timestamp: number;
+}
+
+/**
+ * SLO Tracker class
+ */
+export class SLOTracker {
+  private slos: Map<string, SLO> = new Map();
+  private slis: Map<string, SLI> = new Map();
+  private measurements: Map<string, SLIMeasurement[]> = new Map();
+  private violations: SLOViolation[] = [];
+  private calculator: SLICalculator;
+  private options: Required<SLOTrackerOptions>;
+
+  constructor(options: SLOTrackerOptions = {}) {
+    this.calculator = new SLICalculator();
+    this.options = {
+      warningThreshold: options.warningThreshold ?? 0.95,
+      trackViolations: options.trackViolations ?? true,
+      enableAlerts: options.enableAlerts ?? true,
+      onAlert: options.onAlert ?? (() => {})
+    };
+  }
+
+  /**
+   * Register an SLO
+   */
+  registerSLO(slo: SLO): void {
+    this.slos.set(slo.id, slo);
+  }
+
+  /**
+   * Register an SLI
+   */
+  registerSLI(sli: SLI): void {
+  this.slis.set(sli.id, sli);
+  }
+
+  /**
+   * Register multiple SLOs
+   */
+  registerSLOs(slos: SLO[]): void {
+    for (const slo of slos) {
+      this.registerSLO(slo);
+    }
+  }
+
+  /**
+   * Register multiple SLIs
+   */
+  registerSLIs(slis: SLI[]): void {
+    for (const sli of slis) {
+      this.registerSLI(sli);
+    }
+  }
+
+  /**
+   * Get an SLO by ID
+   */
+  getSLO(id: string): SLO | undefined {
+    return this.slos.get(id);
+  }
+
+  /**
+   * Get an SLI by ID
+   */
+  getSLI(id: string): SLI | undefined {
+    return this.slis.get(id);
+  }
+
+  /**
+   * Get all registered SLOs
+   */
+  getAllSLOs(): SLO[] {
+    return Array.from(this.slos.values());
+  }
+
+  /**
+   * Get all registered SLIs
+   */
+  getAllSLIs(): SLI[] {
+    return Array.from(this.slis.values());
+  }
+
+  /**
+   * Record a measurement for an SLI
+   */
+  recordMeasurement(measurement: SLIMeasurement): void {
+    const sli = this.slis.get(measurement.sliId);
+    if (!sli) {
+      throw new Error(`SLI not found: ${measurement.sliId}`);
+    }
+
+    if (!this.measurements.has(measurement.sliId)) {
+      this.measurements.set(measurement.sliId, []);
+    }
+
+    const measurements = this.measurements.get(measurement.sliId)!;
+    measurements.push(measurement);
+
+    // Keep only measurements within the longest SLO window
+    const longestWindow = this.getLongestWindow();
+    const cutoff = Date.now() - longestWindow;
+    const filtered = measurements.filter(m => m.timestamp >= cutoff);
+    this.measurements.set(measurement.sliId, filtered);
+
+    // Update dependent SLOs
+    this.updateDependentSLOs(measurement.sliId);
+  }
+
+  /**
+   * Get measurements for an SLI
+   */
+  getMeasurements(sliId: string, windowMs?: number): SLIMeasurement[] {
+    const measurements = this.measurements.get(sliId) || [];
+
+    if (!windowMs) {
+      return measurements;
+    }
+
+    const cutoff = Date.now() - windowMs;
+    return measurements.filter(m => m.timestamp >= cutoff);
+  }
+
+  /**
+   * Calculate SLO result
+   */
+  calculateSLOResult(sloId: string): SLOResult | null {
+    const slo = this.slos.get(sloId);
+    if (!slo) {
+      return null;
+    }
+
+    // Get measurements for all SLIs in the SLO
+    const windowStart = Date.now() - slo.windowMs;
+    const sliResults: SLOResult['slis'] = [];
+
+    for (const sliId of slo.sliIds) {
+      const sli = this.slis.get(sliId);
+      if (!sli) continue;
+
+      const measurements = this.getMeasurements(sliId, slo.windowMs);
+      if (measurements.length === 0) continue;
+
+      // Get the most recent measurement or aggregate
+      const latest = measurements[measurements.length - 1];
+      sliResults.push({
+        sliId: sli.id,
+        name: sli.name,
+        value: latest.value,
+        target: slo.target,
+        contribution: 1 / slo.sliIds.length // Equal weight by default
+      });
+    }
+
+    if (sliResults.length === 0) {
+      return null;
+    }
+
+    // Calculate weighted average for SLO value
+    const current = sliResults.reduce((sum, s) => sum + s.value * s.contribution, 0);
+
+    // Calculate error budget
+    const errorBudget = this.calculateErrorBudget(slo, current);
+
+    // Determine status
+    const status = this.calculator.determineStatus(
+      current,
+      slo.target,
+      this.options.warningThreshold
+    );
+
+    // Update SLO
+    slo.currentValue = current;
+    slo.status = status;
+    slo.errorBudget = errorBudget;
+
+    return {
+      sloId: slo.id,
+      name: slo.name,
+      target: slo.target,
+      current,
+      status,
+      errorBudget: {
+        initial: errorBudget.initialBudget,
+        remaining: errorBudget.remainingBudget,
+        burned: errorBudget.initialBudget - errorBudget.remainingBudget,
+        burnRate: errorBudget.remainingBudget > 0
+          ? (errorBudget.initialBudget - errorBudget.remainingBudget) / errorBudget.initialBudget
+          : 1
+      },
+      slis: sliResults
+    };
+  }
+
+  /**
+   * Calculate all SLO results
+   */
+  calculateAllResults(): SLOResult[] {
+    const results: SLOResult[] = [];
+
+    for (const sloId of this.slos.keys()) {
+      const result = this.calculateSLOResult(sloId);
+      if (result) {
+        results.push(result);
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Generate SLO report
+   */
+  generateReport(period?: { start: number; end: number }): SLOReport {
+    const results = this.calculateAllResults();
+
+    const summary = {
+      total: results.length,
+      healthy: results.filter(r => r.status === 'healthy').length,
+      warning: results.filter(r => r.status === 'warning').length,
+      breached: results.filter(r => r.status === 'breached').length
+    };
+
+    const overallStatus: SLOStatus =
+      summary.breached > 0 ? 'breached'
+      : summary.warning > 0 ? 'warning'
+      : summary.healthy > 0 ? 'healthy'
+      : 'unknown';
+
+    return {
+      id: `report_${Date.now()}`,
+      timestamp: Date.now(),
+      period: period || {
+        start: Date.now() - this.getLongestWindow(),
+        end: Date.now()
+      },
+      slos: results,
+      status: overallStatus,
+      summary
+    };
+  }
+
+  /**
+   * Get error budget for an SLO
+   */
+  getErrorBudget(sloId: string): ErrorBudget | null {
+    const slo = this.slos.get(sloId);
+    if (!slo) {
+      return null;
+    }
+
+    const result = this.calculateSLOResult(sloId);
+    if (!result) {
+      return slo.errorBudget;
+    }
+
+    return slo.errorBudget;
+  }
+
+  /**
+   * Calculate burn rate for an SLO
+   */
+  calculateBurnRate(sloId: string): BurnRate | null {
+    const slo = this.slos.get(sloId);
+    if (!slo) {
+      return null;
+    }
+
+    // Get all measurements for SLIs in this SLO
+    const allMeasurements: SLIMeasurement[] = [];
+    for (const sliId of slo.sliIds) {
+      const measurements = this.getMeasurements(sliId, slo.windowMs);
+      allMeasurements.push(...measurements);
+    }
+
+    if (allMeasurements.length === 0) {
+      return null;
+    }
+
+    return this.calculator.calculateBurnRate(allMeasurements, slo.target, slo.windowMs);
+  }
+
+  /**
+   * Get violations for an SLO
+   */
+  getViolations(sloId?: string): SLOViolation[] {
+    if (sloId) {
+      return this.violations.filter(v => v.sloId === sloId);
+    }
+    return this.violations;
+  }
+
+  /**
+   * Clear violations
+   */
+  clearViolations(sloId?: string): void {
+    if (sloId) {
+      this.violations = this.violations.filter(v => v.sloId !== sloId);
+    } else {
+      this.violations = [];
+    }
+  }
+
+  /**
+   * Resolve a violation
+   */
+  resolveViolation(violationId: string): void {
+    const violation = this.violations.find(v => v.id === violationId);
+    if (violation) {
+      violation.resolved = true;
+      violation.resolvedAt = Date.now();
+    }
+  }
+
+  /**
+   * Calculate error budget from current value and target
+   */
+  private calculateErrorBudget(slo: SLO, currentValue: number): ErrorBudget {
+    const initialBudget = 100 - slo.target;
+    const burned = Math.max(0, slo.target - currentValue);
+    const remaining = Math.max(0, initialBudget - burned);
+
+    return {
+      ...slo.errorBudget,
+      initialBudget,
+      remainingBudget: remaining
+    };
+  }
+
+  /**
+   * Update SLOs that depend on an SLI
+   */
+  private updateDependentSLOs(sliId: string): void {
+    for (const slo of this.slos.values()) {
+      if (!slo.sliIds.includes(sliId)) continue;
+
+      const result = this.calculateSLOResult(slo.id);
+      if (!result) continue;
+
+      // Check for violations
+      if (this.options.trackViolations) {
+        this.checkForViolation(slo, result);
+      }
+
+      // Generate alerts
+      if (this.options.enableAlerts) {
+        this.generateAlerts(slo, result);
+      }
+    }
+  }
+
+  /**
+   * Check for SLO violation
+   */
+  private checkForViolation(slo: SLO, result: SLOResult): void {
+    const now = Date.now();
+
+    // Check if we just breached
+    if (result.status === 'breached' && slo.status !== 'breached') {
+      this.violations.push({
+        id: `violation_${now}_${slo.id}`,
+        sloId: slo.id,
+        timestamp: now,
+        value: result.current,
+        expected: result.target,
+        severity: 'critical',
+        resolved: false
+      });
+    }
+
+    // Check if we just hit warning
+    if (result.status === 'warning' && slo.status === 'healthy') {
+      this.violations.push({
+        id: `warning_${now}_${slo.id}`,
+        sloId: slo.id,
+        timestamp: now,
+        value: result.current,
+        expected: result.target,
+        severity: 'warning',
+        resolved: false
+      });
+    }
+  }
+
+  /**
+   * Generate alerts for SLO status
+   */
+  private generateAlerts(slo: SLO, result: SLOResult): void {
+    if (result.status === 'breached' || result.status === 'warning') {
+      this.options.onAlert({
+        sloId: slo.id,
+        sloName: slo.name,
+        severity: result.status === 'breached' ? 'critical' : 'warning',
+        message: `SLO "${slo.name}" is ${result.status}: ${result.current.toFixed(2)}% < ${result.target}%`,
+        currentValue: result.current,
+        target: result.target,
+        errorBudgetRemaining: result.errorBudget.remaining,
+        timestamp: Date.now()
+      });
+    }
+  }
+
+  /**
+   * Get the longest window from all SLOs
+   */
+  private getLongestWindow(): number {
+    let max = 0;
+    for (const slo of this.slos.values()) {
+      if (slo.windowMs > max) {
+        max = slo.windowMs;
+      }
+    }
+    return max || 86400000 * 30; // Default 30 days
+  }
+
+  /**
+   * Clear all data
+   */
+  clear(): void {
+    this.slos.clear();
+    this.slis.clear();
+    this.measurements.clear();
+    this.violations = [];
+  }
+}
+
+/**
+ * Create an SLO tracker
+ */
+export function createSLOTracker(options?: SLOTrackerOptions): SLOTracker {
+  return new SLOTracker(options);
+}