You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/async-logging.md
+31-24Lines changed: 31 additions & 24 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,14 +6,13 @@ Asynchronous logging is a feature of ACL that allows log operations to be non-bl
6
6
7
7
### Enabling Async Mode
8
8
9
-
You can configure ACL to run in async mode globally by setting the `useAsyncLogging` option to `true` when creating the logger instance:
9
+
You can configure ACL to run in async mode globally by setting the `mode` option to `"async"`, `"async-queue"`, or `"worker"` when creating the logger instance:
10
10
11
11
```js
12
12
constlogger=ACL.getInstance({
13
13
logLevel:1,
14
-
useAsyncLogging:true,
14
+
mode:"async",
15
15
});
16
-
17
16
logger.info("This is an async info message");
18
17
logger.error("This is an async error message");
19
18
```
@@ -25,35 +24,43 @@ logger.infoAsync("This is an async info message");
25
24
logger.errorAsync("This is an async error message");
26
25
```
27
26
28
-
##Why Use Async Logging?
27
+
### Async-Queue Mode
29
28
30
-
Asynchronous logging is beneficial in scenarios where logging operations are frequent, and blocking I/O can negatively impact performance. Here’s why you should consider it:
29
+
If you need to optimize file I/O operations further, you can use the `async-queue` mode. In this mode, log entries are queued and written to the file in batches, reducing the overhead associated with individual file writes.
31
30
32
-
-**Improved Performance:** The async methods do not block the event loop, making them better suited for scenarios where multiple log operations are performed rapidly.
33
-
-**Non-blocking I/O:** Since the file operations are handled asynchronously, the main thread is not held up by I/O tasks, reducing latency and improving overall responsiveness.
34
-
-**Flexibility:** By enabling `useAsyncLogging`, users can switch to async logging methods seamlessly without changing their code structure.
31
+
Configure `queueBatchSize` and `flushInterval` options for fine-grained control:
35
32
36
-
## Use Cases for Async Logging
33
+
```js
34
+
constlogger=ACL.getInstance({
35
+
mode:"async-queue",
36
+
outputFilename:"async-queue-app.log",
37
+
queueBatchSize:10, // Number of log entries before triggering a flush
38
+
flushInterval:1000, // Interval (in milliseconds) for flushing logs
39
+
});
40
+
```
37
41
38
-
-**High-frequency logging scenarios:** Applications that generate a large number of log entries in a short period (e.g., high-volume APIs, data processing pipelines).
39
-
-**Applications with strict latency requirements:** Use async logging to avoid delays in time-sensitive applications.
40
-
-**Microservices and distributed systems:** Async logging minimizes delays in inter-service communication and ensures that the service remains responsive.
42
+
### Worker Mode
41
43
42
-
## How to Optimize Async Logging Performance
44
+
In worker mode, the logging operations are offloaded to a worker thread, making it the most efficient option in high-throughput environments.
43
45
44
-
### Batch Writes
46
+
```js
47
+
constlogger=ACL.getInstance({
48
+
mode:"worker",
49
+
outputFilename:"worker-app.log",
50
+
includeTimestamps:true,
51
+
});
52
+
```
45
53
46
-
Consider implementing batched logging for even greater performance. While ACL currently logs each message as a separate operation, batching multiple messages into a single write operation can significantly improve performance under high-load scenarios. Currently, this can be customized by extending ACL’s core implementation.
54
+
### Why Use Async Logging?
47
55
48
-
### Error Handling in Async Mode
56
+
Asynchronous logging is beneficial in scenarios where logging operations are frequent, and blocking I/O can negatively impact performance. Here’s why you should consider it:
49
57
50
-
One consideration for async logging is error handling. Ensure that async methods are correctly handled using `.catch()` for promises, or `try...catch` blocks with `await` to prevent unhandled rejections that might affect your application flow.
58
+
-**Improved Performance:** The async methods do not block the event loop, making them better suited for scenarios where multiple log operations are performed rapidly.
59
+
-**Non-blocking I/O:** Since the file operations are handled asynchronously, the main thread is not held up by I/O tasks, reducing latency and improving overall responsiveness.
60
+
-**Flexibility:** By enabling `mode: "async"`, `mode: "async-queue"`, or `mode: "worker"`, users can switch to async logging seamlessly.
|**Use Case**| Suitable for low-throughput scenarios | Best for high-throughput, non-blocking requirements |
64
+
-**High-frequency logging scenarios:** Applications that generate a large number of log entries in a short period (e.g., high-volume APIs, data processing pipelines).
65
+
-**Applications with strict latency requirements:** Use async logging to avoid delays in time-sensitive applications.
66
+
-**Microservices and distributed systems:** Async logging minimizes delays in inter-service communication and ensures that the service remains responsive.
|`color`|`object`|`{}`| Allows custom color configuration for log levels. See **[Example: Custom Colors](/examples/custom-colors.js)** for implementation details. |
// Custom logic to send logs to an external service
35
+
// Custom integration code to send logs to a third-party service
36
36
}
37
37
}
38
38
```
@@ -54,8 +54,17 @@ class CustomHeaderLogger extends ACL {
54
54
}
55
55
```
56
56
57
-
### Extending ACL’s functionality allows you to implement features such as:
57
+
### 4. Using `loadDynamicMethodsAndProperties`
58
58
59
-
- Custom log formatting
60
-
- Logging to multiple destinations
61
-
- Advanced log aggregation and monitoring solutions
59
+
The ACL class includes a powerful utility to dynamically load methods and properties from external classes. Use `loadDynamicMethodsAndProperties` to inject custom behaviors:
Copy file name to clipboardExpand all lines: docs/performance-considerations.md
+98-9Lines changed: 98 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,26 +6,115 @@ To optimize ACL’s performance in high-throughput applications, consider the fo
6
6
7
7
### 1. Use Asynchronous Logging
8
8
9
-
Set `useAsyncLogging` to `true` in your logger configuration or use async methods (e.g., `logger.infoAsync`) to prevent blocking the main event loop. This approach is ideal for high-frequency logging scenarios where performance is critical.
9
+
Set the `mode` configuration option to `"async"`, `"async-queue"`, or `"worker"` to enable asynchronous logging. This prevents blocking the main event loop and is ideal for high-frequency logging scenarios where performance is critical. The selected mode determines how logs are managed:
10
+
11
+
-**Async Mode**: Log methods (`info`, `warn`, etc.) are converted to their asynchronous equivalents (`infoAsync`, `warnAsync`, etc.) to avoid blocking the main thread during I/O operations.
12
+
-**Async-Queue Mode**: Log entries are batched and written in groups based on the `queueBatchSize` and `flushInterval` configurations, reducing the frequency of file writes and improving performance.
13
+
-**Worker Mode**: Logging operations are offloaded to a separate worker thread, further isolating logging I/O from the main application flow.
14
+
15
+
#### Example:
16
+
17
+
```js
18
+
constlogger=ACL.getInstance({
19
+
mode:"async-queue", // Use "async" or "worker" depending on needs
20
+
queueBatchSize:50,
21
+
flushInterval:1000,
22
+
});
23
+
```
24
+
25
+
### 2. Optimize File I/O Operations
26
+
27
+
ACL supports batched logging through the `"async-queue"` mode, which reduces file I/O by grouping log entries together before writing to the file. Use the following configurations to fine-tune file I/O:
28
+
29
+
-**`queueBatchSize`**: Defines the number of log entries to batch before writing to the file.
30
+
-**`flushInterval`**: Sets the interval (in milliseconds) at which the log queue is flushed when in `async-queue` mode.
31
+
32
+
This ensures that log entries are written to the file in larger batches, minimizing the number of disk operations and improving performance.
33
+
34
+
#### Example:
35
+
36
+
```js
37
+
constlogger=ACL.getInstance({
38
+
mode:"async-queue",
39
+
queueBatchSize:100,
40
+
flushInterval:2000,
41
+
});
42
+
```
43
+
44
+
### 3. Configure File Rotation and Retention
45
+
46
+
Proper file rotation and retention settings prevent uncontrolled log file growth, which could degrade performance over time. Use the following options to manage log file size and disk space:
47
+
48
+
-**`maxLogFileSizeMB`**: Sets the maximum size (in MB) of each log file before it is rotated.
49
+
-**`maxLogFiles`**: Limits the number of rotated log files to retain. Older files are deleted when this limit is exceeded.
50
+
51
+
These settings help maintain optimal performance by keeping file sizes manageable and avoiding excessive disk usage.
52
+
53
+
#### Example:
54
+
55
+
```js
56
+
constlogger=ACL.getInstance({
57
+
outputFilename:"app.log",
58
+
maxLogFileSizeMB:10, // Rotate files at 10MB size
59
+
maxLogFiles:5, // Retain up to 5 log files
60
+
});
61
+
```
62
+
63
+
### 4. Reduce Console Logging Overhead
64
+
65
+
Frequent console logging can introduce significant overhead, especially in production environments where logs may be generated at a high frequency. Consider the following strategies to reduce this overhead:
66
+
67
+
-**Raise the Console Log Level**: Increase the `logLevel` configuration to avoid lower-level logs such as `debug` and `info`.
68
+
-**Disable Console Logging**: Set `logLevel` to `4` (`error`) or higher to limit console output to errors and critical messages.
69
+
-**Use Conditional Logging**: Control logging dynamically by using conditional logging methods (e.g., `logger.info(showLogs, "Message")`).
70
+
71
+
#### Example:
72
+
73
+
```js
74
+
constlogger=ACL.getInstance({
75
+
logLevel:3, // Only log warnings and higher to console
76
+
});
77
+
```
78
+
79
+
### 5. Minimize Memory Usage Tracking
80
+
81
+
Memory usage tracking is an optional feature that can be enabled using the `includeMemoryUsage` configuration. If this information is not needed, disable memory tracking to reduce the computational cost associated with collecting and formatting memory statistics.
82
+
83
+
-**`includeMemoryUsage`**: Set to `false` to disable memory usage tracking.
84
+
-**`memoryCheckFrequency`**: If memory tracking is required, adjust the frequency of checks to reduce performance impact.
10
85
11
86
#### Example:
12
87
13
88
```js
14
89
constlogger=ACL.getInstance({
15
-
useAsyncLogging:true,
90
+
includeMemoryUsage:false, // Disable memory usage tracking for better performance
16
91
});
17
92
```
18
93
19
-
### 2. Reduce Console Logging
94
+
### 6. Utilize Worker Threads for Logging
20
95
21
-
Frequent console writes can introduce overhead, especially in production environments. Consider using higher log levels (`logLevel: 3` for `warn` and above) or disable console logging entirely to reduce performance impact.
96
+
For high-throughput applications that need to completely offload logging operations, use the `"worker"` mode. In this mode, all logging operations are handled in a separate worker thread, freeing up the main thread to focus on application logic.
22
97
23
-
### 3. Minimize Memory Usage Tracking
98
+
This mode is ideal for applications with strict performance requirements, as it prevents any logging-related I/O from blocking the main application.
24
99
25
-
If memory tracking is not required, disable it by setting `includeMemoryUsage` to `false`. This reduces the computational cost associated with memory statistics collection.
100
+
#### Example:
26
101
27
-
### 4. Optimize File I/O Operations
102
+
```js
103
+
constlogger=ACL.getInstance({
104
+
mode:"worker",
105
+
outputFilename:"worker-app.log",
106
+
maxLogFileSizeMB:5,
107
+
maxLogFiles:3,
108
+
});
109
+
```
28
110
29
-
Configure file rotation and reduce log file write frequency by batching multiple log entries into a single write operation. While not currently built into ACL, this can be implemented by extending the library.
111
+
### Summary of Performance Tips
30
112
31
-
By applying these strategies, you can significantly improve the performance of ACL in demanding scenarios.
0 commit comments