Advanced Console Log (ACL), available as the advanced-console-log
NPM package, is a lightweight logging module for Node.js applications. It supports console and file logging with various levels, colors, and additional features such as memory usage tracking and caller information.
- Advanced Configuration Options: Provides extensive configuration options such as memory display modes, caller info inclusion levels, and more.
- Multiple Log Levels: Supports six logging levels (debug, log, info, warn, error, fatal) to categorize and prioritize log messages.
- Console Logging: Outputs log messages to the console with color-coded and formatted output based on log level.
- File Logging: Optionally logs messages to a specified file, with separate control over the log level for file output.
- Asynchronous Logging Modes: Supports multiple asynchronous logging modes ("async", "async-queue", "worker") for non-blocking operations in high-throughput environments.
- Timestamps: Includes configurable timestamps for all log messages.
- Custom Color Configuration: Allows custom color settings for each log level to override default colors.
- Asynchronous Logging: Supports async versions of all log methods for non-blocking operations.
- Conditional Logging: Allows log messages to be conditionally logged based on boolean values.
- Fatal Logging and Process Termination: Optionally terminates the application upon a fatal log message.
- Caller Information: Includes caller information (file, function, line, and column) in log messages based on log level and configuration.
- Inline Caller Information: Displays inline caller information within log messages for quick debugging reference.
- Memory Usage Tracking: Tracks and displays memory usage, either in MB or percentage format, based on configuration.
- Timers and Performance Measurement: Provides methods to start, stop, and measure elapsed time using high-resolution timers (
time
,timeEnd
,startTimer
,stopTimer
).
- Stack Tracing: Supports stack tracing with the
trace
method, similar toconsole.trace
. - Pretty Printing of Objects: Includes a
dir
method for pretty printing complex objects similar toconsole.dir
.
- Log Reports: Generates a report detailing the number of times each log method was called, with percentages.
- File Rotation and Retention: Supports automatic log file rotation and retention strategies to manage log file sizes and disk space.
This logging module utilizes the following built-in Node.js modules:
fs
: For file system operations, such as appending log messages to a specified file.path
: Provides utilities for handling and manipulating file paths, ensuring cross-platform compatibility when working with file system operations.util
: Used to format and inspect complex objects for pretty printing in log outputs.process
: Provides access to the current Node.js process, enabling memory usage tracking and process termination.v8
: Retrieves memory heap statistics to track memory usage within the application. Lazy loaded for performance reasons.worker_threads
: Used for worker thread operations in worker mode. Lazy loaded for performance reasons.
There are no external dependencies.
To install the advanced-console-log npm module, you can use npm:
npm install advanced-console-log
After installation, import advanced-console-log
into your application using require:
const ACL = require("advanced-console-log");
Then you can get a single instance of ACL (recommended), created with your custom configuration options.
const logger = ACL.getInstance({
logLevel: 1,
});
or create a new ACL instance, using your custom configuration options.
const logger = new ACL({
logLevel: 1,
});
ACL supports a number of different configuration options. Here is another example using additional configuration options:
const logger = ACL.getInstance({
logLevel: 1,
outputFilename: "app.log",
outputFileLogLevel: 2,
includeTimestamps: true,
includeMemoryUsage: true,
generateReport: true,
terminateOnFatal: true,
mode: "async",
});
ACL supports different modes of asynchronous logging to improve performance in high-throughput scenarios.
- Regular Mode: Default mode; logging methods are synchronous.
- Async Mode: All logging methods are converted to their asynchronous equivalents.
- Async-Queue Mode: Logs are queued and flushed in batches to improve performance.
- Worker Mode: Logging operations are offloaded to a worker thread to prevent blocking the main event loop.
To enable an asynchronous logging mode, set the mode
configuration option:
const logger = ACL.getInstance({
mode: "async",
});
Once created, you can use the logger to log messages at various levels:
logger.info("This is an info message");
logger.warn("This is a warning message");
logger.error("This is an error message");
You can also use a boolean to control log display.
const showLog = true;
logger.log(showLog, "This is a log message");
If generateReport
is set to true
, you can generate a detailed report at the end of the application.
const logger = ACL.getInstance({
generateReport: true,
});
logger.report();
ACL also supports asynchronous logging e.g., non-blocking operations. You can configure ACL to run in async mode:
const logger = ACL.getInstance({
mode: "async",
});
logger.info("This is an async info message");
logger.error("This is an async error message");
or you can directly call the async versions of log methods if you prefer:
logger.infoAsync("This is an async info message");
logger.errorAsync("This is an async error message");
ACL lets you measure the elapsed time of code execution using timers:
logger.startTimer("Initialization");
// code to measure
logger.stopTimer("Initialization");
Use the dir
method to pretty print complex objects:
const sampleObject = { name: "John", age: 30, location: "New York" };
logger.dir(sampleObject);
- Asynchronous Logging
- Configuration Options
- File Rotation and Retention Strategy
- How to Extend or Customize ACL
- Log Levels
- Methods
- Performance Considerations
- Basic Usage: A simple example demonstrating basic logging methods.
- Configuration Options: Showcases various configuration options available in ACL.
- Async Mode: Demonstrates how to use ACL in async mode.
- Async-Queue Mode: Shows how to use the async-queue mode for batching logs.
- Worker Mode: Explains how to use the worker mode to offload logging operations.
- Custom Colors: Explains how to set custom colors for different log levels.
- Generate Report: Shows how to generate a detailed report of log statistics.
- Terminate on Fatal: Demonstrates how to terminate the application upon a fatal log message.
- Timers: Using timer methods to measure code execution time.
- File Rotation: Demonstrates file rotation and retention strategy.
- Memory Usage: Tracks and displays memory usage information.
- Caller Info: Includes caller information (file, function, line) in log messages.
- Conditional Logging: Logs messages conditionally based on a boolean value.
- Pretty Printing: Uses the
dir
method to pretty print complex objects. - Stack Trace: Logs the current stack trace of the application.
- Extending ACL: Demonstrates how to extend ACL to add custom functionality.
Contributions to this project are welcome. Please fork the repository and submit a pull request with your changes or improvements.
This project is licensed under the MIT License - see the LICENSE file for details.