ntlogger 2.7.0 → 2.8.1

package/lib/logger.js

@@ -14,9 +14,15 @@ const crypto = require('crypto');
 
 const { setupSignalHandlers } = require('./signalHandler');
 const { initPlugins } = require('../plugins/index');
+const { reportPath } = require('./pathReporter');
+const { LogSampler } = require('./logSampler');
+const { LogDeduplicator } = require('./logDeduplicator');
+const { PerformanceTracker } = require('./performanceTracker');
+
 const colors = require('./colors');
 const levels = require('./levels');
 
+
 // Define a map to hold the logger instances by their location
 const loggerInstances = new Map();
 
@@ -72,6 +78,14 @@ const generateSessionId = () => {
 const sessionId = generateSessionId(); // Generate session ID once
 const color = randomBrightColor();
 
+// Pre-calculate color RGB values and ANSI codes for performance
+const colorRgb = {
+    r: parseInt(color.substring(1, 3), 16),
+    g: parseInt(color.substring(3, 5), 16),
+    b: parseInt(color.substring(5, 7), 16)
+};
+const colorAnsiCode = `\x1b[38;2;${colorRgb.r};${colorRgb.g};${colorRgb.b}m`;
+
 // Custom console formatter with random color for session ID and set color for log level and message
 const consoleFormatter = (config) => winston.format.combine(
     winston.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }),
@@ -83,9 +97,15 @@ const consoleFormatter = (config) => winston.format.combine(
         const levelColor = customSettings.colors[level] || ''; // Default to no color if the level is unknown
         const resetCode = '\x1b[0m';
 
+        // Build location string (optionally include filePath if reportPath is enabled)
+        let locationStr = meta.location || 'Unknown';
+        if (config.reportPath && meta.filePath) {
+            locationStr += ` ${meta.filePath}`;
+        }
+
         // Apply the color to the padded level and the session ID
-        // Note: The session ID color remains based on the 'color' variable
-        return `${timestamp} [${levelColor}${paddedLevel}${resetCode}] [\x1b[38;2;${parseInt(color.substring(1, 3), 16)};${parseInt(color.substring(3, 5), 16)};${parseInt(color.substring(5, 7), 16)}mID: ${shortSessionId}${resetCode}] [${meta.location || 'Unknown'}]: ${levelColor}${message}${resetCode}`;
+        // Note: The session ID color remains based on the 'color' variable (pre-calculated)
+        return `${timestamp} [${levelColor}${paddedLevel}${resetCode}] [${colorAnsiCode}ID: ${shortSessionId}${resetCode}] [${locationStr}]: ${levelColor}${message}${resetCode}`;
     }),
 );
 
