driftwood

logger

A namespaced stylish logger for the browser and node.

Example

var driftwood = require('driftwood')

var log = driftwood('a-module')

log.trace('It supports node and the browser!')
log.debug('You can', { also: 'send some arbitrary metadata!' })

var subLog = log('a-sub-module')

subLog.info('You can create loggers off loggers')
subLog.warn('So that your logs remain under the same top namespace')
subLog.error('Isn\'t this cool?')

Enabling log output globally:

driftwood.enable() // defaults to { '*': 'info' }
driftwood.enable({
  'foo': 'info',
  'bar:*': 'debug'
}, { persist: true }) // pass `persist: true` when in the browser to keep logging enabled across pages

Enabling log output for specific loggers or subloggers:

var log = driftwood('a-module')
var subLog = log('a-sub-module')
log.enable() // enables log and subLog

var log = driftwood('a-module')
var subLog = log('a-sub-module')
subLog.enable() // enables just subLog

log.disable() // disables log and sublog

API

driftwood.enable(config, options)

Enables all loggers globally using the optional log level config. The config is a map of name patterns to log level, defaulting to { '*': 'info' }. See below for more pattern examples. You can also pass an options object to the enable function. Currently it only supports the persist option, which lets keep logging enabled across page views (defaults to false, only supports the browser).

driftwood.disable()

Disables all loggers globally and clears the global log config.

driftwood(name, [additionalLoggers, [interceptors]])

Creates a new named log instance, optionally supplying additional loggers (e.g. sentry or devtools). additionalLoggers should be an array of functions accepting 4 arguments:

function (name, level, now, { message, error, metadata }) {
  // do whatever
}

interceptors is an array of functions used to change those arguments before they pass into the loggers:

function (name, level, now, { message, error, metadata }) {
  return [newName, newLevel, newDate, {
    message: newMessage,
    error: newError,
    metadata: newMetadata
  }]
}

For convenience, the return value can be one of:

• [name, level, now, { message, error, metadata }], to transform each of the four arguments,
• { message, error, metadata }, to transform only the main components of the message,
• message, to transform only the main message, or
• a falsey value, to transform nothing.

The interceptors are run sequentially from left to right, before any (additional) loggers.

log(name, [additionalLoggers, [interceptors]])

Creates a sub logger that inherits the namespace of its parent.

var log = driftwood('foo') // namespace will be foo
var subLog = log('bar') // namespace will be foo:bar

When using the sub logger, any additionalLoggers and/or interceptors provided will run alongside the ones provided to the original logger. When using the original logger, the new functions are not run. All interceptors run before all additional loggers. Within those groups, the original functions run before the new functions. For example:

function makeImportant(name, level, now, { message }) { return 'important ' + message }
function capitalize(name, level, now, { message }) { return message.toUpperCase() }
var log = driftwood('foo', [], [makeImportant])
var subLog = log('bar', [], [capitalize])
log.info('message')         // logs: important message
subLog.info('proclamation') // logs: IMPORTANT PROCLAMATION

log.enable(config)

Enables a specific logger with a config object (see driftwood.enable). This will be applied to the logger and all of it's descendants.

log.disable(config)

Disables a specific logger and all of it's descendants.

log.{LEVEL}(message, [message], [metadata/Error])

Logs a message at a level, optionally with a metadata object or error instance. Available levels:

• trace
• debug
• info
• warn
• error

The last argument of the log call can be an object or an instance of Error, which Driftwood will attempt to present in a more readable fashion. All preceding arguments will be concatenated together into a string.

Enabling logging

By default the logger will not output anything. You need to enable it first, as specified above. Below are some examples of log configs you can pass (you can use * as a wildcard:

• { '*': null } - will log everything at the default level (info)
• { 'foo': 'trace' } - will log anything from the logger with the name foo at the trace level
• { 'foo': 'trace', 'bar*': 'warn' } - will log foo at trace and bar* at warn
• { 'foo*': 'error', '*': 'info' } - will only log up to error from foo* and up to info from everything else

When running in the browser, you can pass a persist flag to persist the log configuration into localStorage:

driftwood.enable({ '*': 'info' }, { persist: true })

Disabling timestamps

If you prefer to not have timestamps on your logs, you can turn them off in a nodejs environment by setting the DRIFTWOOD_NO_TIMESTAMP environment variable to a truthy value.

  $ DRIFTWOOD_NO_TIMESTAMP=1 node ./myApp.js

Best practices

Create a main logger.js file in your module/app:

// logger.js
var driftwood = require('driftwood')
module.exports = driftwood('my-app')

In the main part of your app, use the main logger:

// index.js
var log = require('./logger')
log.debug('We are in the entry of the app!')

In each of your submodules, create a sub logger:

// subModuleA.js
var log = require('./logger')('sub-module-a')
log.debug('We are in a submodule of the app!')

Want to work on this for your day job?

This project was created by the Engineering team at Qubit. As we use open source libraries, we make our projects public where possible.

We’re currently looking to grow our team, so if you’re a JavaScript engineer and keen on ES2016 React+Redux applications and Node micro services, why not get in touch? Work with like minded engineers in an environment that has fantastic perks, including an annual ski trip, yoga, a competitive foosball league, and copious amounts of yogurt.

Find more details on our Engineering site. Don’t have an up to date CV? Just link us your Github profile! Better yet, send us a pull request that improves this project.