Log
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.
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 withlog.error
-
WARN
will log messages created withlog.error
andlog.warn
-
INFO
will log messages created withlog.error
,log.warn
, andlog.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 existingmeta
- 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