@kb-labs/rest-api-app 1.3.0

package/src/services/historical-metrics.ts

@@ -0,0 +1,496 @@
+/**
+ * @module @kb-labs/rest-api-app/services/historical-metrics
+ * Historical metrics collection and storage service
+ */
+
+import type { CacheAdapter } from '@kb-labs/plugin-contracts';
+import { metricsCollector } from '../middleware/metrics.js';
+
+/**
+ * Historical data point
+ */
+export interface HistoricalDataPoint {
+  timestamp: number;
+  value: number;
+}
+
+/**
+ * Heatmap cell data
+ */
+export interface HeatmapCell {
+  day: string; // 'Mon', 'Tue', etc.
+  hour: number; // 0-23
+  value: number;
+}
+
+/**
+ * Metrics snapshot for historical storage
+ */
+interface MetricsSnapshot {
+  timestamp: number;
+  requests: {
+    total: number;
+    success: number;
+    clientErrors: number;
+    serverErrors: number;
+  };
+  latency: {
+    average: number;
+    min: number;
+    max: number;
+    p50?: number;
+    p95?: number;
+    p99?: number;
+  };
+  uptime: number; // seconds
+  perPlugin: Array<{
+    pluginId?: string;
+    requests: number;
+    errors: number;
+    avgLatency: number;
+  }>;
+}
+
+/**
+ * Historical metrics collector configuration
+ */
+export interface HistoricalMetricsConfig {
+  /** Collection interval in milliseconds (default: 5000 = 5s) */
+  intervalMs?: number;
+  /** Maximum points to store per time range */
+  maxPoints?: {
+    /** Last 1 minute (default: 12 points at 5s intervals) */
+    '1m'?: number;
+    /** Last 5 minutes (default: 60 points) */
+    '5m'?: number;
+    /** Last 10 minutes (default: 120 points) */
+    '10m'?: number;
+    /** Last 30 minutes (default: 360 points) */
+    '30m'?: number;
+    /** Last 1 hour (default: 720 points) */
+    '1h'?: number;
+  };
+  /** Enable debug logging */
+  debug?: boolean;
+}
+
+const DEFAULT_CONFIG: Required<HistoricalMetricsConfig> = {
+  intervalMs: 5000,
+  maxPoints: {
+    '1m': 12,
+    '5m': 60,
+    '10m': 120,
+    '30m': 360,
+    '1h': 720,
+  },
+  debug: false,
+};
+
+/**
+ * Historical metrics collector service
+ *
+ * Collects and stores historical metrics data in platform.cache with TTL-based retention.
+ * Provides time-series data for dashboards and analytics.
+ */
+export class HistoricalMetricsCollector {
+  private cache: CacheAdapter;
+  private config: Required<HistoricalMetricsConfig>;
+  private intervalHandle: NodeJS.Timeout | null = null;
+  private logger: Console | any;
+  private startTimeMs: number = Date.now();
+
+  constructor(cache: CacheAdapter, config: HistoricalMetricsConfig = {}, logger: Console | any = console) {
+    this.cache = cache;
+    this.config = { ...DEFAULT_CONFIG, ...config, maxPoints: { ...DEFAULT_CONFIG.maxPoints, ...config.maxPoints } };
+    this.logger = logger;
+  }
+
+  /**
+   * Start background collection
+   */
+  start(): void {
+    if (this.intervalHandle) {
+      this.log('warn', 'Historical metrics collector already started');
+      return;
+    }
+
+    this.log('info', 'Starting historical metrics collector', {
+      intervalMs: this.config.intervalMs,
+    });
+
+    // Collect immediately, then every intervalMs
+    this.collect().catch(err => {
+      this.log('error', 'Failed to collect initial metrics', { err });
+    });
+
+    this.intervalHandle = setInterval(() => {
+      this.collect().catch(err => {
+        this.log('error', 'Failed to collect metrics', { err });
+      });
+    }, this.config.intervalMs);
+  }
+
+  /**
+   * Stop background collection
+   */
+  stop(): void {
+    if (this.intervalHandle) {
+      clearInterval(this.intervalHandle);
+      this.intervalHandle = null;
+      this.log('info', 'Historical metrics collector stopped');
+    }
+  }
+
+  /**
+   * Collect current metrics snapshot and store in cache
+   */
+  private async collect(): Promise<void> {
+    const now = Date.now();
+    const metrics = metricsCollector.getMetrics();
+
+    // Build snapshot
+    const snapshot: MetricsSnapshot = {
+      timestamp: now,
+      requests: {
+        total: metrics.requests.total,
+        success: metrics.requests.success ?? 0,
+        clientErrors: metrics.requests.clientErrors ?? 0,
+        serverErrors: metrics.requests.serverErrors ?? 0,
+      },
+      latency: {
+        average: metrics.latency.average,
+        min: metrics.latency.min === Infinity ? 0 : metrics.latency.min,
+        max: metrics.latency.max,
+      },
+      uptime: (now - metrics.timestamps.startTime) / 1000,
+      perPlugin: metrics.perPlugin.map(p => ({
+        pluginId: p.pluginId,
+        requests: p.total,
+        errors: Object.values(p.statuses)
+          .filter((_, idx) => Object.keys(p.statuses)[idx]?.startsWith('4') || Object.keys(p.statuses)[idx]?.startsWith('5'))
+          .reduce((sum, count) => sum + count, 0),
+        avgLatency: p.total > 0 ? p.totalDuration / p.total : 0,
+      })),
+    };
+
+    // Store in each time range bucket
+    await Promise.all([
+      this.appendToTimeSeries('1m', snapshot, 2 * 60 * 1000), // TTL: 2 minutes
+      this.appendToTimeSeries('5m', snapshot, 10 * 60 * 1000), // TTL: 10 minutes
+      this.appendToTimeSeries('10m', snapshot, 20 * 60 * 1000), // TTL: 20 minutes
+      this.appendToTimeSeries('30m', snapshot, 60 * 60 * 1000), // TTL: 1 hour
+      this.appendToTimeSeries('1h', snapshot, 2 * 60 * 60 * 1000), // TTL: 2 hours
+    ]);
+
+    // Update heatmap aggregation (less frequently - every minute)
+    if (now % 60000 < this.config.intervalMs) {
+      await this.updateHeatmapAggregation(snapshot).catch(err => {
+        this.log('error', 'Failed to update heatmap', { err });
+      });
+    }
+
+    this.log('debug', 'Metrics snapshot collected', {
+      timestamp: new Date(now).toISOString(),
+      requests: snapshot.requests.total,
+      latency: snapshot.latency.average.toFixed(2),
+    });
+  }
+
+  /**
+   * Append snapshot to time series bucket
+   */
+  private async appendToTimeSeries(range: keyof typeof DEFAULT_CONFIG.maxPoints, snapshot: MetricsSnapshot, ttlMs: number): Promise<void> {
+    const key = `metrics:history:${range}`;
+    const maxPoints = this.config.maxPoints[range] ?? 120;
+
+    // Get existing time series
+    let timeSeries = await this.cache.get<MetricsSnapshot[]>(key);
+    if (!timeSeries || !Array.isArray(timeSeries)) {
+      timeSeries = [];
+    }
+
+    // Append new snapshot
+    timeSeries.push(snapshot);
+
+    // Trim to max points (FIFO)
+    if (timeSeries.length > maxPoints) {
+      timeSeries = timeSeries.slice(timeSeries.length - maxPoints);
+    }
+
+    // Store back with TTL
+    await this.cache.set(key, timeSeries, ttlMs);
+  }
+
+  /**
+   * Update heatmap aggregation for weekly patterns
+   */
+  private async updateHeatmapAggregation(snapshot: MetricsSnapshot): Promise<void> {
+    const key = 'metrics:heatmap:7d';
+    const ttlMs = 24 * 60 * 60 * 1000; // 24 hours
+
+    // Get existing heatmap data
+    let heatmapData = await this.cache.get<Record<string, HeatmapCell[]>>(key);
+    if (!heatmapData || typeof heatmapData !== 'object') {
+      heatmapData = { latency: [], errors: [], requests: [] };
+    }
+
+    // Calculate current day and hour
+    const date = new Date(snapshot.timestamp);
+    const day = (['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'] as const)[date.getDay() as 0|1|2|3|4|5|6];
+    const hour = date.getHours();
+
+    // Update each metric type
+    for (const metricType of ['latency', 'errors', 'requests'] as const) {
+      let cells = heatmapData[metricType] || [];
+
+      // Find or create cell for this day/hour
+      const cellIndex = cells.findIndex(c => c.day === day && c.hour === hour);
+
+      let value = 0;
+      if (metricType === 'latency') {
+        value = snapshot.latency.average;
+      } else if (metricType === 'errors') {
+        value = snapshot.requests.clientErrors + snapshot.requests.serverErrors;
+      } else {
+        value = snapshot.requests.total;
+      }
+
+      if (cellIndex >= 0 && cells[cellIndex]) {
+        // Update existing cell (exponential moving average)
+        cells[cellIndex]!.value = cells[cellIndex]!.value * 0.9 + value * 0.1;
+      } else {
+        // Add new cell
+        cells.push({ day, hour, value });
+      }
+
+      // Keep only last 7 days worth of unique day/hour combinations (7 * 24 = 168 cells max)
+      if (cells.length > 168) {
+        cells = cells.slice(cells.length - 168);
+      }
+
+      heatmapData[metricType] = cells;
+    }
+
+    // Store back with TTL
+    await this.cache.set(key, heatmapData, ttlMs);
+  }
+
+  /**
+   * Query historical time-series data
+   */
+  async queryHistory(params: {
+    metric: 'requests' | 'errors' | 'latency' | 'uptime';
+    range: '1m' | '5m' | '10m' | '30m' | '1h';
+    interval?: '5s' | '1m' | '5m';
+  }): Promise<HistoricalDataPoint[]> {
+    const key = `metrics:history:${params.range}`;
+
+    // Get time series from cache
+    const timeSeries = await this.cache.get<MetricsSnapshot[]>(key);
+    if (!timeSeries || !Array.isArray(timeSeries)) {
+      return [];
+    }
+
+    // Extract requested metric
+    const dataPoints: HistoricalDataPoint[] = timeSeries.map(snapshot => {
+      let value = 0;
+
+      switch (params.metric) {
+        case 'requests':
+          value = snapshot.requests.total;
+          break;
+        case 'errors':
+          value = snapshot.requests.clientErrors + snapshot.requests.serverErrors;
+          break;
+        case 'latency':
+          value = snapshot.latency.average;
+          break;
+        case 'uptime':
+          value = snapshot.uptime;
+          break;
+      }
+
+      return {
+        timestamp: snapshot.timestamp,
+        value,
+      };
+    });
+
+    // Apply interval aggregation if requested
+    if (params.interval && params.interval !== '5s') {
+      return this.aggregateByInterval(dataPoints, params.interval);
+    }
+
+    return dataPoints;
+  }
+
+  /**
+   * Query heatmap data
+   */
+  async queryHeatmap(params: {
+    metric: 'latency' | 'errors' | 'requests';
+    days?: 7 | 14 | 30;
+  }): Promise<HeatmapCell[]> {
+    const key = 'metrics:heatmap:7d';
+
+    // Get heatmap data from cache
+    const heatmapData = await this.cache.get<Record<string, HeatmapCell[]>>(key);
+    if (!heatmapData || typeof heatmapData !== 'object') {
+      // Return empty heatmap structure
+      return this.generateEmptyHeatmap();
+    }
+
+    const cells = heatmapData[params.metric] || [];
+
+    // If no data yet, return empty heatmap
+    if (cells.length === 0) {
+      return this.generateEmptyHeatmap();
+    }
+
+    // Ensure all day/hour combinations exist (fill missing with 0)
+    return this.fillHeatmapGaps(cells);
+  }
+
+  /**
+   * Generate empty heatmap structure (7 days × 24 hours)
+   */
+  private generateEmptyHeatmap(): HeatmapCell[] {
+    const days = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'];
+    const cells: HeatmapCell[] = [];
+
+    for (const day of days) {
+      for (let hour = 0; hour < 24; hour++) {
+        cells.push({ day, hour, value: 0 });
+      }
+    }
+
+    return cells;
+  }
+
+  /**
+   * Fill gaps in heatmap data (missing day/hour combinations)
+   */
+  private fillHeatmapGaps(cells: HeatmapCell[]): HeatmapCell[] {
+    const days = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'];
+    const cellMap = new Map<string, number>();
+
+    // Index existing cells
+    for (const cell of cells) {
+      const key = `${cell.day}:${cell.hour}`;
+      cellMap.set(key, cell.value);
+    }
+
+    // Generate complete 7×24 grid
+    const complete: HeatmapCell[] = [];
+    for (const day of days) {
+      for (let hour = 0; hour < 24; hour++) {
+        const key = `${day}:${hour}`;
+        complete.push({
+          day,
+          hour,
+          value: cellMap.get(key) ?? 0,
+        });
+      }
+    }
+
+    return complete;
+  }
+
+  /**
+   * Aggregate data points by interval
+   */
+  private aggregateByInterval(dataPoints: HistoricalDataPoint[], interval: '1m' | '5m'): HistoricalDataPoint[] {
+    if (dataPoints.length === 0) {return [];}
+
+    const intervalMs = interval === '1m' ? 60 * 1000 : 5 * 60 * 1000;
+    const aggregated: HistoricalDataPoint[] = [];
+
+    let bucket: HistoricalDataPoint[] = [];
+    let bucketStart = Math.floor(dataPoints[0]!.timestamp / intervalMs) * intervalMs;
+
+    for (const point of dataPoints) {
+      const pointBucket = Math.floor(point.timestamp / intervalMs) * intervalMs;
+
+      if (pointBucket === bucketStart) {
+        bucket.push(point);
+      } else {
+        // Finalize current bucket
+        if (bucket.length > 0) {
+          const avgValue = bucket.reduce((sum, p) => sum + p.value, 0) / bucket.length;
+          aggregated.push({
+            timestamp: bucketStart + intervalMs / 2, // midpoint
+            value: avgValue,
+          });
+        }
+
+        // Start new bucket
+        bucket = [point];
+        bucketStart = pointBucket;
+      }
+    }
+
+    // Finalize last bucket
+    if (bucket.length > 0) {
+      const avgValue = bucket.reduce((sum, p) => sum + p.value, 0) / bucket.length;
+      aggregated.push({
+        timestamp: bucketStart + intervalMs / 2,
+        value: avgValue,
+      });
+    }
+
+    return aggregated;
+  }
+
+  /**
+   * Get collector statistics
+   */
+  async getStats(): Promise<{
+    running: boolean;
+    uptimeSeconds: number;
+    timeSeries: Record<string, { points: number; oldestTimestamp: number | null; newestTimestamp: number | null }>;
+    heatmap: { cells: number; metrics: string[] };
+  }> {
+    const stats: any = {
+      running: this.intervalHandle !== null,
+      uptimeSeconds: (Date.now() - this.startTimeMs) / 1000,
+      timeSeries: {},
+      heatmap: { cells: 0, metrics: [] },
+    };
+
+    // Check each time range
+    for (const range of ['1m', '5m', '10m', '30m', '1h'] as const) {
+      const key = `metrics:history:${range}`;
+      const timeSeries = await this.cache.get<MetricsSnapshot[]>(key);
+
+      if (timeSeries && Array.isArray(timeSeries)) {
+        stats.timeSeries[range] = {
+          points: timeSeries.length,
+          oldestTimestamp: timeSeries[0]?.timestamp ?? null,
+          newestTimestamp: timeSeries[timeSeries.length - 1]?.timestamp ?? null,
+        };
+      } else {
+        stats.timeSeries[range] = { points: 0, oldestTimestamp: null, newestTimestamp: null };
+      }
+    }
+
+    // Check heatmap
+    const heatmapData = await this.cache.get<Record<string, HeatmapCell[]>>('metrics:heatmap:7d');
+    if (heatmapData && typeof heatmapData === 'object') {
+      const metrics = Object.keys(heatmapData);
+      const totalCells = metrics.reduce((sum, m) => sum + (heatmapData[m]?.length ?? 0), 0);
+      stats.heatmap = { cells: totalCells, metrics };
+    }
+
+    return stats;
+  }
+
+  private log(level: 'info' | 'warn' | 'error' | 'debug', message: string, meta?: any): void {
+    if (level === 'debug' && !this.config.debug) {return;}
+
+    if (this.logger[level]) {
+      this.logger[level](`[HistoricalMetrics] ${message}`, meta);
+    } else {
+      console.log(`[HistoricalMetrics] [${level}] ${message}`, meta);
+    }
+  }
+}