@expressots/core 3.0.0 → 4.0.0-preview.1

package/lib/cjs/provider/logger/logger.grouping.js

@@ -0,0 +1,319 @@
+"use strict";
+/**
+ * @file logger.grouping.ts
+ * @description Log grouping and noise reduction system
+ * @module @expressots/core/provider/logger
+ *
+ * Features:
+ * - String similarity detection for grouping similar logs
+ * - Time window grouping for repeated logs
+ * - Configurable thresholds and windows
+ * - Grouped output formatting
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LogGroupingManager = void 0;
+exports.getDefaultGroupingConfig = getDefaultGroupingConfig;
+exports.calculateSimilarity = calculateSimilarity;
+/**
+ * Default grouping configuration.
+ * @returns Default config
+ * @public API
+ */
+function getDefaultGroupingConfig() {
+    const isDevelopment = process.env.NODE_ENV !== "production";
+    return {
+        enabled: isDevelopment, // Enabled in dev, disabled in prod by default
+        similarityThreshold: 0.8, // 80% similarity
+        timeWindow: 5000, // 5 seconds
+        minOccurrences: 3, // Group if 3+ occurrences
+        considerContext: true, // Consider context when grouping
+        maxGroups: 100, // Track up to 100 groups
+    };
+}
+/**
+ * Calculate Levenshtein distance between two strings.
+ * Used for string similarity calculation.
+ * @param str1 - First string
+ * @param str2 - Second string
+ * @returns Edit distance
+ */
+function levenshteinDistance(str1, str2) {
+    const len1 = str1.length;
+    const len2 = str2.length;
+    if (len1 === 0)
+        return len2;
+    if (len2 === 0)
+        return len1;
+    const matrix = [];
+    // Initialize matrix
+    for (let i = 0; i <= len1; i++) {
+        matrix[i] = [i];
+    }
+    for (let j = 0; j <= len2; j++) {
+        matrix[0][j] = j;
+    }
+    // Fill matrix
+    for (let i = 1; i <= len1; i++) {
+        for (let j = 1; j <= len2; j++) {
+            const cost = str1[i - 1] === str2[j - 1] ? 0 : 1;
+            matrix[i][j] = Math.min(matrix[i - 1][j] + 1, // deletion
+            matrix[i][j - 1] + 1, // insertion
+            matrix[i - 1][j - 1] + cost);
+        }
+    }
+    return matrix[len1][len2];
+}
+/**
+ * Calculate similarity between two strings (0-1).
+ * @param str1 - First string
+ * @param str2 - Second string
+ * @returns Similarity score (0 = completely different, 1 = identical)
+ * @public API
+ */
+function calculateSimilarity(str1, str2) {
+    if (str1 === str2)
+        return 1.0;
+    if (str1.length === 0 || str2.length === 0)
+        return 0.0;
+    const maxLength = Math.max(str1.length, str2.length);
+    const distance = levenshteinDistance(str1, str2);
+    return 1.0 - distance / maxLength;
+}
+/**
+ * Normalize log message for grouping.
+ * Removes variable parts like IDs, timestamps, etc.
+ * @param message - Log message
+ * @returns Normalized message
+ */
+function normalizeMessage(message) {
+    // Remove common variable patterns:
+    // - UUIDs: 8-4-4-4-12 hex pattern
+    // - Numbers: standalone numbers
+    // - Timestamps: ISO dates, Unix timestamps
+    // - IDs: common ID patterns
+    let normalized = message;
+    // Remove UUIDs
+    normalized = normalized.replace(/\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi, "<uuid>");
+    // Remove standalone numbers (but keep numbers in context)
+    normalized = normalized.replace(/\b\d+\b/g, "<num>");
+    // Remove ISO timestamps
+    normalized = normalized.replace(/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z?/g, "<timestamp>");
+    // Remove Unix timestamps (10 or 13 digits)
+    normalized = normalized.replace(/\b\d{10,13}\b/g, "<timestamp>");
+    // Remove common ID patterns
+    normalized = normalized.replace(/\bid[:\s=]+(\w+)/gi, "id=<id>");
+    normalized = normalized.replace(/\buser[:\s=]+(\w+)/gi, "user=<id>");
+    return normalized.trim();
+}
+/**
+ * Create a group key for a log entry.
+ * @param entry - Log entry
+ * @param considerContext - Whether to include context in key
+ * @returns Group key
+ */
+function createGroupKey(entry, considerContext) {
+    const normalizedMessage = normalizeMessage(entry.message);
+    const context = considerContext && entry.context ? `[${entry.context}]` : "";
+    const level = entry.level.toString();
+    return `${level}:${context}:${normalizedMessage}`;
+}
+/**
+ * Log grouping manager.
+ * Groups similar logs within time windows to reduce noise.
+ * @public API
+ */
+class LogGroupingManager {
+    constructor(config) {
+        this.groups = new Map();
+        this.lastCleanup = Date.now();
+        this.cleanupInterval = 30000; // Clean up every 30 seconds
+        this.config = { ...getDefaultGroupingConfig(), ...config };
+    }
+    /**
+     * Update grouping configuration.
+     * @param config - Partial configuration to merge
+     */
+    configure(config) {
+        this.config = { ...this.config, ...config };
+    }
+    /**
+     * Process a log entry and determine if it should be grouped.
+     * @param entry - Log entry to process
+     * @returns Grouped entry if grouped, or original entry if not grouped
+     */
+    processEntry(entry) {
+        if (!this.config.enabled) {
+            return entry;
+        }
+        // Clean up old groups periodically
+        this.cleanupOldGroups();
+        const groupKey = createGroupKey(entry, this.config.considerContext);
+        const now = Date.now();
+        // Check if we have an existing group
+        const existingGroup = this.groups.get(groupKey);
+        if (existingGroup) {
+            // Check if within time window
+            const timeSinceLast = now - existingGroup.lastOccurrence.getTime();
+            if (timeSinceLast <= this.config.timeWindow) {
+                // Still within window, add to group
+                existingGroup.count++;
+                existingGroup.lastOccurrence = entry.timestamp;
+                existingGroup.entries.push(entry);
+                // Return grouped entry if we've reached minimum occurrences
+                if (existingGroup.count >= this.config.minOccurrences) {
+                    return existingGroup;
+                }
+                // Not enough occurrences yet, return original entry
+                return entry;
+            }
+            else {
+                // Time window expired, flush the group and start new one
+                const flushedGroup = { ...existingGroup };
+                this.groups.delete(groupKey);
+                this.createNewGroup(groupKey, entry);
+                return flushedGroup.count >= this.config.minOccurrences
+                    ? flushedGroup
+                    : entry;
+            }
+        }
+        // Check for similar groups using similarity algorithm
+        const similarGroup = this.findSimilarGroup(entry);
+        if (similarGroup) {
+            const timeSinceLast = now - similarGroup.lastOccurrence.getTime();
+            if (timeSinceLast <= this.config.timeWindow) {
+                // Similar and within time window, add to group
+                similarGroup.count++;
+                similarGroup.lastOccurrence = entry.timestamp;
+                similarGroup.entries.push(entry);
+                // Update group key to use the new entry's key
+                this.groups.delete(similarGroup.groupKey);
+                this.groups.set(groupKey, similarGroup);
+                similarGroup.groupKey = groupKey;
+                if (similarGroup.count >= this.config.minOccurrences) {
+                    return similarGroup;
+                }
+                return entry;
+            }
+        }
+        // No matching group, create new one
+        this.createNewGroup(groupKey, entry);
+        return entry;
+    }
+    /**
+     * Find a similar group using string similarity.
+     * @param entry - Log entry to match
+     * @returns Similar group if found, null otherwise
+     */
+    findSimilarGroup(entry) {
+        const normalizedMessage = normalizeMessage(entry.message);
+        let bestMatch = null;
+        let bestSimilarity = 0;
+        for (const group of this.groups.values()) {
+            const groupNormalized = normalizeMessage(group.representative.message);
+            const similarity = calculateSimilarity(normalizedMessage, groupNormalized);
+            // Also check context similarity if enabled
+            if (this.config.considerContext) {
+                const contextMatch = entry.context === group.representative.context ? 1.0 : 0.0;
+                const combinedSimilarity = similarity * 0.8 + contextMatch * 0.2;
+                if (combinedSimilarity >= this.config.similarityThreshold &&
+                    combinedSimilarity > bestSimilarity) {
+                    bestSimilarity = combinedSimilarity;
+                    bestMatch = group;
+                }
+            }
+            else {
+                if (similarity >= this.config.similarityThreshold &&
+                    similarity > bestSimilarity) {
+                    bestSimilarity = similarity;
+                    bestMatch = group;
+                }
+            }
+        }
+        return bestMatch;
+    }
+    /**
+     * Create a new group for a log entry.
+     * @param groupKey - Group key
+     * @param entry - First log entry in group
+     */
+    createNewGroup(groupKey, entry) {
+        // Enforce max groups limit
+        if (this.groups.size >= this.config.maxGroups) {
+            // Remove oldest group
+            let oldestKey = null;
+            let oldestTime = Date.now();
+            for (const [key, group] of this.groups.entries()) {
+                if (group.firstOccurrence.getTime() < oldestTime) {
+                    oldestTime = group.firstOccurrence.getTime();
+                    oldestKey = key;
+                }
+            }
+            if (oldestKey) {
+                this.groups.delete(oldestKey);
+            }
+        }
+        const groupedEntry = {
+            representative: entry,
+            count: 1,
+            firstOccurrence: entry.timestamp,
+            lastOccurrence: entry.timestamp,
+            entries: [entry],
+            groupKey,
+        };
+        this.groups.set(groupKey, groupedEntry);
+    }
+    /**
+     * Clean up groups that are outside the time window.
+     */
+    cleanupOldGroups() {
+        const now = Date.now();
+        if (now - this.lastCleanup < this.cleanupInterval) {
+            return;
+        }
+        this.lastCleanup = now;
+        for (const [key, group] of this.groups.entries()) {
+            const timeSinceLast = now - group.lastOccurrence.getTime();
+            if (timeSinceLast > this.config.timeWindow * 2) {
+                // Remove groups that haven't been updated in 2x the time window
+                this.groups.delete(key);
+            }
+        }
+    }
+    /**
+     * Flush all pending groups.
+     * Useful when shutting down or switching modes.
+     * @returns Array of grouped entries that should be logged
+     */
+    flush() {
+        const groupsToFlush = [];
+        for (const group of this.groups.values()) {
+            if (group.count >= this.config.minOccurrences) {
+                groupsToFlush.push(group);
+            }
+        }
+        this.groups.clear();
+        return groupsToFlush;
+    }
+    /**
+     * Reset all groups.
+     */
+    reset() {
+        this.groups.clear();
+    }
+    /**
+     * Get current group statistics.
+     * @returns Statistics about current groups
+     */
+    getStats() {
+        return {
+            totalGroups: this.groups.size,
+            groups: Array.from(this.groups.values()).map((group) => ({
+                key: group.groupKey,
+                count: group.count,
+                firstOccurrence: group.firstOccurrence,
+                lastOccurrence: group.lastOccurrence,
+            })),
+        };
+    }
+}
+exports.LogGroupingManager = LogGroupingManager;

