log2stream
v3.1.2
Published
A logging library with an interface inspired by Log4j but removes the concepts of appenders and layouts in favour of streams.
Downloads
21
Readme
log2stream
A logging library with an interface inspired by Log4j but removes the concepts of appenders and layouts in favour of streams.
Usage
The TL;DR is that there are factories (usually one) which create loggers which each create log records of various severity levels that you can format, filter and persist freely using streams.
This module can be treated as an ES module:
import * as log2stream from 'log2stream';
// or
import { LoggerFactory } from 'log2stream';
This module can also be treated as a CommonJS module:
const log2stream = require('log2stream');
// or
const { LoggerFactory } = require('log2stream');
Logger Factories
Loggers are created by a factory:
const factory = new LoggerFactory();
Creating Loggers
Creating loggers is simple:
const logger = factory.getLogger('name');
Note: You can only have one logger instance with a given name. Any subsequent attempts to create a logger with the same name will result in the same logger being returned. For example, this would be true:
factory.getLogger('name') === factory.getLogger('name');
Using a logger
You can create log records that highlight severe errors that may stop the application from running:
logger.fatal('This is a fatal error message.');
You can create log records that highlight errors that wouldn't normally stop the application from running.
logger.error('This is an error message.');
You can create log records that highlight potentially harmful situations.
logger.warn('This is a warning message.');
You can create log records that highlight the progress of an application.
logger.info('This is an information message.');
You can create log records that are useful for debugging an application.
logger.debug('This is a debug message.');
In addition to logging a string message, you may also provide additional metadata:
logger.warn('This is a warning message.',
{
detail : 'Detail of what happened...'
});
Severity levels
There are 5 predefined levels of severity a log record can have:
| Level | Corresponding logger method | Description |
| ----- | ------------------------------ | ---------------------------------------------------------------- |
| Fatal | logger.fatal()
| Severe errors that may stop the application from running. |
| Error | logger.error()
| Errors that wouldn't normally stop the application from running. |
| Warn | logger.warn()
| Potentially harmful situations. |
| Info | logger.info()
| Progress of an application. |
| Debug | logger.debug()
| Details useful for debugging an application. |
These levels are all exposed via the log2stream.Level
type.
Log record streams
All log records created by a logger are written to their own stream:
const target = new stream.Writable(
{
write (record, _, callback)
{
// ...
},
objectMode : true // Important!
});
logger.stream.pipe(target);
Additionally, all log records created by a logger are automatically written to the stream of the factory responsible for creating it:
factory.stream.pipe(target);
Note: Any stream you pipe the logger or factory streams into must have objectMode
enabled, as log records are being streamed, not strings or buffers. Read further at the Node.js stream documentation.
Log record structure
| Property | Type | Description |
| ---------- | -------- | ------------------------------------------------------------------------------- |
| level
| Level
| The severity level. See Severity levels |
| category
| string
| The name of the logger that created the record. |
| message
| string
| The message describing the record. |
| date
| Date
| The date and time the record was created. |
| metadata
| any
| The optional data assocated with the record. |
Formatting log records
To manipulate log records you will have to pipe the stream of a factory (or logger) into a transformation stream. A utility is provided to help you achieve this:
const formatter = log2stream.transform(record =>
{
return `${record.category} - ${record.message}`;
});
factory.stream.pipe(formatter);
Filtering log records
There could be times when you want to filter log records. An example would be to pipe all log records of a severity level greater than Warn
into the stderr
stream.
To achieve this you will have to pipe the stream of a factory (or logger) into a filter stream. A utility is provided to help you achieve this:
const refine = log2stream.filter(record =>
{
return record.level.isGreaterThan(Level.Warn);
});
factory.stream.pipe(filter);
Getting started
This module is available through the Node Package Manager (NPM):
npm install log2stream
Please Note: Versions of Node lower than v12.0.0 are not supported.
Development
Building
You can build CommonJS and ESM versions of this module that are both minified:
npm run build
Testing
This module also has a robust test suite:
npm test
This includes a code quality check using ESLint. Please refer to the .eslintrc
files to familiar yourself with the rules.
License
This module is released under the MIT License.