pretty-good-log v1.1.0

pretty-good-log

pretty-good-log is a logging system. It's just a tool that I've been working on while working on game projects, but it's starting to see use in some professional projects as well, so I thought I'd polish it up and share it.

It was written with the goal of readable and dynamically filterable console output, while keeping a slim API that doesn't require a bunch of boilerplate to get going. Configurability is good, but only to the extent that it doesn't get in the way of the first two.

Speed hasn't been a focus; so far pretty-good-log's applications have not seen js-bound logging as a bottleneck. If you need a hyper-performant logging library, look elsewhere! (or contribute!) But if what you're after is just something nice and easy, maybe pretty-good-log is a good fit.

Usage

Install via yarn or npm:

yarn add pretty-good-log
# or
npm install --save pretty-good-log

The recommended way to use pretty-good-log is to require it at the top of each module and initialise it with the name of that module, like so:

// in physics.js
var log = require('pretty-good-log')('physics');

log('Calling the log object directly is an alias to log.info');
// will log:
// [xx:xx:xx][physics] Calling the log object directly is an alias to log.info

Different logging levels can be used:

log.debug('log.debug is the lowest level of logging');
log.info('log.info can still be called');
log.warn('log.warn will print to stderr by default');
log.error('log.error is the highest level of logging');

And you can pass in a bunch of arguments like with console.log! You don't need to manually stringify or concatenate:

log('Loaded user', query.person, 'for account', query.account);

Multiple instances of identical log lines will be rolled up so that logs in inner loops don't spam up the console:

for(var i = 0; i < 10; ++i) { log('loop'); }
// outputs
// [xx:xx:xx][demo] loop --x10

Neat!

Read on for internals and how to configure things.

Detailed API

Modules

Functions

formatter

• formatter
  • ~formatter
    • .string()
    • .object()
    • .number()
    • .undefined()
    • .channel()
    • .format()

formatter~formatter

Default formatter object. By default, loggers will call this object's format and channel functions, while the other functions are used to format different types of data. You can override this object's properties to provide your own formatters, or replace it entirely with any object that provides the format and channel functions.

Kind: inner property of formatter

• ~formatter
  • .string()
  • .object()
  • .number()
  • .undefined()
  • .channel()
  • .format()

formatter.string()

Returns the string itself.

Kind: static method of formatter

formatter.object()

Returns the result of util.inspect on a, in red for errors and green otherwise.

Kind: static method of formatter

formatter.number()

Returns string representation of the given number in purple.

Kind: static method of formatter

formatter.undefined()

Returns 'undefined' in yellow.

Kind: static method of formatter

formatter.channel()

Returns the channel decorated appropriately and then padded to 10 characters.

Kind: static method of formatter

formatter.format()

Formats data for concatenation.

Kind: static method of formatter

logger

logger~logger(channelName)

Create a new channel on the singleton logger. This is the main interface to the whole module -- logs should be written into created channels, and the logger itself should be configured through the config property of this function (which is an instance of MultiplexTransport).

Kind: inner method of logger

MultiplexTransport(transports)

A transport that simply passes through log calls to an array of children.

Kind: global function

multiplexTransport.log()

Pass the log through to the child transports

Kind: instance method of MultiplexTransport

ConsoleTransport(out, err)

A transport that formats all arguments nicely and prints them to the appropriate stream. If called with no arguments, out and err default to stdout and stderr respectively. If only out is provided, ALL log levels will be sent to that stream.

Kind: global function

• ConsoleTransport([out], [err])
  • .note(note)
  • .log(channel, level, args)

consoleTransport.note(note)

Remove the existing note if there is one and replace it with the given note.

Kind: instance method of ConsoleTransport

consoleTransport.log(channel, level, args)

Format all console arguments into a string and then log it to the appropriate stream.

Kind: instance method of ConsoleTransport