@gguf/coder 0.2.9 → 0.3.1

package/source/utils/logging/health-monitor/core/health-monitor.ts

@@ -0,0 +1,344 @@
+/**
+ * Main health monitoring class
+ */
+
+import {loadavg} from 'os';
+import {
+	COOLDOWN_ALERT_MS,
+	DURATION_AVERAGE_CRITICAL_MS,
+	DURATION_AVERAGE_WARNING_MS,
+	DURATION_REQUEST_CRITICAL_MS,
+	DURATION_REQUEST_WARNING_MS,
+	HEAP_USAGE_CRITICAL_THRESHOLD,
+	HEAP_USAGE_WARNING_THRESHOLD,
+	INTERVAL_HEALTH_CHECK_MS,
+	TIMEOUT_HEALTH_CHECK_MS,
+} from '@/constants';
+import {generateCorrelationId} from '../../correlation.js';
+import {globalLogStorage} from '../../log-query/index.js';
+import {loggerProvider} from '../../logger-provider.js';
+import {globalPerformanceMonitor} from '../../performance.js';
+import {globalRequestTracker} from '../../request-tracker.js';
+
+const getLogger = () => loggerProvider.getLogger();
+import {sendAlert} from '../alerts/alert-manager.js';
+import type {
+	HealthCheckConfig,
+	HealthCheckResult,
+	SystemMetrics,
+} from '../types.js';
+import {runHealthCheck} from './health-check-runner.js';
+
+// Get logger instance directly to avoid circular dependencies
+const logger = getLogger();
+
+/**
+ * Health monitoring system
+ */
+export class HealthMonitor {
+	private config: HealthCheckConfig;
+	private isRunning: boolean = false;
+	private intervalId?: NodeJS.Timeout;
+	private lastCheck?: HealthCheckResult;
+	private lastAlert?: number;
+	private correlationId: string;
+
+	constructor(config?: Partial<HealthCheckConfig>) {
+		this.correlationId = generateCorrelationId();
+		this.config = {
+			enabled: true,
+			interval: INTERVAL_HEALTH_CHECK_MS,
+			timeout: TIMEOUT_HEALTH_CHECK_MS,
+			thresholds: {
+				memory: {
+					heapUsageWarning: HEAP_USAGE_WARNING_THRESHOLD,
+					heapUsageCritical: HEAP_USAGE_CRITICAL_THRESHOLD,
+					externalWarning: 256,
+					externalCritical: 512,
+				},
+				performance: {
+					averageDurationWarning: DURATION_AVERAGE_WARNING_MS,
+					averageDurationCritical: DURATION_AVERAGE_CRITICAL_MS,
+					errorRateWarning: 0.05,
+					errorRateCritical: 0.1,
+				},
+				logging: {
+					logRateWarning: 100,
+					logRateCritical: 500,
+					errorRateWarning: 0.02,
+					errorRateCritical: 0.05,
+				},
+				requests: {
+					durationWarning: DURATION_REQUEST_WARNING_MS,
+					durationCritical: DURATION_REQUEST_CRITICAL_MS,
+					errorRateWarning: 0.05,
+					errorRateCritical: 0.1,
+				},
+			},
+			alerts: {
+				enabled: true,
+				channels: ['console'],
+				cooldown: COOLDOWN_ALERT_MS,
+			},
+			...config,
+		};
+	}
+
+	/**
+	 * Start health monitoring
+	 */
+	start(): void {
+		try {
+			if (this.isRunning) {
+				logger.warn('Health monitoring already running', {
+					correlationId: this.correlationId,
+					source: 'health-monitor',
+				});
+				return;
+			}
+
+			this.isRunning = true;
+
+			// Run initial check
+			try {
+				void this.runHealthCheck();
+			} catch (error) {
+				logger.error('Failed to run initial health check', {
+					error: error instanceof Error ? error.message : error,
+					correlationId: this.correlationId,
+					source: 'health-monitor',
+				});
+				// Continue starting monitoring even if initial check fails
+			}
+
+			// Schedule regular checks
+			try {
+				this.intervalId = setInterval(() => {
+					try {
+						void this.runHealthCheck();
+					} catch (error) {
+						logger.error('Failed to run scheduled health check', {
+							error: error instanceof Error ? error.message : error,
+							correlationId: this.correlationId,
+							source: 'health-monitor',
+						});
+					}
+				}, this.config.interval);
+			} catch (error) {
+				logger.error('Failed to schedule health monitoring', {
+					error: error instanceof Error ? error.message : error,
+					correlationId: this.correlationId,
+					source: 'health-monitor',
+				});
+				this.isRunning = false;
+				return;
+			}
+
+			logger.info('Health monitoring started', {
+				interval: `${this.config.interval}ms`,
+				timeout: `${this.config.timeout}ms`,
+				correlationId: this.correlationId,
+				source: 'health-monitor',
+			});
+		} catch (error) {
+			logger.error('Critical error starting health monitoring', {
+				error: error instanceof Error ? error.message : error,
+				correlationId: this.correlationId,
+				source: 'health-monitor',
+			});
+			this.isRunning = false;
+		}
+	}
+
+	/**
+	 * Stop health monitoring
+	 */
+	stop(): void {
+		try {
+			if (!this.isRunning) {
+				logger.debug('Health monitoring not running', {
+					correlationId: this.correlationId,
+					source: 'health-monitor',
+				});
+				return;
+			}
+
+			this.isRunning = false;
+
+			try {
+				if (this.intervalId) {
+					clearInterval(this.intervalId);
+					this.intervalId = undefined;
+				}
+			} catch (error) {
+				logger.error('Failed to clear health monitoring interval', {
+					error: error instanceof Error ? error.message : error,
+					correlationId: this.correlationId,
+					source: 'health-monitor',
+				});
+				// Continue with cleanup even if interval clearing fails
+			}
+
+			logger.info('Health monitoring stopped', {
+				correlationId: this.correlationId,
+				source: 'health-monitor',
+			});
+		} catch (error) {
+			logger.error('Critical error stopping health monitoring', {
+				error: error instanceof Error ? error.message : error,
+				correlationId: this.correlationId,
+				source: 'health-monitor',
+			});
+			// Ensure we don't leave the system in a bad state
+			this.isRunning = false;
+			if (this.intervalId) {
+				try {
+					clearInterval(this.intervalId);
+					this.intervalId = undefined;
+				} catch (cleanupError) {
+					// Final fallback - log but don't rethrow
+					logger.error(
+						'Failed to cleanup health monitoring interval during error recovery',
+						{
+							error:
+								cleanupError instanceof Error
+									? cleanupError.message
+									: cleanupError,
+							correlationId: this.correlationId,
+							source: 'health-monitor',
+						},
+					);
+				}
+			}
+		}
+	}
+
+	/**
+	 * Run a comprehensive health check
+	 */
+	async runHealthCheck(): Promise<HealthCheckResult> {
+		const result = await runHealthCheck(this.config, this.correlationId);
+		this.lastCheck = result;
+
+		// Check if alerts should be sent
+		if (
+			this.config.alerts.enabled &&
+			(result.status === 'unhealthy' || result.status === 'degraded')
+		) {
+			await sendAlert(result, this.config, this.lastAlert, this.correlationId);
+			this.lastAlert = Date.now();
+		}
+
+		return result;
+	}
+
+	/**
+	 * Get current system metrics
+	 */
+	getSystemMetrics(): SystemMetrics {
+		const _now = Date.now();
+		const memory = process.memoryUsage();
+		const cpuUsage = process.cpuUsage();
+		const requestStats = globalRequestTracker.getStats();
+		const logStats = globalLogStorage.getEntryCount();
+		const perfStats = globalPerformanceMonitor.getAllStats();
+
+		// Calculate rates (approximate based on current state)
+		const logRate = logStats / (process.uptime() / 60); // logs per minute
+		const errorRate = requestStats.errorRate;
+		const requestsPerSecond = requestStats.totalRequests / process.uptime();
+
+		// Calculate average operation duration from performance stats
+		const allPerfStats = Object.values(perfStats).filter(Boolean);
+		const averageDuration =
+			allPerfStats.length > 0
+				? allPerfStats.reduce(
+						(sum, stat) => sum + (stat?.avgDuration || 0),
+						0,
+					) / allPerfStats.length
+				: 0;
+
+		return {
+			timestamp: new Date().toISOString(),
+			memory: {
+				heapUsed: memory.heapUsed,
+				heapTotal: memory.heapTotal,
+				external: memory.external,
+				rss: memory.rss,
+				heapUsagePercent: memory.heapUsed / memory.heapTotal,
+			},
+			cpu: {
+				usage: (cpuUsage.user + cpuUsage.system) / 1000000, // Convert to milliseconds
+				loadAverage: loadavg(),
+			},
+			process: {
+				uptime: process.uptime(),
+				pid: process.pid,
+				nodeVersion: process.version,
+				platform: process.platform,
+				arch: process.arch,
+			},
+			logging: {
+				totalLogEntries: logStats,
+				logRate,
+				errorRate,
+				averageLogSize: 256, // Estimated
+			},
+			requests: {
+				totalRequests: requestStats.totalRequests,
+				activeRequests: globalRequestTracker.getActiveRequests().length,
+				averageDuration: requestStats.averageDuration,
+				errorRate: requestStats.errorRate,
+				requestsPerSecond,
+			},
+			performance: {
+				operationCount: allPerfStats.reduce(
+					(sum, stat) => sum + (stat?.count || 0),
+					0,
+				),
+				averageDuration,
+				slowOperations: 0, // Would need tracking over time
+				memoryIntensiveOps: 0, // Would need tracking over time
+			},
+		};
+	}
+
+	/**
+	 * Get last health check result
+	 */
+	getLastHealthCheck(): HealthCheckResult | undefined {
+		return this.lastCheck;
+	}
+
+	/**
+	 * Check if monitoring is running
+	 */
+	isActive(): boolean {
+		return this.isRunning;
+	}
+
+	/**
+	 * Update health check configuration
+	 */
+	updateConfig(config: Partial<HealthCheckConfig>): void {
+		this.config = {...this.config, ...config};
+
+		logger.info('Health monitor configuration updated', {
+			enabled: this.config.enabled,
+			interval: `${this.config.interval}ms`,
+			correlationId: this.correlationId,
+			source: 'health-monitor',
+		});
+
+		// Restart monitoring if running
+		if (this.isRunning) {
+			this.stop();
+			this.start();
+		}
+	}
+}
+
+/**
+ * Global health monitor instance
+ */
+export const globalHealthMonitor = new HealthMonitor();

