@kofile/log

    4.3.0 • Public • Published

    Log

    Build Status Coverage Status Commitizen friendly semantic-release

    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 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

    Keywords

    none

    Install

    npm i @kofile/log

    DownloadsWeekly Downloads

    202

    Version

    4.3.0

    License

    MIT

    Unpacked Size

    13.4 kB

    Total Files

    8

    Last publish

    Collaborators

    • narekdaghlaryan
    • daniltarasov
    • kevinkofile
    • kofilesystems
    • neezer
    • scottkof
    • jbalfantz
    • ngraves
    • arturhovhannisyan1994volo
    • rachel-ftw
    • warrenyoungkofile