@@ -95,13 +115,188 @@ const fileFormatter = (config) => winston.format.combine(
     winston.format.printf(({ timestamp, level, message, ...meta }) => {
         const paddedLevel = level.padEnd(8); // Pad the level to ensure consistent spacing
 
-        return `${timestamp} [${paddedLevel}] [ID: ${sessionId}] [${meta.location || 'Unknown'}]: ${message} ${
-            Object.keys(meta).length ? JSON.stringify(meta, null, 2) : ''
+        // Build location string (optionally include filePath if reportPath is enabled)
+        let locationStr = meta.location || 'Unknown';
+        if (config.reportPath && meta.filePath) {
+            locationStr += ` ${meta.filePath}`;
+        }
+
+        // Include all metadata in JSON (filePath is already shown in locationStr but kept in JSON for structured data)
+        const metaKeys = Object.keys(meta);
+        return `${timestamp} [${paddedLevel}] [ID: ${sessionId}] [${locationStr}]: ${message}${
+            metaKeys.length ? ' ' + JSON.stringify(meta, null, 2) : ''
         }`;
     }),
 );
 
-const createLoggerInstance = (location = "Unknown", config = {}, transports) => {
+/**
+ * Wraps a logger method to add all advanced features
+ * @param {Function} originalMethod - The original logger method (e.g., logger.info)
+ * @param {object} options - Options object with sampler, deduplicator, performanceTracker, etc.
+ * @returns {Function} - Wrapped method with all features
+ */
+function wrapLoggerMethod(originalMethod, options = {}) {
+    const {
+        reportPathEnabled = false,
+        sampler = null,
+        deduplicator = null,
+        performanceTracker = null,
+        childContext = null,
+        loggerInstance = null,
+        level = 'info',
+    } = options;
+
+    return function(...args) {
+        // Capture stack trace BEFORE setImmediate to get the actual call site
+        let capturedCallSite = null;
+        let capturedCallerOfCaller = null;
+        if (reportPathEnabled) {
+            try {
+                const originalPrepareStackTrace = Error.prepareStackTrace;
+                Error.prepareStackTrace = (_, stack) => stack;
+
+                const err = new Error();
+                const stack = err.stack;
+
+                Error.prepareStackTrace = originalPrepareStackTrace;
+
+                // Stack structure: stack[0] = this wrapper function, stack[1] = actual caller
+                // Walk up the stack to skip internal Node.js functions
+                if (stack && stack.length >= 2) {
+                    // Helper to check if a call site is internal
+                    const isInternal = (callSite) => {
+                        if (!callSite) return true;
+                        const funcName = callSite.getFunctionName() || callSite.getMethodName() || '';
+                        const fileName = callSite.getFileName() || '';
+                        return (funcName.startsWith('_') || 
+                                fileName.includes('node:internal/') || 
+                                fileName.includes('node_modules/') ||
+                                fileName.includes('internal/') ||
+                                ['_onTimeout', 'listOnTimeout', 'processTimers', 'setImmediate', 'setTimeout', 'setInterval'].includes(funcName));
+                    };
+
+                    // Start from stack[1] (skip our wrapper)
+                    let callSiteIndex = 1;
+                    
+                    // Skip internal functions to find the actual user code
+                    while (callSiteIndex < stack.length && isInternal(stack[callSiteIndex])) {
+                        callSiteIndex++;
+                    }
+                    
+                    if (callSiteIndex < stack.length) {
+                        capturedCallSite = stack[callSiteIndex];
+                        
+                        // Find the caller of the caller, also skipping internals
+                        let callerIndex = callSiteIndex + 1;
+                        while (callerIndex < stack.length && isInternal(stack[callerIndex])) {
+                            callerIndex++;
+                        }
+                        
+                        if (callerIndex < stack.length) {
+                            capturedCallerOfCaller = stack[callerIndex];
+                        }
+                    } else {
+                        // Fallback: use stack[1] if we can't find non-internal
+                        capturedCallSite = stack[1];
+                        capturedCallerOfCaller = stack.length > 2 ? stack[2] : null;
+                    }
+                }
+            } catch (err) {
+                // Silently fail
+            }
+        }
+
+        // Use setImmediate to make this non-blocking
+        setImmediate(() => {
+            const startTime = performanceTracker?.enabled ? performance.now() : null;
+
+            try {
+                // Extract message and metadata (Winston format: method(message, meta) or method(message))
+                let message = args[0];
+                let meta = {};
+                
+                if (args.length > 1 && typeof args[args.length - 1] === 'object' && args[args.length - 1] !== null && !Array.isArray(args[args.length - 1])) {
+                    // Standard format: method(message, meta)
+                    meta = { ...args[args.length - 1] };
+                    message = args[0];
+                } else if (args.length === 1) {
+                    if (typeof args[0] === 'object' && args[0] !== null && !Array.isArray(args[0])) {
+                        // Object format: method({ message: '...', ...other })
+                        message = args[0].message || JSON.stringify(args[0]);
+                        meta = { ...args[0] };
+                        delete meta.message;
+                    } else {
+                        // Just a message string
+                        message = args[0];
+                    }
+                }
+
+                // Merge child context if available
+                if (childContext) {
+                    meta = { ...childContext, ...meta };
+                }
+
+                // Check sampling and rate limiting
+                if (sampler && !sampler.shouldProcess(level)) {
+                    if (performanceTracker?.enabled && startTime) {
+                        performanceTracker.recordLogProcessing(performance.now() - startTime);
+                    }
+                    return;
+                }
+
+                // Use captured stack trace for filePath
+                if (reportPathEnabled && capturedCallSite) {
+                    const filePath = reportPath(capturedCallSite, capturedCallerOfCaller);
+                    if (filePath) {
+                        meta.filePath = filePath;
+                    }
+                }
+
+                // Check deduplication
+                if (deduplicator) {
+                    const dedupResult = deduplicator.check(level, String(message), meta);
+                    if (dedupResult) {
+                        if (!dedupResult.shouldLog) {
+                            // Suppressed by deduplication
+                            if (performanceTracker?.enabled && startTime) {
+                                performanceTracker.recordLogProcessing(performance.now() - startTime);
+                            }
+                            return;
+                        }
+                        // Update message with count if needed
+                        if (dedupResult.count > 1 && dedupResult.message !== String(message)) {
+                            message = dedupResult.message;
+                        }
+                    }
+                }
+
+                // Call the original method with modified args (Winston format)
+                const transportStartTime = performanceTracker?.enabled ? performance.now() : null;
+                const target = loggerInstance || this;
+                originalMethod.call(target, message, meta);
+                
+                if (performanceTracker?.enabled) {
+                    const logTime = performance.now() - startTime;
+                    performanceTracker.recordLogProcessing(logTime);
+                    if (transportStartTime) {
+                        performanceTracker.recordTransport(performance.now() - transportStartTime);
+                    }
+                }
+            } catch (err) {
+                // Don't break logging if wrapper fails - fall back to original method
+                try {
+                    originalMethod.apply(this, args);
+                } catch (fallbackErr) {
+                    // Last resort - log to console
+                    console.error('Logger wrapper error:', err);
+                    console.error('Fallback also failed:', fallbackErr);
+                }
+            }
+        });
+    };
+}
+
+const createLoggerInstance = (location = "Unknown", config = {}, transports, parentContext = null) => {
     // Configuration options
     const {
         level = 'info',
@@ -114,6 +309,12 @@ const createLoggerInstance = (location = "Unknown", config = {}, transports) =>
         maxFiles = 5,
         timestamp = true,
         skipCache = false,
+        reportPath: reportPathEnabled = false,
+        sampling = {},
+        rateLimit = {},
+        deduplication = { enabled: false, threshold: 3, window: 60000 },
+        performanceMetrics = process.env.NODE_ENV === 'development',
+        statsInterval = 0,
     } = config;
 
     let logTransport = [].filter(Boolean);
@@ -156,24 +357,123 @@ const createLoggerInstance = (location = "Unknown", config = {}, transports) =>
         }
     });
 
+    // Initialize feature modules
+    const sampler = (Object.keys(sampling).length > 0 || Object.keys(rateLimit).length > 0) 
+        ? new LogSampler({ sampling, rateLimit }) 
+        : null;
+    const deduplicator = deduplication.enabled 
+        ? new LogDeduplicator(deduplication) 
+        : null;
+    const perfTracker = performanceMetrics 
+        ? new PerformanceTracker(true) 
+        : null;
+
+    // Store child context (merge with parent if exists)
+    const childContext = parentContext ? Object.freeze({ ...parentContext }) : null;
+
+    // Wrap logger methods with all features
+    const wrapOptions = {
+        reportPathEnabled,
+        sampler,
+        deduplicator,
+        performanceTracker: perfTracker,
+        childContext,
+        loggerInstance: logger,
+    };
+
+    const boundLogger = logger;
+    logger.info = wrapLoggerMethod(boundLogger.info.bind(boundLogger), { ...wrapOptions, level: 'info' });
+    logger.warn = wrapLoggerMethod(boundLogger.warn.bind(boundLogger), { ...wrapOptions, level: 'warn' });
+    logger.error = wrapLoggerMethod(boundLogger.error.bind(boundLogger), { ...wrapOptions, level: 'error' });
+    logger.debug = wrapLoggerMethod(boundLogger.debug.bind(boundLogger), { ...wrapOptions, level: 'debug' });
+    logger.trace = wrapLoggerMethod(boundLogger.trace.bind(boundLogger), { ...wrapOptions, level: 'trace' });
+    logger.fatal = wrapLoggerMethod(boundLogger.fatal.bind(boundLogger), { ...wrapOptions, level: 'fatal' });
+    logger.internal = wrapLoggerMethod(boundLogger.internal.bind(boundLogger), { ...wrapOptions, level: 'internal' });
+
+    // Add child logger method
+    logger.child = function(context) {
+        const mergedContext = childContext ? { ...childContext, ...context } : context;
+        // Use skipCache for child loggers to avoid cache conflicts
+        const childConfig = { ...config, skipCache: true };
+        // Generate unique location for child logger
+        const childLocation = `${location}:child:${Date.now()}:${Math.random().toString(36).substring(7)}`;
+        return createLoggerInstance(childLocation, childConfig, transports, mergedContext);
+    };
+
+    // Add performance tracking methods
+    if (perfTracker) {
+        logger.time = function(label) {
+            perfTracker.time(label);
+        };
+        logger.timeEnd = function(label) {
+            const duration = perfTracker.timeEnd(label);
+            if (duration !== null) {
+                logger.debug(`Timer '${label}' completed in ${duration.toFixed(2)}ms`);
+            }
+            return duration;
+        };
+    }
+
+    // Add statistics method
+    logger.getStats = function() {
+        const stats = {
+            sampling: sampler ? sampler.getStats() : null,
+            deduplication: deduplicator ? deduplicator.getStats() : null,
+            performance: perfTracker ? perfTracker.getStats() : null,
+        };
+        return stats;
+    };
+
+    // Add flush method (non-blocking, returns Promise)
+    logger.flush = function() {
+        return new Promise((resolve) => {
+            setImmediate(() => {
+                // Flush all transports that support it
+                const flushPromises = logger.transports.map(transport => {
+                    if (transport.flush && typeof transport.flush === 'function') {
+                        return Promise.resolve(transport.flush());
+                    }
+                    return Promise.resolve();
+                });
+                Promise.all(flushPromises).then(() => resolve());
+            });
+        });
+    };
+
+    // Add close method (graceful shutdown)
+    logger.close = function() {
+        return new Promise((resolve) => {
+            setImmediate(() => {
+                // Destroy feature modules
+                if (sampler) sampler.destroy();
+                if (deduplicator) deduplicator.destroy();
+                
+                // Close all transports
+                logger.end(() => {
+                    resolve();
+                });
+            });
+        });
+    };
+
+    // Statistics reporting interval
+    if (statsInterval > 0 && (sampler || deduplicator)) {
+        setInterval(() => {
+            const stats = logger.getStats();
+            logger.internal('Logger Statistics:', stats);
+        }, statsInterval);
+    }
+
     // Cache the newly created logger instance
     loggerInstances.set(location, logger);
 
     if (debug === true) {
-        // Extract RGB components from the color string
-        const rgb = {
-            r: parseInt(color.slice(1, 3), 16),
-            g: parseInt(color.slice(3, 5), 16),
-            b: parseInt(color.slice(5, 7), 16)
-        };
-
-        // Construct ANSI escape code for the RGB color
-        const colorCode = `\x1b[38;2;${rgb.r};${rgb.g};${rgb.b}m`;
+        // Use pre-calculated color values
         const resetCode = `\x1b[0m`;
 
-        logger.internal(`Logger instance created from ${location} with session ID: ${colorCode}${sessionId.slice(-6)}${resetCode}`);
-        logger.internal(`Logger instance created from ${location} with color: ${colorCode}${color}${resetCode}`);
-        logger.internal(`Logger instance created from ${location} with log level: ${colorCode}${logger.level}${resetCode}`);
+        logger.internal(`Logger instance created from ${location} with session ID: ${colorAnsiCode}${sessionId.slice(-6)}${resetCode}`);
+        logger.internal(`Logger instance created from ${location} with color: ${colorAnsiCode}${color}${resetCode}`);
+        logger.internal(`Logger instance created from ${location} with log level: ${colorAnsiCode}${logger.level}${resetCode}`);
     }
 
     return logger;

package/lib/messageNormalizer.js

@@ -0,0 +1,39 @@
+/**
+ * @file /lib/messageNormalizer.js
+ * @description Normalizes log messages by replacing dynamic values with placeholders for deduplication.
+ */
+
+/**
+ * Normalizes a message by replacing dynamic values (UUIDs, IDs, numbers) with placeholders
+ * @param {string} message - The message to normalize
+ * @returns {string} - Normalized message with placeholders
+ */
+function normalizeMessage(message) {
+    // Convert to string first, then normalize
+    let normalized = typeof message === 'string' ? message : String(message);
+
+    // Replace UUIDs (e.g., a481199f-ed1c-47c6-834d-9cf54cdc394e)
+    normalized = normalized.replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, '*');
+
+    // Replace long hex strings (32+ chars)
+    normalized = normalized.replace(/[0-9a-f]{32,}/gi, '*');
+
+    // Replace numbers that appear to be IDs (standalone numbers, especially in phrases like "device 1234")
+    normalized = normalized.replace(/\b(?:device|id|threshold|ticket|job|request|user|session)\s+(\d+)\b/gi, (match, num) => {
+        return match.replace(num, '*');
+    });
+
+    // Replace standalone large numbers (likely IDs) - but keep small numbers (like counts, percentages)
+    // Handle both word-boundary cases and standalone numbers (start/end of string)
+    normalized = normalized.replace(/(?:^|\b)(\d{4,})(?:\b|$)/g, '*');
+
+    // Replace timestamps (numbers with dashes or colons)
+    normalized = normalized.replace(/\d{4}-\d{2}-\d{2}[\sT]\d{2}:\d{2}:\d{2}/g, '*');
+
+    return normalized;
+}
+
+module.exports = {
+    normalizeMessage,
+};
+

package/lib/pathReporter.js

@@ -0,0 +1,120 @@
+/**
+ * @file /lib/pathReporter.js
+ * @description Utility function for reporting the file path, line number, column number, and call chain where a log statement is executed.
+ */
+
+const path = require('path');
+
+/**
+ * Checks if a function name or file path is an internal Node.js function
+ * @param {string} functionName - Function name to check
+ * @param {string} fileName - File path to check
+ * @returns {boolean} - True if internal
+ */
+function isInternalFunction(functionName, fileName) {
+    if (!functionName && !fileName) return true;
+    
+    // Check for internal Node.js function names
+    const internalNames = [
+        '_onTimeout',
+        'listOnTimeout',
+        'processTimers',
+        'process.nextTick',
+        'setImmediate',
+        'setTimeout',
+        'setInterval',
+        'Promise.then',
+        'Promise.catch',
+        'Promise.finally',
+    ];
+    
+    if (functionName) {
+        // Check if function name starts with underscore (internal convention)
+        if (functionName.startsWith('_')) {
+            return true;
+        }
+        // Check against known internal names
+        if (internalNames.includes(functionName)) {
+            return true;
+        }
+    }
+    
+    // Check if file is from Node.js internals
+    if (fileName) {
+        if (fileName.includes('node:internal/') || 
+            fileName.includes('node_modules/') ||
+            fileName.includes('internal/') ||
+            fileName.includes('timers.js') ||
+            fileName.includes('next_tick.js') ||
+            fileName.includes('promise.js')) {
+            return true;
+        }
+    }
+    
+    return false;
+}
+
+/**
+ * Reports the file path, line number, column number, and call chain from CallSite objects.
+ * @param {Object} callSite - The CallSite object representing where the log was called (stack[1])
+ * @param {Object} callerOfCaller - Optional CallSite object representing the caller of the caller (stack[2])
+ * @returns {string} - Formatted string like "./path/to/file.js:123:45 [functionName ← callerFunctionName]"
+ */
+function reportPath(callSite, callerOfCaller = null) {
+    try {
+        if (!callSite) {
+            return './unknown';
+        }
+
+        const file = callSite.getFileName();
+        const line = callSite.getLineNumber();
+        const col = callSite.getColumnNumber();
+
+        if (!file) {
+            return './unknown';
+        }
+
+        const callerName = callSite.getFunctionName() || callSite.getMethodName() || '';
+        let callerOfCallerName = callerOfCaller
+            ? (callerOfCaller.getFunctionName() || callerOfCaller.getMethodName() || '')
+            : '';
+
+        // Filter out internal functions from call chain
+        // If caller is internal, don't include it in the chain
+        const callerIsInternal = isInternalFunction(callerName, file);
+        const callerOfCallerIsInternal = callerOfCaller && isInternalFunction(
+            callerOfCallerName, 
+            callerOfCaller.getFileName()
+        );
+
+        // Get base path (project root)
+        const basePath = require.main?.path || process.cwd();
+
+        // Build relative path
+        const relativeDir = path
+            .relative(basePath, path.dirname(file))
+            .replace(/\\/g, '/')
+            .replace(/(\.\.\/)+/g, '');
+
+        const shortPath = './' + (relativeDir ? relativeDir + '/' : '') + path.basename(file);
+
+        // Build the optional "call chain" string only if both are known and not internal
+        let callChain = '';
+        if (!callerIsInternal && !callerOfCallerIsInternal && callerName && callerOfCallerName) {
+            callChain = ` [${callerName} ← ${callerOfCallerName}]`;
+        } else if (!callerIsInternal && callerName && callerOfCallerName && !callerOfCallerIsInternal) {
+            // Only show caller if callerOfCaller is internal
+            callChain = ` [${callerName}]`;
+        }
+
+        return `${shortPath}:${line}:${col}${callChain}`;
+    } catch (err) {
+        console.error('Error in reportPath:', err.message);
+        return './unknown';
+    }
+}
+
+module.exports = {
+    reportPath,
+};
+

package/lib/performanceTracker.js

@@ -0,0 +1,112 @@
+/**
+ * @file /lib/performanceTracker.js
+ * @description Tracks performance metrics for development mode.
+ */
+
+/**
+ * Performance tracker class
+ */
+class PerformanceTracker {
+    constructor(enabled = false) {
+        this.enabled = enabled;
+        this.timers = new WeakMap(); // Use WeakMap to avoid memory leaks
+        this.timerData = new Map(); // Store timer data with labels as keys
+        this.stats = {
+            logProcessingTime: [],
+            transportTime: [],
+        };
+    }
+
+    /**
+     * Start a timer
+     * @param {string} label - Timer label
+     */
+    time(label) {
+        if (!this.enabled) return;
+        this.timerData.set(label, performance.now());
+    }
+
+    /**
+     * End a timer and return duration
+     * @param {string} label - Timer label
+     * @returns {number|null} - Duration in milliseconds or null if timer not found
+     */
+    timeEnd(label) {
+        if (!this.enabled) return null;
+        const start = this.timerData.get(label);
+        if (start === undefined) {
+            return null;
+        }
+        const duration = performance.now() - start;
+        this.timerData.delete(label);
+        return duration;
+    }
+
+    /**
+     * Record log processing time
+     * @param {number} duration - Duration in milliseconds
+     */
+    recordLogProcessing(duration) {
+        if (!this.enabled) return;
+        this.stats.logProcessingTime.push(duration);
+        // Keep only last 100 entries
+        if (this.stats.logProcessingTime.length > 100) {
+            this.stats.logProcessingTime.shift();
+        }
+    }
+
+    /**
+     * Record transport execution time
+     * @param {number} duration - Duration in milliseconds
+     */
+    recordTransport(duration) {
+        if (!this.enabled) return;
+        this.stats.transportTime.push(duration);
+        // Keep only last 100 entries
+        if (this.stats.transportTime.length > 100) {
+            this.stats.transportTime.shift();
+        }
+    }
+
+    /**
+     * Get statistics
+     * @returns {object} - Statistics object
+     */
+    getStats() {
+        if (!this.enabled) {
+            return { enabled: false };
+        }
+
+        const avgLogProcessing = this.stats.logProcessingTime.length > 0
+            ? this.stats.logProcessingTime.reduce((a, b) => a + b, 0) / this.stats.logProcessingTime.length
+            : 0;
+
+        const avgTransport = this.stats.transportTime.length > 0
+            ? this.stats.transportTime.reduce((a, b) => a + b, 0) / this.stats.transportTime.length
+            : 0;
+
+        return {
+            enabled: true,
+            avgLogProcessingTime: avgLogProcessing,
+            avgTransportTime: avgTransport,
+            logProcessingSamples: this.stats.logProcessingTime.length,
+            transportSamples: this.stats.transportTime.length,
+        };
+    }
+
+    /**
+     * Reset statistics
+     */
+    resetStats() {
+        this.stats = {
+            logProcessingTime: [],
+            transportTime: [],
+        };
+        this.timerData.clear();
+    }
+}
+
+module.exports = {
+    PerformanceTracker,
+};
+