package/source/utils/logging/health-monitor/core/scoring.spec.ts

@@ -0,0 +1,65 @@
+/**
+ * Scoring tests
+ */
+
+import test from 'ava';
+import type {HealthCheck} from '../types.js';
+import {calculateScore, generateRecommendations} from './scoring.js';
+
+test('calculateScore returns 0 for fail status', t => {
+	const score = calculateScore('fail', 0, 0.5, 0.8);
+	t.is(score, 0);
+});
+
+test('calculateScore returns 100 for pass status', t => {
+	const score = calculateScore('pass', 0, 0.5, 0.8);
+	t.is(score, 100);
+});
+
+test('calculateScore returns value between 50-80 for warn status', t => {
+	const score = calculateScore('warn', 0.6, 0.5, 0.8);
+	t.true(score >= 50 && score <= 80);
+});
+
+test('generateRecommendations returns array for healthy status', t => {
+	const checks: HealthCheck[] = [
+		{
+			name: 'memory-usage',
+			status: 'pass',
+			score: 100,
+			duration: 10,
+		},
+	];
+	const recommendations = generateRecommendations(checks, 'healthy');
+	t.true(Array.isArray(recommendations));
+});
+
+test('generateRecommendations includes critical message for unhealthy status', t => {
+	const checks: HealthCheck[] = [
+		{
+			name: 'memory-usage',
+			status: 'fail',
+			score: 0,
+			duration: 10,
+		},
+	];
+	const recommendations = generateRecommendations(checks, 'unhealthy');
+	t.true(recommendations.length > 0);
+	t.true(
+		recommendations.some(r => r.includes('critical') || r.includes('unhealthy')),
+	);
+});
+
+test('generateRecommendations includes degraded message for degraded status', t => {
+	const checks: HealthCheck[] = [
+		{
+			name: 'memory-usage',
+			status: 'warn',
+			score: 60,
+			duration: 10,
+		},
+	];
+	const recommendations = generateRecommendations(checks, 'degraded');
+	t.true(recommendations.length > 0);
+	t.true(recommendations.some(r => r.includes('degraded')));
+});

