feat: add health monitoring utility for API tracking

src/utils/health-monitor.test.ts

@@ -0,0 +1,195 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { HealthMonitor } from "./health-monitor";
+
+describe("HealthMonitor", () => {
+  let monitor: HealthMonitor;
+
+  beforeEach(() => {
+    monitor = new HealthMonitor();
+  });
+
+  describe("recordSuccess", () => {
+    it("should increment successful requests", () => {
+      monitor.recordSuccess(100);
+      const metrics = monitor.getHealthMetrics();
+
+      expect(metrics.totalRequests).toBe(1);
+      expect(metrics.successfulRequests).toBe(1);
+      expect(metrics.failedRequests).toBe(0);
+    });
+
+    it("should calculate average response time", () => {
+      monitor.recordSuccess(100);
+      monitor.recordSuccess(200);
+      monitor.recordSuccess(300);
+
+      const metrics = monitor.getHealthMetrics();
+      expect(metrics.averageResponseTime).toBe(200);
+    });
+
+    it("should update last request timestamp", () => {
+      const before = Date.now();
+      monitor.recordSuccess(50);
+      const after = Date.now();
+
+      const metrics = monitor.getHealthMetrics();
+      expect(metrics.lastRequestTimestamp).toBeGreaterThanOrEqual(before);
+      expect(metrics.lastRequestTimestamp).toBeLessThanOrEqual(after);
+    });
+  });
+
+  describe("recordFailure", () => {
+    it("should increment failed requests", () => {
+      monitor.recordFailure(new Error("Test error"));
+      const metrics = monitor.getHealthMetrics();
+
+      expect(metrics.totalRequests).toBe(1);
+      expect(metrics.successfulRequests).toBe(0);
+      expect(metrics.failedRequests).toBe(1);
+    });
+
+    it("should track error types", () => {
+      monitor.recordFailure(new Error("First error"));
+      monitor.recordFailure(new Error("Second error"));
+
+      const metrics = monitor.getHealthMetrics();
+      expect(metrics.errors).toHaveLength(1);
+      expect(metrics.errors[0].type).toBe("Error");
+      expect(metrics.errors[0].count).toBe(2);
+    });
+
+    it("should track different error types separately", () => {
+      monitor.recordFailure(new Error("Error 1"));
+      monitor.recordFailure(new TypeError("TypeError 1"));
+
+      const metrics = monitor.getHealthMetrics();
+      expect(metrics.errors).toHaveLength(2);
+
+      const errorTypes = metrics.errors.map((e) => e.type);
+      expect(errorTypes).toContain("Error");
+      expect(errorTypes).toContain("TypeError");
+    });
+  });
+
+  describe("getHealthMetrics", () => {
+    it("should return correct success rate", () => {
+      monitor.recordSuccess(100);
+      monitor.recordSuccess(100);
+      monitor.recordFailure(new Error("Test"));
+
+      const metrics = monitor.getHealthMetrics();
+      expect(metrics.successRate).toBeCloseTo(66.67, 1);
+    });
+
+    it("should return 0 success rate when no requests", () => {
+      const metrics = monitor.getHealthMetrics();
+      expect(metrics.successRate).toBe(0);
+    });
+
+    it("should return 100 success rate when all succeed", () => {
+      monitor.recordSuccess(100);
+      monitor.recordSuccess(100);
+
+      const metrics = monitor.getHealthMetrics();
+      expect(metrics.successRate).toBe(100);
+    });
+  });
+
+  describe("isHealthy", () => {
+    it("should return true when success rate is above threshold", () => {
+      monitor.recordSuccess(100);
+      monitor.recordSuccess(100);
+
+      expect(monitor.isHealthy(95)).toBe(true);
+    });
+
+    it("should return false when success rate is below threshold", () => {
+      monitor.recordSuccess(100);
+      monitor.recordFailure(new Error("Test"));
+      monitor.recordFailure(new Error("Test"));
+
+      expect(monitor.isHealthy(95)).toBe(false);
+    });
+
+    it("should return true when no requests have been made", () => {
+      expect(monitor.isHealthy()).toBe(true);
+    });
+
+    it("should use custom threshold", () => {
+      monitor.recordSuccess(100);
+      monitor.recordFailure(new Error("Test"));
+
+      expect(monitor.isHealthy(50)).toBe(true);
+      expect(monitor.isHealthy(60)).toBe(false);
+    });
+  });
+
+  describe("reset", () => {
+    it("should clear all metrics", () => {
+      monitor.recordSuccess(100);
+      monitor.recordFailure(new Error("Test"));
+      monitor.reset();
+
+      const metrics = monitor.getHealthMetrics();
+      expect(metrics.totalRequests).toBe(0);
+      expect(metrics.successfulRequests).toBe(0);
+      expect(metrics.failedRequests).toBe(0);
+      expect(metrics.errors).toHaveLength(0);
+      expect(metrics.lastRequestTimestamp).toBeNull();
+    });
+  });
+
+  describe("getHealthReport", () => {
+    it("should return formatted health report", () => {
+      monitor.recordSuccess(100);
+      monitor.recordSuccess(200);
+      monitor.recordFailure(new Error("Test error"));
+
+      const report = monitor.getHealthReport();
+      expect(report).toContain("Health Status:");
+      expect(report).toContain("Total Requests: 3");
+      expect(report).toContain("Success Rate:");
+      expect(report).toContain("Average Response Time:");
+    });
+
+    it("should show HEALTHY status when success rate is high", () => {
+      monitor.recordSuccess(100);
+      monitor.recordSuccess(100);
+
+      const report = monitor.getHealthReport();
+      expect(report).toContain("HEALTHY");
+    });
+
+    it("should show DEGRADED status when success rate is low", () => {
+      monitor.recordFailure(new Error("Test"));
+      monitor.recordFailure(new Error("Test"));
+
+      const report = monitor.getHealthReport();
+      expect(report).toContain("DEGRADED");
+    });
+
+    it("should include error details in report", () => {
+      monitor.recordFailure(new TypeError("Type error"));
+
+      const report = monitor.getHealthReport();
+      expect(report).toContain("Errors:");
+      expect(report).toContain("TypeError");
+    });
+  });
+});

