diff --git a/readme.md b/readme.md index 3d3d701..3df3910 100644 --- a/readme.md +++ b/readme.md @@ -1,36 +1,49 @@ # dev/null because logging to dev/null is webscale -Current build status: [![BuildStatus](https://secure.travis-ci.org/observing/devnull.png)](http://travis-ci.org/observing/devnull) +Current build status: [![BuildStatus](https://secure.travis-ci.org/observing/devnull.png?branch=master)](http://travis-ci.org/observing/devnull) ### Introduction -**devnull** is an feature rich logging library for Node.js. It was designed from the ground up to assist you during development and be powerful in production. It works just like the regular `console.log` statements you have in code, it uses the same formatter for logging to the terminal and has the same API. It's basically a cherry on the top :). +**devnull** is an feature rich logging library for Node.js. It was designed from +the ground up to assist you during development and be powerful in production. It +works just like the regular `console.log` statements you have in code, it uses +the same formatter for logging to the terminal and has the same API. It's +basically a cherry on the top :). ### Namespacing -The module automatically adds intelligent namespaces to all your log calls so you can easily track back those log statements in your code without having to remember where you placed them. +The module automatically adds intelligent namespaces to all your log calls so +you can easily track back those log statements in your code without having to +remember where you placed them. ### Evented -The logger is build on top of the EventEmitter prototype. This allows you to handle all critical log messages in one central location. You might want to be notified when you application starts emitting critical errors. I know I would. +The logger is build on top of the EventEmitter prototype. This allows you to +handle all critical log messages in one central location. You might want to be +notified when you application starts emitting critical errors. I know I would. ### Multiple transports -It supports different logging transports. You might want to log to the terminal in production but to MongoDB in production so you have a centralized location of all your logs. Each logger can have multiple transports. +It supports different logging transports. You might want to log to the terminal +in production but to MongoDB in production so you have a centralized location of +all your logs. Each logger can have multiple transports. ![output preview](http://f.cl.ly/items/2t461h193a2D1t0f0k0q/Screen%20Shot%202011-12-15%20at%2022.29.14.PNG) -The image above is the result of the [example/logging.js](https://github.com/observing/devnull/blob/master/example/logging.js) +The image above is the result of the +[example/logging.js](https://github.com/observing/devnull/blob/master/example/logging.js) ## Installation -The module is tested against Node.js 0.4 and 0.6 and can be installed using the Node.js Package Manager, also known as NPM. +The module is tested against Node.js 0.4 and 0.6 and can be installed using the +Node.js Package Manager, also known as NPM. ``` npm install devnull ``` -If you don't have NPM installed on your system you can get it at [http://npmjs.org](http://npmjs.org) +If you don't have NPM installed on your system you can get it at +[http://npmjs.org](http://npmjs.org) ## API @@ -40,36 +53,48 @@ You can either initialize the default logger: ```js var Logger = require('devnull') - , logger = new Logger + , logger = new Logger(); -logger.log('hello world') -logger.info('pew pew') -logger.error('oh noes, something goes terribly wrong') +logger.log('hello world'); +logger.info('pew pew'); +logger.error('oh noes, something goes terribly wrong'); ``` Or configure a customized instance using the options argument: ```js var Logger = require('devnull') - , logger = new Logger({ timestamp: false }) + , logger = new Logger({ timestamp: false }); -logger.log('hello world') +logger.log('hello world'); ... ``` The following options are available for configuring your customized instance: -- **env** either development of production. Default is based on the isAtty check of the process.stdout. -- **level** Only log statements that are less than this level will be logged. This allows you to filter out debug and log statements in production for example. Default is 8. -- **notification** At what log level should we start emitting events? Default is 1. -- **namespacing** At what log level should we start generating namespaces (uses callsite based stacktraces)? Defaults to 8. -- **timestamp** Should we prepend a timestamp to the log message? Logging is always done asynchronously so it might be that log messages do not appear in order. A timestamp helps you identify the order of the logs. Default is true. -- **pattern** The pattern for the timestamp. Everybody prefers it's own pattern. The pattern is based around the great [140bytes date entry](https://gist.github.com/1005948) but also allows functions to be called directly. Default is the util.log format that Node.js adopted. -- **base** Should the logger be configured with the base transport (log to process.stdout)? Default is true. +- **env** either development of production. Default is based on the isAtty check + of the process.stdout. +- **level** Only log statements that are less than this level will be logged. + This allows you to filter out debug and log statements in production for + example. Default is 8. +- **notification** At what log level should we start emitting events? Default is + 1. +- **namespacing** At what log level should we start generating namespaces (uses + callsite based stacktraces)? Defaults to 8. +- **timestamp** Should we prepend a timestamp to the log message? Logging is + always done asynchronously so it might be that log messages do not appear in + order. A timestamp helps you identify the order of the logs. Default is true. +- **pattern** The pattern for the timestamp. Everybody prefers it's own pattern. + The pattern is based around the great [140bytes date + entry](https://gist.github.com/1005948) but also allows functions to be called + directly. Default is the util.log format that Node.js adopted. +- **base** Should the logger be configured with the base transport (log to + process.stdout)? Default is true. ### .configure(env, fn) -Configure the module for different environments, it follows the same API as Express.js. +Configure the module for different environments, it follows the same API as +Express.js. #### Arguments @@ -80,28 +105,30 @@ _fn_ (function) callback ```js var Logger = require('devnull') - , logger = new Logger + , logger = new Logger(); // runs always logger.configure(function () { - logger.log('running on the things') -}) + logger.log('running on the things'); +}); // only runs in production logger.configure('production', function () { - logger.log('running in production') -}) + logger.log('running in production'); +}); logger.configure('development', function () { - logger.log('running in development') -}) + logger.log('running in development'); +}); ``` ### .use(Transport, options) -Adds another transport to the logger. We currently ship 2 different transports inside the module (stream and mongodb). +Adds another transport to the logger. We currently ship 2 different transports +inside the module (stream and mongodb). -These transports can be required using `require('devnull/transports/')`. +These transports can be required using +`require('devnull/transports/')`. #### Arguments @@ -112,24 +139,24 @@ _options_ (object) options for the transport. ```js var Logger = require('devnull') - , logger = new Logger + , logger = new Logger(); // use the stream transport to log to a node.js stream logger.use(require('devnull/transports/stream'), { - stream: require('fs').createWriteStream('logger.log') -}) + stream: require('fs').createWriteStream('logger.log'); +}); // also exports all transports :) -var transport = require('devnull/transports') +var transport = require('devnull/transports'); // and add mongodb to production logging logger.configure('production', function () { logger.use(transport.mongodb, { url: 'mongodb://test:test@localhost:27017/myapp' - }) -}) + }); +}); -logger.warning('hello world') +logger.warning('hello world'); ``` ### .remove(Transport) @@ -145,15 +172,19 @@ _Transport_ (Transport) a transport ```js var Logger = require('devnull') , logger = new Logger({ base: false }) - , transports = require('devnull/transports') + , transports = require('devnull/transports'); -logger.use(transports.stream) -logger.remove(transports.stream) +logger.use(transports.stream); +logger.remove(transports.stream); ``` ### .on(Event, fn) -Because the Logger is build upon the EventEmitter you can also start listening for log messages. This is set to warning levels by default in the configuration options. In addition to listening to the log message you can also listen to the events of the transports. These are prefixed with `transport:`. The following events are emitted: +Because the Logger is build upon the EventEmitter you can also start listening +for log messages. This is set to warning levels by default in the configuration +options. In addition to listening to the log message you can also listen to the +events of the transports. These are prefixed with `transport:`. The following +events are emitted: - All the types (alert, critical etc) @@ -172,15 +203,15 @@ _fn_ (function) callback, receives _args_ (array), _stack_ (stack/callsite) ``` var Logger = require('devnull') - , logger = new Logger + , logger = new Logger(); logger.on('error', function (args, stack) { // args = foo bar, 1 // stack = stack trace that we used to generate the namespace email('errors@pew.pew', 'error!', args); -}) +}); -logger.error('foo bar', 1) +logger.error('foo bar', 1); ``` ### .ignore(file) @@ -196,7 +227,7 @@ _env_ (string) file ```js var Logger = require('devnull') - , logger = new Logger + , logger = new Logger(); logger.ignore('my_other_module.js'); ``` @@ -213,7 +244,7 @@ _env_ (string) file ```js var Logger = require('devnull') - , logger = new Logger + , logger = new Logger(); logger.ignore('my_other_module.js'); logger.unignore('my_other_module.js'); @@ -221,7 +252,8 @@ logger.unignore('my_other_module.js'); ### Logging methods and levels -The logger has the following methods available for logging. The () is the log level. +The logger has the following methods available for logging. The () is +the log level. - alert (0) - critical (1)