npm package: @mimik/sumologic-winston-logger
Description: Log wrapper for sumo, s3, kinesis and winston
Author: mimik technology inc
Latest version: 2.2.4

# @mimik/sumologic-winston-logger

Log wrapper for sumo, s3, kinesis and winston.

<a name="module_configuration"></a>

## 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. Both must be set as a pair; if only one is provided the
other defaults to unknown.

Resolution priority (highest to lowest):
1. Extra fields passed in the log call (trailing plain object with `serverType`/`serverId`).
2. `globalThis.serverType` / `globalThis.serverId`.
3. `SERVER_TYPE` / `SERVER_ID` environment variables.


* [configuration](#module_configuration)
    * [~checkConfig(config)](#module_configuration..checkConfig)
    * [~checkMode(mode)](#module_configuration..checkMode) ⇒ <code>Array.&lt;string&gt;</code> \| <code>null</code>

<a name="module_configuration..checkConfig"></a>

### configuration~checkConfig(config)
Validates that no property in the configuration tree is undefined.

**Kind**: inner method of [<code>configuration</code>](#module_configuration)  
**Throws**:

- <code>Error</code> If any property value is undefined.


| Param | Type | Description |
| --- | --- | --- |
| config | <code>object</code> | The configuration object to validate. |

<a name="module_configuration..checkMode"></a>

### configuration~checkMode(mode) ⇒ <code>Array.&lt;string&gt;</code> \| <code>null</code>
Parses and validates the LOG_MODE string.

**Kind**: inner method of [<code>configuration</code>](#module_configuration)  
**Returns**: <code>Array.&lt;string&gt;</code> \| <code>null</code> - Array of validated mode strings, or null if mode is falsy.  
**Throws**:

- <code>Error</code> If the mode string contains invalid values.


| Param | Type | Description |
| --- | --- | --- |
| mode | <code>string</code> \| <code>undefined</code> | 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.
For error-level logs, the full stack trace is added. When `NO_STACK` is not set to `'yes'` and the environment is development or local, method name, file name, and line number are appended to other log levels. **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.

![Screen Shot 2016-10-10 at 2.03.31 PM.png](https://bitbucket.org/repo/xbXGRo/images/3258406172-Screen%20Shot%202016-10-10%20at%202.03.31%20PM.png)

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


![Screen Shot 2016-10-10 at 2.03.57 PM.png](https://bitbucket.org/repo/xbXGRo/images/1501199325-Screen%20Shot%202016-10-10%20at%202.03.57%20PM.png)

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

![Screen Shot 2016-10-10 at 2.04.18 PM.png](https://bitbucket.org/repo/xbXGRo/images/1913524258-Screen%20Shot%202016-10-10%20at%202.04.18%20PM.png)

**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.

``` javascript
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