@zebpay/colt/README.md

LoggerSDK for Microservices with multiple adapters eg: Pino, Winston, Bunyan with support for [Mapped Diagnostics Context](http://logback.qos.ch/manual/mdc.html).

# @zebpay/colt
LoggerSDK for Microservices with multiple adapters eg: Pino, Winston, Bunyan with support for [Mapped Diagnostics Context](http://logback.qos.ch/manual/mdc.html).

### Installation
```
  npm install @zebpay/colt --save
```

### Configuration Required
```
  process.env.SERVICE = 'Payment'; // Name of the microservice
  process.env.LOG_ADAPTER = 'pino'; // any one of the pino, winston, bunyan values
  process.env.LOG_LEVEL = 'debug';
  process.env.LOG_PATH = 'logs'; // log directory path
  process.env.LOG_FILE = 'payment.log'; // log file name
  process.env.LOG_ONLY_STDOUT = 'true'; // to skip writing logs to file supports only `pino` adapter.
```

### Usage with VaniallJS
- Step1 : Configure

```
  // Entry Point of your Microservice
  // server.js
  const { Logger } = require('@zebpay/colt');

  //...other initialization code
  function configureLogger() {
    const logOptions = {
      level: process.env.LOG_LEVEL,
      logPath: process.env.LOG_PATH,
      logFile: process.env.LOG_FILE,
  };

  Logger.setLoggerOptions(logOptions);
  Logger.addAdapter(process.env.LOG_ADAPTER, Logger.setAdapter(process.env.LOG_ADAPTER));
}

// should be configured once hence in entry point file
configureLogger();

// create logger
const logger = new Logger(__filename);
logger.debug('debug message');
```

### Usage with Typescript
```
import { Logger, ILogOptions } from '@zebpay/colt';

function configureLogger() {
  const logOptions:ILogOptions = {
    level: process.env.LOG_LEVEL,
    logPath: process.env.LOG_PATH,
    logFile: process.env.LOG_FILE,
  };
  Logger.setLoggerOptions(logOptions);
  Logger.addAdapter(process.env.LOG_ADAPTER, Logger.setAdapter(process.env.LOG_ADAPTER));

  // create logger
  const logger = new Logger(__filename);
  logger.debug('debug message');
}
```

- Step2 : Create instances
```
// mymodule.js
const Logger = require('@zebpay/colt');
const logger = new Logger('mymodule');
logger.debug('debug');
logger.info('info');
logger.error('Error occurred', new Error('some error'));
logger.log('level', msg, arbitarydata, correlationIdJson)
logger.fatal('DatabaseException', errorInstance);

```

NOTE: scope will be truncated to first 6 chars for formatting.

### Application Errors vs System Errors
- *Application Errors*: Errors which are caused by any validation error or any cases which do not satisfy the business rules are categorized as application error. Always use `logger.error` for logging application logs. eg: userIsNotAuthenticated, recordsNotFound
- *System Errors*: Errors which are unhandled eg: DatabaseException, DatabaseConnectionLost or any syntax errors that may arise at runtime. Always use `logger.fatal`

### CorrelationIds
In order to add the correlationIds often known as MDC (Mapped Domain Context or Context Mapping) related to specific event it can be supplied to any of the loggers API as the last argument. CorrelationId should be a valid JSON Object. Incase if correlationIds are not passed on default correlationIds assigned during instantiation will be used.

#### Motive for implementing MDC
Often when there are lot of microservices and logs are been forwarded it becomes difficult to find the reason for error and sequence of events that might have caused the error. MDC approach helps to group together the events that are related to specific event for eg. Order Checkout failed or Payment Failure on Ecommerce site.As customer is unaware of the internal things it is wise idea to add some related information as correlationIds like { orderID: 101 } so it can be searched quickly.

#### Usage of CorrelationIds
```
 processPayment(orderData) {
   logger.debug(`Processing payment for orderID ${orderData.id}`, { orderId: orderData.id });
 }
```
#### Run Examples
```
  node examples server.js
```

#### Setup Requirement For New Relic Integration
- Install td-agent 4 [Installation](https://docs.fluentd.org/installation/install-by-deb)
- Configure td-agent.conf in /etc/td-agent/td-agent.conf

```
<source>
  @type tail
  path /tmp/logs/payment.log
  tag payment.stdout
  pos_file /tmp/payment.log.pos
  <parse>
    @type json
  </parse>
</source>

<match payment.stdout>
  @type http
  log_level debug
  endpoint https://log-api.eu.newrelic.com/log/v1
  http_method post
  content_type application/json
  headers {"x-license-key":"ENTER_LICENSE_KEY" }
  <format>
      @type json
  </format>
  <buffer>
    flush_interval 2s
  </buffer>
</match>
```

---
HappyCoding :bowtie: