README

@zebpay/colt

LoggerSDK for Microservices with multiple adapters eg: Pino, Winston, Bunyan with support for Mapped Diagnostics Context.

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

Usage no npm install needed!