package/lib/cjs/provider/logger/logger.health.js

@@ -0,0 +1,295 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HealthMonitor = void 0;
+exports.getDefaultHealthConfig = getDefaultHealthConfig;
+exports.formatUptime = formatUptime;
+exports.collectHealthStatus = collectHealthStatus;
+const logger_metrics_js_1 = require("./logger.metrics.js");
+/**
+ * Get default health configuration.
+ * @param environment - Current environment
+ * @returns Default health config
+ * @public API
+ */
+function getDefaultHealthConfig(environment) {
+    const isDev = environment === "development" || !environment;
+    return {
+        enabled: !isDev, // Enabled in production by default
+        interval: 60000, // 60 seconds
+        memoryThreshold: 80, // 80%
+        cpuThreshold: 90, // 90%
+        alertsEnabled: true,
+        logLevel: "info",
+        alertLogLevel: "warn",
+    };
+}
+/**
+ * Format uptime as human-readable string.
+ * @param ms - Milliseconds
+ * @returns Formatted string (e.g., "2h 30m 15s")
+ * @public API
+ */
+function formatUptime(ms) {
+    const seconds = Math.floor(ms / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    const days = Math.floor(hours / 24);
+    if (days > 0) {
+        return `${days}d ${hours % 24}h ${minutes % 60}m`;
+    }
+    if (hours > 0) {
+        return `${hours}h ${minutes % 60}m ${seconds % 60}s`;
+    }
+    if (minutes > 0) {
+        return `${minutes}m ${seconds % 60}s`;
+    }
+    return `${seconds}s`;
+}
+/**
+ * Collect current health status.
+ * @param serviceChecks - Optional service check functions
+ * @returns Health status
+ * @public API
+ */
+async function collectHealthStatus(serviceChecks) {
+    const uptime = process.uptime() * 1000; // Convert to milliseconds
+    const memory = process.memoryUsage();
+    const memoryUsage = memory.heapUsed;
+    const memoryTotal = memory.heapTotal;
+    const memoryUsagePercent = (memoryUsage / memoryTotal) * 100;
+    // CPU usage is calculated by HealthMonitor over time (requires sampling interval)
+    // Real CPU percentage requires measuring over an interval, so it's undefined here
+    const cpuUsagePercent = undefined; // Will be calculated by HealthMonitor over time
+    // Collect external service statuses
+    const services = {};
+    if (serviceChecks && serviceChecks.length > 0) {
+        for (const check of serviceChecks) {
+            try {
+                const status = await check();
+                services[status.name] = status;
+            }
+            catch (error) {
+                // If service check fails, mark as unhealthy
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                services[errorMessage] = {
+                    name: errorMessage,
+                    status: "unhealthy",
+                    error: errorMessage,
+                    lastChecked: Date.now(),
+                };
+            }
+        }
+    }
+    // Determine overall status based on thresholds and services
+    let status = "healthy";
+    if (memoryUsagePercent > 90) {
+        status = "unhealthy";
+    }
+    else if (memoryUsagePercent > 80) {
+        status = "degraded";
+    }
+    // Check service statuses
+    if (Object.keys(services).length > 0) {
+        const unhealthyServices = Object.values(services).filter((s) => s.status === "unhealthy");
+        if (unhealthyServices.length > 0) {
+            status = "unhealthy";
+        }
+        else if (Object.values(services).some((s) => s.status === "degraded")) {
+            status = status === "unhealthy" ? "unhealthy" : "degraded";
+        }
+    }
+    return {
+        status,
+        uptime,
+        uptimeFormatted: formatUptime(uptime),
+        memoryUsage,
+        memoryUsageFormatted: (0, logger_metrics_js_1.formatMemory)(memoryUsage),
+        memoryUsagePercent: Math.round(memoryUsagePercent * 100) / 100, // Round to 2 decimals
+        cpuUsage: cpuUsagePercent,
+        services: Object.keys(services).length > 0 ? services : undefined,
+        timestamp: Date.now(),
+    };
+}
+/**
+ * Health monitor for periodic health checks and alerts.
+ * @public API
+ */
+class HealthMonitor {
+    /**
+     * Create a new health monitor.
+     * @param logger - Logger instance
+     * @param config - Health configuration
+     */
+    constructor(logger, config = {}) {
+        this.intervalId = null;
+        this.lastCpuUsage = null;
+        this.lastCpuCheck = 0;
+        this.logger = logger;
+        const environment = process.env.NODE_ENV;
+        const defaults = getDefaultHealthConfig(environment);
+        this.config = { ...defaults, ...config };
+        this.startTime = Date.now();
+        this.lastCpuCheck = Date.now();
+        this.lastCpuUsage = process.cpuUsage();
+    }
+    /**
+     * Start periodic health monitoring.
+     */
+    start() {
+        if (!this.config.enabled) {
+            return;
+        }
+        if (this.intervalId) {
+            this.stop();
+        }
+        // Initial health check
+        this.checkHealth();
+        // Set up periodic checks
+        this.intervalId = setInterval(() => {
+            this.checkHealth();
+        }, this.config.interval);
+    }
+    /**
+     * Stop periodic health monitoring.
+     */
+    stop() {
+        if (this.intervalId) {
+            clearInterval(this.intervalId);
+            this.intervalId = null;
+        }
+    }
+    /**
+     * Perform a health check and log results.
+     */
+    async checkHealth() {
+        try {
+            const health = await collectHealthStatus(this.config.serviceChecks);
+            // Calculate CPU usage over the interval
+            const now = Date.now();
+            const timeDelta = now - this.lastCpuCheck;
+            // Need at least 100ms interval for accurate CPU measurement
+            if (timeDelta >= 100 && this.lastCpuUsage) {
+                const currentCpuUsage = process.cpuUsage();
+                const cpuDelta = {
+                    user: currentCpuUsage.user - this.lastCpuUsage.user,
+                    system: currentCpuUsage.system - this.lastCpuUsage.system,
+                };
+                // Convert microseconds to milliseconds, then to percentage
+                // CPU percentage = (CPU time / wall clock time) * 100
+                const cpuTimeMs = (cpuDelta.user + cpuDelta.system) / 1000;
+                const cpuPercent = (cpuTimeMs / timeDelta) * 100;
+                health.cpuUsage = Math.round(cpuPercent * 100) / 100; // Round to 2 decimals
+                this.lastCpuUsage = currentCpuUsage;
+                this.lastCpuCheck = now;
+            }
+            else if (timeDelta < 100) {
+                // First check or interval too short - update baseline but don't calculate CPU
+                this.lastCpuUsage = process.cpuUsage();
+                this.lastCpuCheck = now;
+            }
+            // Log health status
+            const logLevel = this.config.logLevel || "info";
+            const healthMessage = `💚 Health Check: Uptime ${health.uptimeFormatted}, Memory ${health.memoryUsageFormatted} (${health.memoryUsagePercent.toFixed(1)}%)${health.cpuUsage !== undefined ? `, CPU ${health.cpuUsage.toFixed(1)}%` : ""}`;
+            const healthData = {
+                uptime: health.uptimeFormatted,
+                memoryUsage: health.memoryUsageFormatted,
+                memoryUsagePercent: health.memoryUsagePercent,
+                timestamp: new Date(health.timestamp).toISOString(),
+            };
+            if (health.cpuUsage !== undefined) {
+                healthData.cpuUsage = `${health.cpuUsage.toFixed(1)}%`;
+            }
+            if (health.services) {
+                healthData.services = health.services;
+            }
+            if (logLevel === "debug") {
+                this.logger.debug(healthMessage, healthData);
+            }
+            else {
+                this.logger.info(healthMessage, undefined, healthData);
+            }
+            // Check thresholds and alert if needed
+            if (this.config.alertsEnabled) {
+                this.checkThresholds(health);
+            }
+        }
+        catch (error) {
+            this.logger.error("Failed to perform health check", undefined, error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+    /**
+     * Check health thresholds and log alerts if exceeded.
+     */
+    checkThresholds(health) {
+        const alertLogLevel = this.config.alertLogLevel || "warn";
+        // Check memory threshold
+        if (health.memoryUsagePercent >= this.config.memoryThreshold) {
+            const message = `⚠️  Memory usage threshold exceeded: ${health.memoryUsagePercent.toFixed(1)}% >= ${this.config.memoryThreshold}%`;
+            const alertData = {
+                metric: "memory",
+                current: `${health.memoryUsagePercent.toFixed(1)}%`,
+                threshold: `${this.config.memoryThreshold}%`,
+                memoryUsage: health.memoryUsageFormatted,
+            };
+            if (alertLogLevel === "error") {
+                this.logger.error(message, undefined, alertData);
+            }
+            else {
+                this.logger.warn(message, undefined, alertData);
+            }
+        }
+        // Check CPU threshold
+        if (health.cpuUsage !== undefined &&
+            health.cpuUsage >= this.config.cpuThreshold) {
+            const message = `⚠️  CPU usage threshold exceeded: ${health.cpuUsage.toFixed(1)}% >= ${this.config.cpuThreshold}%`;
+            const alertData = {
+                metric: "cpu",
+                current: `${health.cpuUsage.toFixed(1)}%`,
+                threshold: `${this.config.cpuThreshold}%`,
+            };
+            if (alertLogLevel === "error") {
+                this.logger.error(message, undefined, alertData);
+            }
+            else {
+                this.logger.warn(message, undefined, alertData);
+            }
+        }
+        // Check external service statuses
+        if (health.services) {
+            for (const [name, service] of Object.entries(health.services)) {
+                if (service.status === "unhealthy") {
+                    const message = `⚠️  Service '${name}' is unhealthy: ${service.error || "Unknown error"}`;
+                    const alertData = {
+                        service: name,
+                        status: service.status,
+                        error: service.error,
+                        responseTime: service.responseTime,
+                    };
+                    if (alertLogLevel === "error") {
+                        this.logger.error(message, undefined, alertData);
+                    }
+                    else {
+                        this.logger.warn(message, undefined, alertData);
+                    }
+                }
+                else if (service.status === "degraded") {
+                    const message = `⚠️  Service '${name}' is degraded${service.responseTime ? ` (response time: ${service.responseTime}ms)` : ""}`;
+                    const alertData = {
+                        service: name,
+                        status: service.status,
+                        responseTime: service.responseTime,
+                    };
+                    this.logger.warn(message, undefined, alertData);
+                }
+            }
+        }
+    }
+    /**
+     * Get current health status (without logging).
+     * @returns Current health status
+     */
+    async getCurrentHealth() {
+        return await collectHealthStatus(this.config.serviceChecks);
+    }
+}
+exports.HealthMonitor = HealthMonitor;