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