src/utils/health-monitor.ts

@@ -0,0 +1,185 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Health monitoring utility for tracking API request health and performance.
+ * @public
+ */
+
+export interface HealthMetrics {
+  totalRequests: number;
+  successfulRequests: number;
+  failedRequests: number;
+  successRate: number;
+  averageResponseTime: number;
+  lastRequestTimestamp: number | null;
+  errors: ErrorSummary[];
+}
+
+export interface ErrorSummary {
+  type: string;
+  count: number;
+  lastOccurrence: number;
+  message?: string;
+}
+
+/**
+ * Monitor API health and track request metrics.
+ * Useful for debugging, monitoring, and performance analysis.
+ *
+ * @example
+ * ```typescript
+ * const monitor = new HealthMonitor();
+ *
+ * try {
+ *   const startTime = Date.now();
+ *   const result = await model.generateContent("Hello");
+ *   monitor.recordSuccess(Date.now() - startTime);
+ * } catch (error) {
+ *   monitor.recordFailure(error);
+ * }
+ *
+ * const health = monitor.getHealthMetrics();
+ * console.log(`Success rate: ${health.successRate}%`);
+ * ```
+ *
+ * @public
+ */
+export class HealthMonitor {
+  private totalRequests = 0;
+  private successfulRequests = 0;
+  private failedRequests = 0;
+  private responseTimes: number[] = [];
+  private lastRequestTimestamp: number | null = null;
+  private errorMap = new Map<string, ErrorSummary>();
+  private readonly maxResponseTimesSaved = 100;
+
+  /**
+   * Record a successful API request.
+   * @param responseTime - Response time in milliseconds
+   */
+  recordSuccess(responseTime: number): void {
+    this.totalRequests++;
+    this.successfulRequests++;
+    this.lastRequestTimestamp = Date.now();
+
+    this.responseTimes.push(responseTime);
+    if (this.responseTimes.length > this.maxResponseTimesSaved) {
+      this.responseTimes.shift();
+    }
+  }
+
+  /**
+   * Record a failed API request.
+   * @param error - The error that occurred
+   */
+  recordFailure(error: Error): void {
+    this.totalRequests++;
+    this.failedRequests++;
+    this.lastRequestTimestamp = Date.now();
+
+    const errorType = error.constructor.name;
+    const existing = this.errorMap.get(errorType);
+
+    if (existing) {
+      existing.count++;
+      existing.lastOccurrence = Date.now();
+    } else {
+      this.errorMap.set(errorType, {
+        type: errorType,
+        count: 1,
+        lastOccurrence: Date.now(),
+        message: error.message,
+      });
+    }
+  }
+
+  /**
+   * Get current health metrics.
+   * @returns Current health and performance metrics
+   */
+  getHealthMetrics(): HealthMetrics {
+    const successRate =
+      this.totalRequests > 0
+        ? (this.successfulRequests / this.totalRequests) * 100
+        : 0;
+
+    const averageResponseTime =
+      this.responseTimes.length > 0
+        ? this.responseTimes.reduce((sum, time) => sum + time, 0) /
+          this.responseTimes.length
+        : 0;
+
+    return {
+      totalRequests: this.totalRequests,
+      successfulRequests: this.successfulRequests,
+      failedRequests: this.failedRequests,
+      successRate: Math.round(successRate * 100) / 100,
+      averageResponseTime: Math.round(averageResponseTime * 100) / 100,
+      lastRequestTimestamp: this.lastRequestTimestamp,
+      errors: Array.from(this.errorMap.values()),
+    };
+  }
+
+  /**
+   * Check if the service is healthy based on success rate threshold.
+   * @param threshold - Minimum success rate percentage (default: 95)
+   * @returns true if success rate is above threshold
+   */
+  isHealthy(threshold: number = 95): boolean {
+    if (this.totalRequests === 0) {
+      return true; // No requests yet, consider healthy
+    }
+    const metrics = this.getHealthMetrics();
+    return metrics.successRate >= threshold;
+  }
+
+  /**
+   * Reset all metrics to initial state.
+   */
+  reset(): void {
+    this.totalRequests = 0;
+    this.successfulRequests = 0;
+    this.failedRequests = 0;
+    this.responseTimes = [];
+    this.lastRequestTimestamp = null;
+    this.errorMap.clear();
+  }
+
+  /**
+   * Get a human-readable health status report.
+   * @returns Formatted health status string
+   */
+  getHealthReport(): string {
+    const metrics = this.getHealthMetrics();
+    const status = this.isHealthy() ? "HEALTHY" : "DEGRADED";
+
+    let report = `Health Status: ${status}\n`;
+    report += `Total Requests: ${metrics.totalRequests}\n`;
+    report += `Success Rate: ${metrics.successRate}%\n`;
+    report += `Average Response Time: ${metrics.averageResponseTime}ms\n`;
+
+    if (metrics.errors.length > 0) {
+      report += `\nErrors:\n`;
+      metrics.errors.forEach((error) => {
+        report += `  - ${error.type}: ${error.count} occurrence(s)\n`;
+      });
+    }
+
+    return report;
+  }
+}