woodchuck
TypeScript icon, indicating that this package has built-in type declarations

2.0.1 • Public • Published

woodchuck

A simple logger for the browser and node.js

Version npm

NPM

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

Package Sidebar

Install

npm i woodchuck

Weekly Downloads

2

Version

2.0.1

License

ISC

Unpacked Size

18.3 kB

Total Files

5

Last publish

Collaborators

  • tkil