logty
A really simple streaming logger.
Install
You can install the latest version of the package in your project running the following command:
$ npm install --save logty
Or you can install the global utility to print logging messages in your console running the following command:
$ npm install --global logty
See CLI Usage for more information.
Usage
logty
creates a Readable Stream that can emit logs messages.
Pipe log messages to process.stdout
:
//Import logty
var logty = require('logty');
//Initialize the log stream
var log = new logty(null, { encoding: 'utf8' });
//Pipe the log messages to process.stdout
log.pipe(process.stdout);
//Generate simple log messages
log.debug('This is a debug message');
log.error('This is an error message');
//Close the log stream
log.end();
This will print on console the following lines:
[2017-07-12 13:01:17] [DEBUG] This is a debug message
[2017-07-12 13:01:17] [ERROR] This is an error message
You can pipe log messages to a file:
//Import dependencies
var logty = require('logty');
var fs = require('fs');
//Initialize the log stream
var log = new logty(null, { encoding: 'utf8' });
//Initialize the writable stream
var writer = fs.createWriteStream('./my-logs.txt', { encoding: 'utf8', flags: 'a' });
//Pipe the logs stream to the writer
logs.pipe(writer);
//Generate logs
log.info('This is an info message');
log.error('This is an error message');
//Close the log stream
log.end();
Content of the file:
$ cat my-logs.txt
[2017-07-12 13:01:17] [INFO] This is a info message
[2017-07-12 13:01:17] [ERROR] This is an error message
The default logging message has this structure:
[{{ tag }}] [YYYY-MM-DD hh:mm:ss] [{{ label }}] {{ message }}
-
tag
is the tag string provided on thelogty
constructor. If no tag string is provided, this field will be omitted from the log string. -
label
is the log label. -
message
is log message.
You can change this structure using the log.setFormat
method.
API
var log = new logty(options)
Returns a new Readable Stream
. The options
argument must be an object with the following attributes:
-
tag
: (optionally) a string with the log tag. If not tag is provided (null
or empty string), the tag field of the log message will be removed. -
encoding
: (optionally) the stream encoding. Default isutf8
.
Event: 'data'
The data event will be emitted when a new log message is generated using the log.debug
, log.info
, log.notice
, log.warning
, log.error
or log.fatal
methods.
var log = new logty();
log.on('data', function (message) {
//New log message generated
// . . .
});
//Emit a debug message
log.debug('This is a debug message');
Event: 'error'
The error
event is emitted if an error occurred while writing the log messages into the provided stream. an Error
object will be passed to the listener callback with the error information.
Event: 'end'
The end
event is emitted after the log.end()
method has been called.
log.pipe(writer)
Pipe log messages to a Writable Stream
.
log.setFormat(fn)
In
v0.5.0
this method replaces thev0.4.x
log.format(fn)
method.
In
v0.6.0
, theday
andtime
arguments are not passed to the format function. Uselogty.timestamp
to format the current timestamp.
Use this method to print your custom log messages. The fn
argument must be a function that will be execute each log request with the following arguments:
-
tag
: the log tag string. -
label
: a string with the log label. -
message
: a string with the log message.
log.setFormat(function (tag, label, message) {
//Only print the label and the message
return '[' + label.toUpperCase() + '] ' + message;
});
log.debug('A debug message'); // --> [DEBUG] A debug message
log.setLevel(level)
In
v0.5.0
, this method replaces thev0.4.x
log.level(level)
method.
This method accepts an integer with the maximum log level. Available levels:
-
0
:fatal
-
1
:error
-
2
:warning
-
3
:notice
-
4
:info
-
5
:debug
For example, if you set 2
(warning
) as the maximum level, all the notice
, info
or debug
messages will be omitted.
log.setLevel(2);
log.error('This is an error message'); // --> error <= warning, so this message will be piped
log.debug('This is a debug message'); // --> info > warning, so this message will be ignored
log.debug(message)
log.debug('This is a debug message');
// -> [2018-01-21 21:04:32] [DEBUG] This is a debug message
log.info(message)
log.info('This is an info message');
// -> [2018-01-21 21:04:32] [INFO] This is an info message
log.notice(message)
log.notice('This is a notice message');
// -> [2018-01-21 21:04:32] [NOTICE] This is a notice message
log.warning(message)
log.fatal('This is a warning message');
// -> [2018-01-21 21:04:32] [WARNING] This is a warning message
log.error(message)
log.error('This is an error message');
// -> [2018-01-21 21:04:32] [ERROR] This is an error message
log.fatal(message)
log.fatal('This is a fatal message');
// -> [2018-01-21 21:04:32] [FATAL] This is a fatal message
log.customLabeledMessage(label, message)
Added in
v0.7.0
.
Generate and emit a new log message with a custom label. This method accepts two arguments:
-
label
: astring
with the custom label. -
message
: astring
with the log message.
log.customLabeledMessage("log", "This is a log message");
// -> [2018-01-21 21:04:32] [LOG] This is a log message
log.customLabeledMessage("critical", "This is a critical message");
// -> [2018-01-21 21:04:32] [CRITICAL] This is a critical message
log.end()
Closes the log stream.
Utils
logty.timestamp(pattern)
Added in
v0.6.0
.
A static method to generate a formatted timestamp. Valid patterns:
-
YYYY
: current year. -
MM
: current month. -
DD
: current day. -
hh
: current hours. -
mm
: current minutes. -
ss
: current seconds.
let date = logty.timestamp("YYYY-MM-DD");
// --> "2018-03-07"
let time = logty.timestamp("hh:mm:ss");
// --> "15:24:04"
logty.labels
Added in
v0.6.0
.
A static array with the labels used in logty
.
console.log(logty.labels)
// --> [ "fatal", "error", "warning", "notice", "info", "debug" ]
CLI Usage
You can use logty
in your terminal or in your bash scripts by installing this module globally with npm
. Simply run this command in your terminal:
$ npm install --global logty
You can print the logty
usage guide running logty --help
:
$ logty --help
logty v0.7.0
Usage:
$ logty [options] -m <message>
Options:
-m MESSAGE Set the message to display. This option is mandatory.
-l LABEL Set the label. Default is 'debug'.
--fatal Alias for '-l fatal'.
--error Alias for '-l error'.
--warning Alias for '-l warning'.
--notice Alias for '-l notice'.
--info Alias for '-l info'.
--debug Alias for '-l debug'.
--help, -h Display this usage guide.
Example of use in a bash script:
#!/usr/bin/env bash
## Display a debug message
logty -l debug -m "Hello world" ## --> [2018-01-21 21:04:32] [DEBUG] Hello world
## Display a error message
logty -l error -m "An error message" ## --> [2018-01-21 21:04:32] [ERROR] An error message
## Display a message with a custom label
logty -l custom -m "Hello world" ## --> [2018-01-21 21:04:32] [CUSTOM] Hello world
License
MIT © Josemi Juanes.