Blocklog NPM | npm.io

#blockLog A simple and adaptable stream-based logging lib for node.js, with support for multiple outputs and log rotation.

##Installation Simply install via npm:
npm install --save blocklog

##Usage

First of all require it and get a new instance:

var blockLog = require('blocklog'),
    log      = new blockLog('name');

Then you will need to attach an adapter to stream to. This must be a writeable stream, like process.stdout or a writeable file stream using fs.createWriteStream.

For most streams you will also need to specify the logging type. At the moment there are three logging types:

raw: The raw input data will be piped through
plain: blockLog will nicely format the logging message into a nice string for you (as [LEVEL] MSG")
json: The data will be passed as JSON strings. Useful when you want to read the data later, without complicated parsing.

NOTE: When using the plain or json format blockLog will append a \n at the end of the formatted string.

Once you have attached a stream (you may attach more than one, at any time) you can start logging:

var blockLog = require('blocklog'),
    log      = new blockLog('name');

log.attach('stdout', process.stdout, 'plain');

log.info('Hello World');

log.warning('Oh no');

log.error('whoops', 'another Error');

log.log('customLogLevel', ['msg1', 'msg2']);

If you want to log to a file simply open a writeable stream with fs:

var blockLog = require('blocklog'),
    log      = new blockLog('name');
    fs       = require('fs');

log.attach('fileLog', fs.createWriteStream('path/to/file.txt', {encoding: 'uft8'}), 'json');

log.info('Hello File');

##Usage with Express.js blockLog comes with a middleware wrapper for express.js applications.

//...

app.use(log.express());

Don't forget to attach streams to the logger, otherwise you won't see anything.

##API

####new blockLog(name) You can create multiple instances, each with their own set of attached streams, filters, formatters, etc. You may pass in a name to be able to distinguish the instances, if they log to the same stream (like stdout).

####attach(name, stream, type) The first argument is the name of the stream (used internally and can be used to remove it later one), then a writable stream and the type of data the stream accepts, e. g. plain text (plain) or raw data (raw).

####info(msg...) Logs the parameters to the stream and marks them as info level logs.

####warning(msg...) Logs the parameters to the stream and marks them as info level logs.

####error(msg...) Logs the parameters to the stream and marks them as info level logs.

####log(level, msgs) The internal method used to log to the stream. Accepts a log level and an array of log messages.

####setPlainFormat(fn) Replace the default format for the plain text output. The function takes one parameter, which will be the log data: log level and message.
Example:

log.setPlainFormat(function(data) {
    return '|' + data.level + '| -> ' + JSON.stringify(data.msg) + '\n';
});

####addMap(mapFn, opts) Add a map to transform the log data. The mapFn will be passed to event-stream's map function, so each function will get two parameters, the data and a callback that must be called.

opts can hold the following keys:

key	default	description
type	'all'	To which type of log output should this map apply, like 'json' or 'plain'
levels	'all'	Either 'all' or an array of log levels the map should apply, e. g. 'info', 'error'

Example:

log.addMap(function(data, cb) {
    data.msg += ' (transformed)';
    cb(null, data);
});

####createEndpoint(fn) If you don't want to deal with streams you can simply create an endpoint to pipe to. This method takes a function that will be executed for each logged item.

var ep  = log.createEndpoint(function(data) {
        mail(data).to("email");
        // or do anything else you want to do with your data here
    });

log.attach('endpoint', ep);

###Log rotation blockLog supports log roation for file based streams. Create a writeable file stream and attach it to the log stream. By passing the rotation option you can specify the log rotation.

key	description
path	The path to the file that is being rotated. The old logs will have the same name with the `format` appended
format	The way the time will be formated when the old log file is created
period	A string made up of a number and a unit
afterRotate	A callback that will be fired after the log rotation has created a new file. It will be passed the path to the new file and the timestamp at which it was created

####Options for the period: |unit|description| |:--|:----------| |s|Seconds| |m|Minutes| |h|Hours| |d|Days| |w|Weeks| |M|Months| |y|Years|

var ws = fs.createWriteStream('logs/rotating.log', {encoding: 'utf8'});

log.attach('rotating-file', ws, {
    type: 'plain',
    rotation: {
        path: 'logs/rotating.log',
        format: '.YYYY-MM-DD-ss',
        period: '1d',
        afterRotate: function(newPath, now) {
            fs.unlinkSync(newPath);
        }
    }
});