apigrate-logger

A simple logging utility, withi minimal dependencies capable of holding a transcript in memory until cleared.

By default, this logger logs to an internal NodeJS console object. The internal console object is exposed for access.

Note: this library requires NodeJS 10.x or greater

Usage

const Logger = require('@apigrate/logger')

let logger = new Logger(logLevel, opts);

In the above, logLevel may be one of:

1. error show only errors
2. warn show errors and warnings
3. info informational level logging, in addition to the above
4. debug detailed logging (typically not used in production environments), in addition to the above
5. trace even higher level of logging than debug (will not be output for injected winston loggers)

A basic example of output:

let logger = new Logger('info');

logger.error('This is an error message');
logger.warn('This is a warning message');
logger.info('This is an informational message');
logger.debug('This is debugging information');
logger.trace('This is some very detailed output seldom seen');

...would produce

ERROR: This is an error message
WARN: This is a warning message
INFO: This is an informational message

because the debug and trace messages are below the logging level of 'info'.

Options

The opts parameter is optional. It contains the following options:

omitLogLevelPrefix (boolean)

Note that the the log level prefix (e.g. INFO: , DEBUG: ,ERROR: , etc.) is prepended to messages by default. Use the omitLogLevelPrefix to omit these prefixes when using the logger.

let logger = new Logger('info', {omitLogLevelPrefix: true});

logger.info('The quick brown fox jumped over the lazy dog.');

...would produce

The quick brown fox jumped over the lazy dog.

prefix (string)

Adds an additional prefix to each logging message.

let logger = new Logger('info', {prefix: "-->"});

logger.info('The quick brown fox jumped over the lazy dog.');

...would produce

INFO: -->The quick brown fox jumped over the lazy dog.

maxMessages (number)

The maximum number of messages the logger saves in memory. When it is exceeded, the logger emits an "overflow" event, whose payload is the current internal transcript (i.e. string array of log messages). After this event is emitted, the logger internally clears out the oldest message to keep the number of array elements held internally no larger than this maxMessages value.

useSymbols (boolean)

Defaults to false. If true, the log level labels are replaced by symbols: ✖=error, ▲=warning, ◦=info, ▽=debug, ◇=trace

silent (boolean):

Defaults to false. If true, output is never logged to console. Use this if you are only interested in using the logger to build a transcript (see below).

events (boolean):

Defaults to false. If true, a logging event named 'log' is emitted with {level, indent, message} as payload for each message.

For example, you could use this to write your own event-driven transport function

logger = new Logger(5, {useSymbols: true, events: true, silent: true});
logger.on('log', ({level, indent, message})=>{
  let indentation = ''
  for(let i=0; i<indent; i++, indentation+='---');
  console.log(`${indentation} ${message}`);
});

Transcript Output

A distinguishing feature of this logger library is to provide transcript output when needed. This allows the logger to accumulate a series of log messages and then output this series as newline delimited text. This can be useful if you need a processing transcript output to an external source where piping output is not an option.

let logger = new Logger('info');
//...
logger.info('Now processing widget X.');
//...
logger.debug('Current memory footprint is 123478 bytes');
//...
logger.warn('You are getting close to your transaction limit.');
//...
logger.error('Error processing widget X. Server returned 502 indicating it is too busy.');

//...
hypotheticalNotificationService.send( logger.transcript() )

In this case, logger.transcript() would output:

INFO: Now processing widget X.
WARN: You are getting close to your transaction limit.
ERROR: Error processing widget X. Server returned 502 indicating it is too busy.

Logger stores these messages in memory. Which means you'll want to consider the following:

1. think about when you instantiate this Logger, it may make sense to only use it inside transaction processing blocks where you need a transcript of processing for a transaction.
2. if re-using the logger, use the clearLogs() function to clear the log messages stored in memory.
3. remember to make use of the maxMessages option if needed. It defaults to 100 messages stored in memory.