README.md

captains-log

   

Lightweight logger with a simple pass-through configuration for use with fancier logging libraries. Used by the Sails framework. Optional support for colorized output, custom prefixes, and log levels (using npm's logging conventions.)

Installation

$ npm install captains-log

Usage

var log = require('captains-log')();

log('hi');

Logging at a particular level

By default, if you just call log(), captains-log will write your log output at the "debug" log level. You can achieve the same effect by writing log.debug().

IMPORTANT NOTE: npm calls this level log.http(), but we call it debug. If you use log(), the logger sees this as a call to log.debug())

Here are all of the log-level-specific methods which are available in captains-log out of the box:

log.silly();

log.verbose();

log.info();

log.debug()

log.warn();

log.error();

Configuring a custom logger

To use a different library, overrides.custom must already be instantiated and ready to go with (at minimum) an n-ary .debug() method.

Implementing the simplest possible override

var log = require('captains-log')({ custom: customLogger });

log('hello', 'world');
// yields => "Hello world"

This assumes customLogger works as follows:

customLogger.debug()
customLogger.debug('blah')
customLogger.debug('blah', 'foo')
customLogger.debug('blah', 'foo', {bar: 'baz'})
customLogger.debug('blah', 'foo', {bar: 'baz'}, ['a', 3], 2, false);
// etc.

For example:

var customLogger = console.log.bind(console);

Configure inspect

When an object is passed, and inspect is set to true (it is true, by default), you can configure the inner inspect function options, by passing an inspectOptions parameter:

var log = require('captains-log')({inspectOptions: {colors: true, depth: null}});

log('hello', 'world', {this:'is', a: 'nice', object: new Date()});

The previous code renders the object with colors.

Using Winston

Formerly, this module encapsulated winston, a popular logger by @indexzero and the gals/guys over at Nodejitsu. But eventually, we made Winston optional to make captains-log as lightweight as possible and reduce the number of npm installs and require()s necessary for its usage in other modules.

But Winston is awesome! And it's a great fit for many apps, giving you granular control over how log output is handled, including sending emails, logging to multiple transports, and other production-time concerns.

To boot up a captains-log that writes to Winston, do the following:

var log = require('captains-log')({
  custom: new (require('winston').Logger)({
    levels     : ...,
    transports : ...
  })
});

Why use a custom logger?

It it can useful to configure a custom logger-- particularly for regulatory compliance and organizational requirements (i.e. if your company is using a particular logger in other apps.) In the context of Sails, configuring a custom logger also allows you to intercept all log messages automatically created by the framework, which is a quick way to set up email notifications about errors and warnings.

That said, don't feel like you have to use a custom logger if you want these sorts of notifications. In fact, there are usually more straightforward ways to implement features like Slack, SMS, or email notifications. For example, in Sails, consider customizing your responses/serverError.js file. Or check out a product like Papertrail.

Help

If you have further questions or are having trouble, click here.

Bugs  

To report a bug, click here.

Contributing  

Please observe the guidelines and conventions laid out in the Sails project contribution guide when opening issues or submitting pull requests.

License

This package, like the Sails framework, is free and open-source under the MIT License.