config() ⇒ object

The following environment variables are needed to configure logger:

| Env variable name | Description | Default | Comments | | ----------------- | ----------- | ------- | -------- | | SERVER_TYPE | type of the server that is logged | null | SERVER_ID |id of the servier that is logged | null | NODE_ENV | environment of the running instance | local | DEFAULT_ENV | LOG_LEVEL | log level of the running instance | debug | DEFAULT_LEVEL | CONSOLE_LEVEL | log level for the console of the running instance | debug | DEFAULT_LEVEL | FILTER_FILE | filename containing filter rules | null | DEFAULT_FILTER_FILE | EXIT_DELAY | delay when existing gracefully | 2000 | DEFAULT_EXIT_DELAY in ms | NO_STACK | indicatior to log th stack on all log message | no | DEFAULT_NO_STACK | LOG_MODE | string with comma separated words defining the logmode for the running instance | sumologic | DEFAULT_SUMOLOGIC (enum: awsS3, awsKinesis, sumologic, all, none)

If LOG_MODE includes sumologic the following environment variables are needed:

| Env variable name | Description | Default | Comments | | ----------------- | ----------- | ------- | -------- | | SUMO_LOGIC_ENDPOINT | url of the sumologic collector | SUMO_LOGIC_COLLECTOR_CODE | code of the sumologic collector

If LOG_MODE includes awsKinesis the following environment variables are needed:

| Env variable name | Description | Default | Comments | | ----------------- | ----------- | ------- | -------- | | KINESIS_AWS_STREAM_NAME_INFO | name of the stream for info level logs | KINESIS_AWS_STREAM_NAME_ERROR | name of the stream for error level logs | KINESIS_AWS_STREAM_NAME_OTHER | name of the stream for any other level logs | KINESIS_AWS_REGION | region of the stream | KINESIS_AWS_TIMEOUT | maximum time before flushing | 1000 | DEFAULT_KINESIS_TIMEOUT in ms | KINESIS_AWS_MAX_SIZE | maximum size of the accumulated logs before flushing | 5 | DEFAULT_KINESIS_MAX_SIZE in mB | KINESIS_AWS_MAX_EVENTS | maximum number of accumulated logs before flushing | 1000 | DEFAULT_KINESIS_MAX_EVENTS | KINESIS_AWS_ACCESS_KEY_ID | access key id of the stream | KINESIS_AWS_SECRET_ACCESS_KEY | access key secret of the stream

If LOG_MODE includes awsS3 the following environment variables are needed:

| Env variable name | Description | Default | Comments | | ----------------- | ----------- | ------- | -------- | | S3_AWS_BUCKET_NAME | name of the bucket for storing the logs | S3_AWS_REGION | region of the bucket | S3_AWS_TIMEOUT | maximum time before flushing | 5 | DEFAULT_S3_TIMEOUT in minutes | S3_AWS_MAX_SIZE | maximum size of the accumulated logs before flushing | 5 | DEFAULT_S3_MAX_SIZE in mB | S3_AWS_MAX_EVENTS | maximum number of accumulated logs before flushing | 1000 | DEFAULT_S3_MAX_EVENTS | S3_AWS_ACCESS_KEY_ID | access key id of the bucket | S3_AWS_SECRET_ACCESS_KEY | access key secret of the bucket

When LOG_MODE is none the logs will only be on console. When LOG_MODE is all LOG_MODE will be set to sumologic, awsS3.

The SERVER_TYPE and SERVER_ID are used to create the S3 filename and are inserted in the payload of the log for S3 and Kinesis. If global.serverType is set, this value is used over SERVER_TYPE. If global.serverType is set, the value of global.serverId is used over SERVER_ID.

Kind: global function
Returns: object - configuration - logger configuration.

Synopsis

Sumologic-Winston-Logger is a log wrapper that can write to multiple logging services. Currently, Winston, SumoLogic, AWS Kinesis and AWS S3 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. The package also allow some level of filtering.

Motivation

To centralize logging in a single npm node package

Installation

The logger is discoverable on npmjs.org.

To install:

npm install sumologic-winston-logger --save

Configuration - Details

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.

|Example to set the environment variable LOG_LEVEL| |---| |export LOG_LEVEL=error|

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.

|Example to set the environment varible SUMO_LOGIC_ENDPOINT| |---| |export SUMO_LOGIC_ENDPOINT=https://endpoint1.collection.us2.sumologic.com/receiver/v1/http/|

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.

|Example to set the environment varible SUMO_LOGIC_COLLECTOR_CODE| |---| |export SUMO_LOGIC_COLLECTOR_CODE=AhfheisdcOllectorCodeInSumoLogicuZw==|

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.

FILTER_FILE

FILTER_FILE is the location where the definition of the filtering configuration is. The location has to be a full file name. When the environment (NODE_ENV) in which the logger is used is prod or production, the content of the log will be filtered according to the log filtering configuration included in the file refered by the FILTER_FILE valiable. The filter will replace values of the designated property names to '-----'.

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 following ways:

• only the first is use for message
• only one object can be passed as parameter
• structured stackTrace info is added to every log except is NO_STACK is set the 'yes'
• if the last parameter is a string it will be considered as a correlationId

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');

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('this is a debug statement with 2 params and a correlationId',  { meta: 'data' }, '123456')

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

|Example| |---| |sourceCategory=local/node/challengeAPI/logs|

Stack Trace

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

License

MIT