config() ⇒ object

The following environment variables are used to configure the logger:

| Env variable name | Description | Default | Comments | | ----------------- | ----------- | ------- | -------- | | SERVER_TYPE | Type of the server being logged | null | | | SERVER_ID | ID of the server being logged | null | | | NODE_ENV | Environment of the running instance | local | | | LOG_LEVEL | Log level for the running instance | debug | | | CONSOLE_LEVEL | Console log level | debug | | | FILTER_FILE | Filename containing filter rules | null | | | FLUSH_EXIT_DELAY | Delay for flushing the transports and exiting | 2000 | in millisecond | | FLUSH_EXIT_TIMEOUT | Timeout safety net in case flush never completes | 5000 | in millisecond | | NO_STACK | Whether to include call stacks in all log messages | yes | expected: yes/no | | LOG_MODE | Comma-separated list defining the log mode/backends | none | enum: awsS3, awsKinesis, sumologic, all, none |

If LOG_MODE includes sumologic, the following environment variables are required:

| Env variable name | Description | Default | Comments | | ----------------- | ----------- | ------- | -------- | | SUMO_LOGIC_ENDPOINT | URL of the Sumo Logic collector | | | | SUMO_LOGIC_COLLECTOR_CODE | Code of the Sumo Logic collector | | |

If LOG_MODE includes awsKinesis, the following environment variables are required:

| Env variable name | Description | Default | Comments | | ----------------- | ----------- | ------- | -------- | | KINESIS_AWS_STREAM_NAME_INFO | Stream name for info level logs | | | | KINESIS_AWS_STREAM_NAME_ERROR | Stream name for error level logs | | | | KINESIS_AWS_STREAM_NAME_OTHER | Stream name for any other level | | | | KINESIS_AWS_REGION | AWS region of the stream | | | | KINESIS_AWS_TIMEOUT | Max time before sending events to Kinesis | 5 | in minute | | KINESIS_AWS_MAX_SIZE | Max size of the data before sending to Kinesis | 5 | in MB | | KINESIS_AWS_MAX_EVENTS | Max number of events before sending to Kinesis | 1000 | | | KINESIS_AWS_MAX_RETRIES | Max retries to connect to Kinesis | 4 | | | KINESIS_AWS_ACCESS_KEY_ID | AWS access key ID | | | | KINESIS_AWS_SECRET_ACCESS_KEY | AWS secret access key | | | | KINESIS_AWS_HTTP_OPTIONS_SOCKET_TIMEOUT | Socket timeout for the http handler | 5000 | in millisecond | | KINESIS_AWS_HTTP_OPTIONS_CONNECTION_TIMEOUT | Connection timeout for the http handler | 5000 | in millisecond |

If LOG_MODE includes awsS3, the following environment variables are required:

| Env variable name | Description | Default | Comments | | ----------------- | ----------- | ------- | -------- | | S3_AWS_BUCKET_NAME | S3 bucket name for storing logs | | | | S3_AWS_REGION | AWS region of the bucket | | | | S3_AWS_TIMEOUT | Max time before sending events to S3 | 5 | in minute | | S3_AWS_MAX_SIZE | Max size of the data before sending to S3 | 5 | in MB | | S3_AWS_MAX_EVENTS | Max number of events before sending to S3 | 1000 | | | S3_AWS_ACCESS_KEY_ID | AWS access key ID | | | | S3_AWS_SECRET_ACCESS_KEY | AWS secret access key | | |

When LOG_MODE is none, logs are written to the console only. When LOG_MODE is all, it is equivalent to sumologic,awsS3 (does not include awsKinesis).

SERVER_TYPE and SERVER_ID are used to build the S3 filename and are included in the log payload for S3 and Kinesis. If globalThis.serverType is set, it overrides SERVER_TYPE. If globalThis.serverId is set, it overrides 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 stackTrace info. StackTrace information is included in all log entries. For error-level logs, the full stack trace is added. For other log levels, method name, file name, and line number are appended. Line formatting is not currently configurable. The package also allows 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 @mimik/sumologic-winston-logger --save

Configuration - Details

The following sections describe 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 variable 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 variable 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 encoded 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 referred by the FILTER_FILE variable. 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 arguments 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 argument is used as the message
• only one object can be passed as parameter
• structured stackTrace info is added to every log except when NO_STACK is set to 'yes'
• if the last parameter is a string it will be considered as a correlationId

Logging Examples

Listing 2 below shows 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.

import logger from '@mimik/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

Tailing 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 calls to error() include the stack trace. All other log levels will include a line number and file name.

License

MIT