h2-logger-for-sumologic v1.0.1

Synopsis

H2-Logger is a log wrapper that can write to multiple logging services. Currently, Winston and SumoLogic are supported. The package also adds strackTrace info. StackTrace information gets tacked on to Sumologic calls, In addition and method, module, and line info or concatenated is added to the end of winston lines. Line formatting is not currently configrable.

Motivation

To centralize logging in a single npm node package

Current Version

1.0.0

Installation

The logger is discoverable on npmjs.org.

To install:

npm install h2-logger --save

JavaScript/ECMAScript support

The Sumolog-Winston-Logger support two version of ECMAScript. ECMAScript 6 is the primary version that the logger supports. (This logger is written in ECMAScript 6.) ECMAScript 5 is supported also when run against version of Node using versions of V8 3.x and below.

You indicate the version of ECMAScript that the logger is to run under via the require declaration as shown below in Listing 1.

// to load ES6
const logger = require('sumologic-winston-logger').ES6;

// to load ES5
const logger = require('sumologic-winston-logger').ES5;

Listing 1: Declaring the version of ECMAScript in a require statement

Configuration - Environment Variables:

The logger expects certain environment variables to be present in order to be operational. If they environment variables are not set, the logger will not load.

The expected environment variables are:

• LOG_LEVEL
• SUMO_LOGIC_ENDPOINT
• SUMO_LOGIC_COLLECTOR_CODE

The following sections decribe the details of each of the environment variables listed above.

LOG_LEVEL

Log levels supported inclusively according to the following list, as borrowed from winston:

• silly
• verbose
• debug
• info
• warn
• error

Thus, if one declares a log level of silly, the levels error, warn, info, debug, and verbose are reported too.

SUMO_LOGIC_ENDPOINT

The endpoint defined in SumoLogic to where log information will be sent. See the section, Finding SumoLogic endpoint and collector code, below to find the value to assign to this environment variable.

SUMO_LOGIC_COLLECTOR_CODE

The collector code as defined in SumoLogic. The Collector Code is the Base64 string that appears after the last slash in the URL defined in the SumoLogic Control Panel.

To learn more about setting this environment variable, see the section, Finding SumoLogic endpoint and collector code, below.

Finding SumoLogic endpoint and collector code

To find the values that you will apply the environment variables, SUMO_LOGIC_ENDPOINT and SUMO_LOGIC_COLLECTOR_CODE, in the SumoLogic Control Panel, goto: Manage > Collection, and get the source category

Figure 1: Select the Manage -> Collection to display a list of collectors in force

Figure 2: Click the link, Show URL to display the URL configuration for the given collector

Figure 3: The HTTP Source Address dialog shows collector's URL. The collector code is a Base64 string appended after the last slash in the Source Address URL

The endpoint is the part of the url that ends with a slash. i.e. https://endpoint1.collection.us2.sumologic.com/receiver/v1/http/

The collector code is the Base64 encrypted part of the URL that follows the last slash in the url.

Sample Use

The intent of this package is to support all the behavior common to console.log while also including support of multiple arguements and all data types.

Formatting console logs is left to winston, except that some stackTrace info is appended to each line.

Formatting of SumoLogic logs is handled by this module in the foloowing ways:

• strings from multiple parameters are join with a space
• if multiple objects are passed in, their keys and values are combined, which makes data more searchable on SumoLogic
• structued stackTrace info is added to every log.

If a function is provided as the last argument, that argument will be used as a callback.

Both SumoLogic and Winton return callbacks, so the results will be combined into one object. Winston resolves with the log level. Sumologic resolves with an empty string. example:

{ 
  winston: 'debug',
  sumoLogic: ''
}

Logging Examples

Listing 2 below show you how to declare a logger to run under ECMAScript 6 and then log using the various log levels supported by the Sumologic-Winston-Logger.

const logger = require('sumologic-winston-logger').ES6;

logger.log(debug', 'this is a debug statement using log');
logger.debug({ message: 'this is a debug statement using an object'});
logger.error('this is an error statement');
logger.error(new Error('this is an error statement'));
logger.warn('this is a warning statement', { meta: 'data' });
logger.info('this is an info statement', { meta: 'data' });
logger.verbose('this is a verbose statement');
logger.silly('this is a silly statement o_O');
logger.debug('this is a debug statement with 2 params', { meta: 'data' });
logger.debug('debug', 'this is a debug with 4 params', { meta: 'data' }, (err, data) => {
    if (err) doSomething(err);
});

Listing 2: Examples of using the logger to make a log entry, using the log levels, log, silly, verbose, debug, info, warn, and error

By default, log entries are logged to console. The log() method is also supported, and adds a level parameter in position 1.

Tailing

Trailing allows you to scroll through log output in real time. You can trail log data in SumoLogic.

To trail in SumoLogic go to Search > Live Tail in the SumoLogic user interface and enter sourceCategory=<source category> in the search bar, where <source category> is the log you want to trail. Then click, Run

Stack Trace

All logging to error() are added the stack trace. All other log levels will include a line number and file name.

License

ISC