debug-logger


debug-logger
============

A thin wrapper for visionmedia/debug logger, adding levels and colored output.

Overview

visionmedia/debug is a ubitiquous logging library with 1000+ dependants. Given how widespread it is and the convenience of namespaces it is a great logger for library modules.
debug-logger is a convenience wrapper around debug that adds level based coloured output. Each instance of debug-logger will lazily instantiate several instances of debug such as namespace:info, namespace:warn, namespace:error, etc. All these are configurable. debug-logger has no dependencies besides debug.

debug-logger uses the same syntax as node.js console so you can use it as drop in replacement.
Check and run examples/console.parity.js for more details.

At AppsCot we use debug-logger in waterline-orientdb.

Instalation

``javascript
npm install debug-logger -S
`

Usage

`javascript
var log = require('debug-logger')('myapp');

log.trace("I'm a trace output");
log.debug("I'm a debug output");
log.log("I'm a log output");
log.info("I'm an info output");
log.warn("I'm a warn output");
log.error("I'm an error output");
`
!screenshot

$3


`javascript
var err = new Error('error message');
err.stack = 'the stack\nline2\nline3';

log.error('Something failed:', err);

var obj = {
anumber : 1234,
astring : 'str',
adate : new Date(),
aboolean : true
};
log.info("let's inspect 'obj'", obj);
`
!inspect error/object

$3


`javascript
log.debug.logger()("the debug instance of debug, using 'myapp:debug' namespace");
var debug = debugLogger.debug('myapp:visionmedia');
debug('Nothing tastes better than the original!');

if (log.debug.enabled()) {
// This only runs if environment variable DEBUG includes "myapp:debug" namespace
log.debug("Debug is enabled");
}
`
!enabled

$3


Full util.inspect options available at nodejs.org.
`javascript
var debugLogger = require('debug-logger');
debugLogger.inspectOptions = {
colors : true
};
log.info('By enabling colors we get this nice colored example:', {
anumber : 1234,
astring : 'str',
adate : new Date(),
aboolean : true
});
`
!inspect

$3

`javascript
debugLogger.levels.error.color = debugLogger.colors.magenta;
debugLogger.levels.error.prefix = 'ERROR ';

var customColorLog = debugLogger('myapp');
customColorLog.error("I'm a 'magenta' error output");
`
!customize log

$3


`javascript
debugLogger.levels.silly = {
color : debugLogger.colors.magenta,
prefix : 'SILLY ',
namespaceSuffix : ':silly'
};

var sillyLog = debugLogger('myapp');
sillyLog.silly("I'm a silly output");
`
!add log levels

$3


`javascript
log.log("Multiple", "arguments", "including", "objects:", { obj: 'obj'}, "makes life easier");
log.warn("util.format style string: %s, number: %d and json: %j.", "foo", 13, { obj: 'json'});
`
!multiple arguments

$3

`javascript
log.time('100-elements');
for (var i = 0; i < 100; i++) {
;
}
log.timeEnd('100-elements');

log.time('setTimeout');
setTimeout(function(){
var diff = log.timeEnd('setTimeout', 'debug');
log.trace('log.timeEnd returns diff so it can be reused:', diff);
}, 262);
`
!code time

$3


`javascript
log.dir({ foo: { bar: 1 } });
log.dir({ foo: { bar: 1 } }, { depth: 0 }, 'warn');
`
!dir inspect

$3

`javascript
log.assert(1 == 0);

// More elaborate example
var log = require('..').config({
levels: {
fatal: {
color : 5, //magenta
prefix : '',
namespaceSuffix : ':fatal',
level : 6
}
}
})('myapp');
log.assert(1 == 0, 'testing %s %d', 'log.assert', 666, 'fatal');
`
!assert

$3


By default trace, debug, log and info output to stdout while warn and error output to stderr.
This is configurable, example:
`javascript
var log = require('debug')('myapp');
log.trace("goes to stdout!");
log.debug("goes to stdout!");
log.log("goes to stdout!");
log.info("goes to stdout!");
log.warn("goes to stderr");
log.error("goes to stderr");

// outputting only to stdout
var stdout = require('debug').config({ levels: { warn: { fd: 1 }, error: { fd: 1 } } })('stdoutapp');
stdout.warn("goes to stdout!");
stdout.error("goes to stdout!");
`

$3


`sh
export DEBUG_LEVEL=info
`
Only info level and above logs will be outputted.

More examples in the examples folder.

Reference

$3

Assuming log is an instance of debug-logger (var log = require('debug-logger')('myapp');).

#### log.trace([data][, ...])
#### log.debug([data][, ...])
#### log.log([data][, ...])
#### log.info([data][, ...])
#### log.warn([data][, ...])
#### log.error([data][, ...])
Prints the data prepended by log level. If the terminal supports colors, each level will have a specific color. If an Error is provided, the toString() and call stack will be outputted. If an Object is provided the toString() and util.inspect() will be outputted. Example:
`
myapp:debug I'm a debug output +0ms
myapp:info I'm an info output +1ms
`
This function can take multiple arguments in a printf()-like way, if formatting elements are not found in the first string then util.inspect is used on each argument.

#### log([message][, ...])
Outputs the message using the root/default debug instance, without the level suffix. Example:
`
myapp I'm a root/default debug instance output +0ms
`

#### log[level].logger()
Returns the default debug instance used by level.

#### log[level].enabled()
Boolean indicating if level's logger is enabled.

#### log.time(label)
Mark a time.

#### log.timeEnd(label[, level])
Finish timer, record output. level will determine the logger used to output the result (defaults to 'log').
Return duration in ms.

#### log.dir(obj[, options][, level])
Uses util.inspect on obj and prints resulting string to the appropriate logger. This function bypasses any custom inspect() function on obj. An optional options object may be passed that alters certain aspects of the formatted string.
level will determine the logger used to output the result (defaults to 'log').

#### log.assert(value[, message][, ...][, level])
Similar to console.assert().
Additionally it outputs the error using the appropriate logger set by level (defaults to 'error').

$3

#### .config(obj)
Configures debug-logger. Returns debug-logger to allow chaining operations.

#### .debug`
Returns visionmedia/debug module.