Log

• Usage
• API
  • Log
  • Timer
• 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
• noop (does nothing)

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.File() })

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

If you want access to export the LEVELS, you can do so:

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

LEVELS.DEBUG //=> 'DEBUG'

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.

You can pass in tags to use to group messages together:

const log = makeLog({ tags: ['api', 'will-fix'] })

log.info('test message')
//=> `1984-10-04T06:12:43.453Z [DEBUG] #api #will-fix test message`

Tags

• may only contain alphanumeric characters and dashes
• may not contain double dashes --
• can be added with spawn() (new tags will be added to old tags)

API

Setting SILENCE_LOG to any truthy value will setup the logger to use the Noop Adapter.

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[, error[, supplementalInfo]])

Log an error message. Give an actual instance of Error as the second argument. Provide any additional information (as an object) as supplementalInfo.

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, tags])

Returns a new instance of log with the same initialization parameters as its parent.

• if a meta object is provided, it will be merged in with existing meta
• if a tags array is provided, the new tags will be merged with the old tags

Timer

Please see the Timer documentation.

Supported Platforms

Node 7+

Testing

Run tests with yarn test

Authors

• @neezer