@kofile/log

Log

• Usage
• API
  • Log
  • Timer
• Why?
• Supported Platforms
• Testing
• Authors

Log is a thin wrapper around a logging engine. It supports

• limiting log output based on log level
• creating high-resolution timers for instrumenting code
• any engine with the appropriate adapater

At present, these adapters are included by default:

• console

You can write your own to support these other logging engines:

• pino
• bunyan
• winston

Usage

Create a log:

const { makeLog } = require('@kofile/log')

const log = makeLog()

By default, your adapter will be console and the log level will be set to DEBUG.

See available log levels with

Log.LEVELS //=> ERROR, WARN, INFO, & DEBUG

You can pass in a different level when you instantiate your log:

const log = makeLog({ level: Log.LEVELS.INFO })

If you want to use another adapter, pass it in to the constructor as well:

const { Adapters } = require('@kofile/log')

const log = makeLog({ adapter: new Adapters.Pino() })

NOTE The pino adapter currently doesn't exist. :wink:

You can also pass in a meta object, which will be rendered with every log message as stringified JSON:

const meta = { foo: 'bar' }
const log = makeLog({ meta })

log.info('test message')
//=> `1984-10-04T06:12:43.453Z [DEBUG] test message -- {"foo":"bar"}`

Meta must be an object.

API

Log

log.level

Returns the configured log level.

• ERROR will only log messages created with log.error
• WARN will log messages created with log.error and log.warn
• INFO will log messages created with log.error, log.warn, and log.info
• DEBUG will log all messages

Use Log.LEVELS when specifying levels for log initialization.

log.level = newLevel

Set the given level as the new log level for this instance.

Log level must be one of Log.LEVELS.

log.adapter

Returns the adapter used by this instance of Log.

log.defaultTimerCallback = cb

Set the given callback function cb as the default callback function for timers to execute when they complete.

The callback function will receive (message, [durationSeconds, durationNanoseconds]).

Example:

const { makeLog } = require('@kofile/log')
const statsd = require('./statsd')

const log = makeLog()

const timerCallback = (message, duration) => {
  statsd.timing(message, duration)
}

log.defaultTimerCallback = timerCallback

const timer1 = log.makeTimer('timer-1')
const timer1 = log.makeTimer('timer-2')
const timer1 = log.makeTimer('timer-3')

timer1.start()
timer2.start()
timer3.start()

timer1.end() //=> calls timerCallback with details for timer1
timer2.end() //=> calls timerCallback with details for timer2
timer3.end() //=> calls timerCallback with details for timer3

log.error(message, [...args])

Log an error message. Any additional arguments are passed as-is to the adapter.

log.warn(message, [...args])

log.info(message, [...args])

log.debug(message, [...args])

log.makeTimer(key, [callback])

Returns a preconfigured instance of Timer.

If the optional callback is provided, when the timer instance ends, the callback will be invoked.

log.spawn([meta])

Returns a new instance of log with the same initialization parameters as its parent, and merges in meta if meta is given.

Timer

Why?

Many of the aforementioned loggers are good loggers, but in choosing one, we lock ourselves into a given API. This library serves as an abstraction on top of any logging engine to provide a stable, consistent API to develop against.

Supported Platforms

Node 7+

Testing

Run tests with yarn test

Authors

• @neezer