@mimik/sumologic-winston-logger

Log wrapper for sumo, s3, kinesis and winston.

configuration

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 | Set to 'yes' to suppress stack info on non-error logs | 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.

• configuration
  • ~checkConfig(config)
  • ~checkMode(mode) ⇒ Array.<string> | null

configuration~checkConfig(config)

Validates that no property in the configuration tree is undefined.

Kind: inner method of configuration
Throws:

• Error If any property value is undefined.

| Param | Type | Description | | --- | --- | --- | | config | object | The configuration object to validate. |

configuration~checkMode(mode) ⇒ Array.<string> | null

Parses and validates the LOG_MODE string.

Kind: inner method of configuration
Returns: Array.<string> | null - Array of validated mode strings, or null if mode is falsy.
Throws:

• Error If the mode string contains invalid values.

| Param | Type | Description | | --- | --- | --- | | mode | string | undefined | Comma-separated list of log modes. |

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, go to: 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 a FILTER_FILE is specified, 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,
• one metadata object can be passed as a parameter; its properties are included in the log entry,
• 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,
• if the last parameter is a plain object and there is already an earlier metadata object, its properties are merged into the log entry at the top level (alongside serverType/serverId) — this is the extra fields feature.

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

// Extra fields — the trailing plain object is merged into the log entry at the top level.
// Works with or without a correlationId.
logger.info('this is an info statement with extra fields', { meta: 'data' }, { type: 'myService' });
logger.info('this is an info statement with extra fields and a correlationId', { meta: 'data' }, '123456', { type: 'myService', version: '1.0' });

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|

Logger API

In addition to the standard Winston log methods (error, warn, info, verbose, debug, silly), the logger exposes the following:

| Property / Method | Description | | --- | --- | | logger.LEVELS | Array of supported log levels in severity order: ['error', 'warn', 'info', 'verbose', 'debug', 'silly'] | | logger.flush() | Flushes all active transports (SumoLogic, S3, Kinesis). Completes asynchronously after the configured FLUSH_EXIT_DELAY. | | logger.flushAndExit(code) | Flushes all active transports and then calls process.exit(code). A safety-net timer (FLUSH_EXIT_TIMEOUT) ensures the process exits even if a transport never responds. |

Stack Trace

All calls to error() include the stack trace. When NO_STACK is not set to 'yes' and the environment is development or local, other log levels will include a line number and file name.

License

MIT