package/source/utils/logging/health-monitor/core/scoring.ts

@@ -0,0 +1,91 @@
+/**
+ * Health scoring and recommendation logic
+ */
+
+import type {HealthCheck} from '../types.js';
+
+/**
+ * Calculate score based on status and value
+ */
+export function calculateScore(
+	status: 'pass' | 'fail' | 'warn',
+	value: number,
+	warningThreshold: number,
+	criticalThreshold: number,
+): number {
+	if (status === 'fail') return 0;
+	if (status === 'pass') return 100;
+	if (status === 'warn') {
+		// Calculate score based on how far from critical threshold
+		const range = criticalThreshold - warningThreshold;
+		const distance = criticalThreshold - value;
+		return Math.max(50, Math.min(80, 50 + (distance / range) * 30));
+	}
+	return 50; // default for unknown status
+}
+
+/**
+ * Generate recommendations based on check results
+ */
+export function generateRecommendations(
+	checks: HealthCheck[],
+	status: 'healthy' | 'degraded' | 'unhealthy',
+): string[] {
+	const recommendations: string[] = [];
+
+	for (const check of checks) {
+		switch (check.name) {
+			case 'memory-usage':
+				if (check.status === 'fail') {
+					recommendations.push(
+						'Immediate memory optimization required - consider increasing memory limits or fixing memory leaks',
+					);
+				} else if (check.status === 'warn') {
+					recommendations.push(
+						'Monitor memory usage and optimize memory-intensive operations',
+					);
+				}
+				break;
+
+			case 'logging-system':
+				if (check.status === 'fail') {
+					recommendations.push(
+						'Fix logging system initialization - check logger configuration',
+					);
+				}
+				break;
+
+			case 'request-tracking':
+				if (check.status === 'fail') {
+					recommendations.push(
+						'Address high request error rates or slow request processing',
+					);
+				} else if (check.status === 'warn') {
+					recommendations.push(
+						'Monitor request performance and optimize slow endpoints',
+					);
+				}
+				break;
+
+			case 'performance-monitoring':
+				if (check.status === 'warn') {
+					recommendations.push(
+						'Ensure performance monitoring is integrated into critical operations',
+					);
+				}
+				break;
+		}
+	}
+
+	if (status === 'unhealthy') {
+		recommendations.push(
+			'System health is critical - immediate attention required',
+		);
+	} else if (status === 'degraded') {
+		recommendations.push(
+			'System performance is degraded - review recommendations and optimize',
+		);
+	}
+
+	return recommendations;
+}

