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 = log = '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 = log = 'name'; log; log; log; log; log;
If you want to log to a file simply open a writeable stream with fs
:
var blockLog = log = 'name'; fs = ; log; log;
Express.js
Usage withblockLog
comes with a middleware wrapper for express.js
applications.
//... app;
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;
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;
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; log;
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; log;
NOTE: new file streams are created using utf8 encoding
ROADMAP
License
MIT
© 2014 Robin Thrift