Woodchuck NPM | npm.io

woodchuck

A simple logger for the browser and node.js

Repo: https://gitlab.com/tkil/woodchuck

  import log from 'woodchuck';

Summary

woodchuck is a lightweight abstraction for your logging needs. The goal of the project is to allow for a central logging layer for your app to interface with. This separation of concerns allows for dev'ing so you can easily slot in a final logging implementation as time allows. By default, the built in functions: console.debug, console.info, console.warn and console.error are used. This can be changed and configured at any time as requirements change and needs arise.

Basic Usage

Under the hood, woodchuck persists its config when imported to various modules. No need for instantiation, simply import where needed and start logging. It is recommended to configure options via the log.config methods in your app's startup / initialization section.

Call signature

log.<level>(<message>, <payload>)\ or\ log.<level>(<payload>)


`level`	levels are: `DEBUG`, `INFO`, `WARN`, `ERROR` and `FATAL`; in order of severity
`message`	message of the log, a string is encouraged, but the first param will except the payload)
`payload`	the payload object is free form, but keys `level`, `type`, `details`, and `data` are encouraged
	`level` - the severity of the log message
	`type` - the type of log, examples are init and api
	`details` - extra info and specific details
	`data` - useful for reporting request, response and arguments for later troubleshooting
	`error` - when invoking an error log, it is STRONGLY recomended that you attach the error to the payload - not the string message, but the actual error. This is useful as it comes with a call stack
	`message` - message should be added if the first argument to log is the payload object, eg: `log.info({ message: 'My message', type: 'api' })`

Examples

import { log } from 'woodchuck'

log.debug('My debug log!') // Must set minLogLevel to DEBUG or TRACE
// My debug log { level: 'DEBUG' }

log.info('My info log!')
// My info log! { level: 'INFO' }

log.warn('My warn log!')
// My warn log! { level: 'WARN' }

log.error('My error log!')
// My error log! { level: 'ERROR' }

log.fatal('My fatal log!')
// My fatal log! { level: 'FATAL' }

Logging to New Relic

Assumes window.newrelic.addPageAction is installed

log.nr('myFunc', 'myAction', { status: 'failure' })

// Output (stdout)
// NR: myAction @myFunc(), { status: 'failure' }

New Relic Output (in NR console)

action	functionName	status	etc
myAction	myFunc	failure	etc

Configuration

To set configuration options:

log.config({
  appName: 'My Awesome App',
  uuid: true,
  format: 'json',
  minLogLevel: log.level.info
})

Property	Default	Description
appName	`undefined`	Name of the application shown in the log
uuid	`false`	show a UUID with the log
logFormat	`'msg-json'`	'msg-json', 'json'
minLogLevel	`'INFO'`	Sets the minimum log when logging
logMaxTotalChars	`undefined`	Sets a character limit when printing logs (min 100)
logTypeFilter	`undefined`	Filter to only provided log types (note that the default is type 'general')
logTypeDefaultGeneral	`false`	Will default log type to `general` if no type is added to the payload
logCallback	`undefined`	Callback function to be invoked whenever log is sent (note that payload.level is useful to drive behavior)
logFatalFn	`console.error`	Under the hood function to be used for fatal log calls
logErrorFn	`console.error`	Under the hood function to be used for error log calls
logWarnFn	`console.warn`	Under the hood function to be used for warn log calls
logInfoFn	`console.info`	Under the hood function to be used for info log calls
logDebugFn	`console.debug`	Under the hood function to be used for debug log calls

Example of wiring in the logCallback:

  import { log } from 'woodchuck';

  log.config.setLogCallback(() => {
    console.log('You called?')
  });
  log.info('Answer the call!')

  // Answer the call! { level: 'INFO' }  
  // You called?

  log.config.setLogCallback(({ userMessage }) => {
    myUserMessageToaster.toast(userMessage)
  });
  log.warn('WARN: Bad system error', { userMessage: 'Oops something broke on our end'})

  // WARN: Bad system error { level: 'WARN', { userMessage: 'Oops something broke on our end'} }  
  // ** myUserMessageToaster.toast() would be invoked with the callback's userMessage  
  // User would see: 'Oops something broke on our end' if you set things up properly

Changelog

v2.0.1 - Optimizes internals to lighten bundle, removes one off set configs to favor log.config({})
v1.1.3 - Makes error optional on the payload object of log.warn
v1.1.1 - Log as default export instead of prop of generic default export object
v1.1.2 - Makes error optional on the payload object of log.error and log.fatal
v1.0.0 - Bump to Release Version, Adds logging to new relic