package/source/utils/logging/health-monitor/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Health monitoring system
+ * Provides comprehensive health metrics and monitoring capabilities
+ */
+
+// Re-export types
+export type {
+	HealthCheck,
+	HealthCheckConfig,
+	HealthCheckResult,
+	SystemMetrics,
+} from './types.js';
+
+// Re-export the only public API - healthChecks helper functions
+export {healthChecks} from './instances.js';

package/source/utils/logging/health-monitor/instances.ts

@@ -0,0 +1,48 @@
+/**
+ * Global instances for health monitoring
+ */
+
+import {globalHealthMonitor} from './core/health-monitor.js';
+
+/**
+ * Quick health check functions
+ */
+export const healthChecks = {
+	/**
+	 * Quick health check - returns status only
+	 */
+	quick: async (): Promise<'healthy' | 'degraded' | 'unhealthy'> => {
+		const result = await globalHealthMonitor.runHealthCheck();
+		return result.status;
+	},
+
+	/**
+	 * Full health check with details
+	 */
+	full: () => globalHealthMonitor.runHealthCheck(),
+
+	/**
+	 * System metrics snapshot
+	 */
+	metrics: () => globalHealthMonitor.getSystemMetrics(),
+
+	/**
+	 * Check if system is ready
+	 */
+	ready: async (): Promise<boolean> => {
+		const result = await globalHealthMonitor.runHealthCheck();
+		return result.status === 'healthy';
+	},
+
+	/**
+	 * Check if system is alive (basic check)
+	 */
+	alive: (): boolean => {
+		try {
+			const metrics = globalHealthMonitor.getSystemMetrics();
+			return metrics.process.uptime > 0;
+		} catch {
+			return false;
+		}
+	},
+};

package/source/utils/logging/health-monitor/middleware/http-middleware.spec.ts

@@ -0,0 +1,141 @@
+/**
+ * HTTP middleware tests
+ */
+
+import test from 'ava';
+import {healthCheckMiddleware} from './http-middleware.js';
+
+const createMockHealthChecks = () => ({
+	full: async () => ({
+		status: 'healthy' as const,
+		timestamp: new Date().toISOString(),
+		score: 100,
+		checks: [
+			{
+				name: 'test-check',
+				status: 'pass' as const,
+				score: 100,
+			},
+		],
+	}),
+	ready: async () => true,
+	alive: () => true,
+	metrics: () => ({test: 'metrics'}),
+});
+
+test('healthCheckMiddleware calls next for non-health paths', async t => {
+	const middleware = healthCheckMiddleware(createMockHealthChecks());
+	let nextCalled = false;
+
+	const req = {path: '/api/test'};
+	const res = {
+		status: (code: number) => ({
+			json: (_data: unknown) => {},
+		}),
+		json: (_data: unknown) => {},
+	};
+	const next = () => {
+		nextCalled = true;
+	};
+
+	await middleware(req, res, next);
+	t.true(nextCalled);
+});
+
+test('healthCheckMiddleware handles /health path', async t => {
+	const middleware = healthCheckMiddleware(createMockHealthChecks());
+	let responseSent = false;
+	let statusCode = 0;
+
+	const req = {path: '/health'};
+	const res = {
+		status: (code: number) => {
+			statusCode = code;
+			return {
+				json: (_data: unknown) => {
+					responseSent = true;
+				},
+			};
+		},
+		json: (_data: unknown) => {
+			responseSent = true;
+		},
+	};
+	const next = () => {};
+
+	await middleware(req, res, next);
+	t.true(responseSent);
+	t.is(statusCode, 200);
+});
+
+test('healthCheckMiddleware handles /health/ready path', async t => {
+	const middleware = healthCheckMiddleware(createMockHealthChecks());
+	let responseSent = false;
+	let statusCode = 0;
+
+	const req = {path: '/health/ready'};
+	const res = {
+		status: (code: number) => {
+			statusCode = code;
+			return {
+				json: (_data: unknown) => {
+					responseSent = true;
+				},
+			};
+		},
+		json: (_data: unknown) => {
+			responseSent = true;
+		},
+	};
+	const next = () => {};
+
+	await middleware(req, res, next);
+	t.true(responseSent);
+	t.is(statusCode, 200);
+});
+
+test('healthCheckMiddleware handles /health/live path', async t => {
+	const middleware = healthCheckMiddleware(createMockHealthChecks());
+	let responseSent = false;
+
+	const req = {path: '/health/live'};
+	const res = {
+		status: (_code: number) => {
+			return {
+				json: (_data: unknown) => {
+					responseSent = true;
+				},
+			};
+		},
+		json: (_data: unknown) => {
+			responseSent = true;
+		},
+	};
+	const next = () => {};
+
+	await middleware(req, res, next);
+	t.true(responseSent);
+});
+
+test('healthCheckMiddleware handles /metrics path', async t => {
+	const middleware = healthCheckMiddleware(createMockHealthChecks());
+	let responseSent = false;
+
+	const req = {path: '/metrics'};
+	const res = {
+		status: (_code: number) => {
+			return {
+				json: (_data: unknown) => {
+					responseSent = true;
+				},
+			};
+		},
+		json: (_data: unknown) => {
+			responseSent = true;
+		},
+	};
+	const next = () => {};
+
+	await middleware(req, res, next);
+	t.true(responseSent);
+});