@villedemontreal/logger 6.5.1

package/src/logger.ts

@@ -0,0 +1,551 @@
+import { LogLevel, utils } from '@villedemontreal/general-utils';
+import * as fs from 'fs';
+import * as http from 'http';
+import * as _ from 'lodash';
+import * as path from 'path';
+import * as pino from 'pino';
+import * as pinoMultiStreams from 'pino-multi-stream';
+import { LoggerConfigs } from './config/configs';
+import { constants } from './config/constants';
+
+const createRotatingFileStream = require('rotating-file-stream').createStream;
+
+// ==========================================
+// We export the LogLevel
+// ==========================================
+export { LogLevel } from '@villedemontreal/general-utils';
+
+// ==========================================
+// This allows us to get the *TypeScript*
+// informations instead of the ones from the
+// transpiled Javascript file.
+// ==========================================
+require('source-map-support').install({
+  environment: 'node'
+});
+
+// ==========================================
+// App infos
+// ==========================================
+const packageJson = require(`${constants.appRoot}/package.json`);
+const appName = packageJson.name;
+const appVersion = packageJson.version;
+
+let loggerInstance: pino.Logger;
+let loggerConfigs: LoggerConfigs;
+let libIsInited: boolean = false;
+
+// Keeping track of all created loggers
+const loggerChildren: Logger[] = [];
+
+let multistream: any;
+
+/**
+ * A Logger.
+ */
+export interface ILogger {
+  debug(messageObj: any, txtMsg?: string): void;
+  info(messageObj: any, txtMsg?: string): void;
+  warning(messageObj: any, txtMsg?: string): void;
+  error(messageObj: any, txtMsg?: string): void;
+  log(level: LogLevel, messageObj: any, txtMsg?: string): void;
+}
+
+/**
+ * Converts a Pino level to its number value.
+ */
+export const convertPinoLevelToNumber = (pinoLogLevel: pino.Level): number => {
+  return pino.levels.values[pinoLogLevel];
+};
+
+/**
+ * Converts a local LogLevel to a Pino label level.
+ */
+export const convertLogLevelToPinoLabelLevel = (logLevel: LogLevel): pino.Level => {
+  let pinoLevel: pino.Level = 'error';
+  if (logLevel !== undefined) {
+    if ((logLevel as LogLevel) === LogLevel.DEBUG) {
+      pinoLevel = 'debug';
+    } else if (logLevel === LogLevel.INFO) {
+      pinoLevel = 'info';
+    } else if (logLevel === LogLevel.WARNING) {
+      pinoLevel = 'warn';
+    } else if (logLevel === LogLevel.ERROR) {
+      pinoLevel = 'error';
+    }
+  }
+  return pinoLevel;
+};
+
+/**
+ * Converts a local LogLevel to a Pino number level.
+ */
+export const convertLogLevelToPinoNumberLevel = (logLevel: LogLevel): number => {
+  return convertPinoLevelToNumber(convertLogLevelToPinoLabelLevel(logLevel));
+};
+
+/**
+ * Gets the path to the directory where to log, if required
+ */
+const getLogDirPath = (loggerConfig: LoggerConfigs): string => {
+  let logDir: string = loggerConfig.getLogDirectory();
+
+  if (!path.isAbsolute(logDir)) {
+    logDir = path.join(process.cwd(), logDir);
+  }
+  logDir = path.normalize(logDir);
+
+  if (!fs.existsSync(logDir)) {
+    fs.mkdirSync(logDir);
+  }
+
+  return logDir;
+};
+
+/**
+ * Initialize the logger with the config given in parameter
+ * This function must be used before using createLogger or Logger Class
+ * @param {LoggerConfigs} loggerConfig
+ * @param {string} [name='default']
+ * @param force if `true`, the logger will be initialized
+ *   again even if it already is.
+ */
+export const initLogger = (loggerConfig: LoggerConfigs, name = 'default', force: boolean = false) => {
+  if (loggerInstance && !force) {
+    return;
+  }
+
+  const streams: pinoMultiStreams.Streams = [];
+  loggerConfigs = loggerConfig;
+  // ==========================================
+  // Logs to stdout, potentially in a human friendly
+  // format...
+  // ==========================================
+  if (loggerConfig.isLogHumanReadableinConsole()) {
+    const prettyStream = pinoMultiStreams.prettyStream();
+    streams.push({
+      level: convertLogLevelToPinoLabelLevel(loggerConfig.getLogLevel()),
+      stream: prettyStream
+    });
+  } else {
+    streams.push({
+      level: convertLogLevelToPinoLabelLevel(loggerConfig.getLogLevel()),
+      stream: process.stdout
+    });
+  }
+
+  // ==========================================
+  // Logs in a file too?
+  // ==========================================
+  if (loggerConfig.isLogToFile()) {
+    const rotatingFilesStream = createRotatingFileStream('application.log', {
+      path: getLogDirPath(loggerConfig),
+      size: loggerConfig.getLogRotateThresholdMB() + 'M',
+      maxSize: loggerConfig.getLogRotateMaxTotalSizeMB() + 'M',
+      maxFiles: loggerConfig.getLogRotateFilesNbr()
+    });
+
+    // ==========================================
+    // TODO
+    // Temp console logs, to help debug this issue:
+    // https://github.com/iccicci/rotating-file-stream/issues/17#issuecomment-384423230
+    // ==========================================
+    rotatingFilesStream.on('error', (err: any) => {
+      // tslint:disable-next-line:no-console
+      console.log('Rotating File Stream error: ', err);
+    });
+    rotatingFilesStream.on('warning', (err: any) => {
+      // tslint:disable-next-line:no-console
+      console.log('Rotating File Stream warning: ', err);
+    });
+
+    streams.push({
+      level: convertLogLevelToPinoLabelLevel(loggerConfig.getLogLevel()),
+      stream: rotatingFilesStream
+    });
+  }
+
+  multistream = pinoMultiStreams.multistream(streams);
+  loggerInstance = pino(
+    {
+      name,
+      safe: true,
+      timestamp: pino.stdTimeFunctions.isoTime, // ISO-8601 timestamps
+      messageKey: 'msg',
+      level: convertLogLevelToPinoLabelLevel(loggerConfig.getLogLevel())
+    },
+    multistream
+  );
+
+  libIsInited = true;
+};
+
+/**
+ * Change the global log level of the application. Useful to change dynamically
+ * the log level of something that is already started.
+ * @param level The log level to set for the application
+ */
+export const setGlobalLogLevel = (level: LogLevel) => {
+  if (!loggerInstance) {
+    throw new Error(
+      'You must use "initLogger" function in @villemontreal/core-utils-logger-nodejs-lib package before making new instance of Logger class.'
+    );
+  }
+  // Change the log level and update children accordingly
+  loggerInstance.level = convertLogLevelToPinoLabelLevel(level);
+  for (const logger of loggerChildren) {
+    logger.update();
+  }
+
+  // ==========================================
+  // The streams's levels need to be modified too.
+  // ==========================================
+  if (multistream && multistream.streams) {
+    for (const stream of multistream.streams) {
+      // We need to use the *numerical* level value here
+      stream.level = convertLogLevelToPinoNumberLevel(level);
+    }
+  }
+};
+
+/**
+ * Shorthands function that return a new logger instance
+ * Internally, we use the same logger instance but with different context like the name given in parameter
+ * and this context is kept in this new instance returned.
+ * @export
+ * @param {string} name
+ * @returns {ILogger}
+ */
+export function createLogger(name: string): ILogger {
+  return new Logger(name);
+}
+
+export function isInited(): boolean {
+  return libIsInited;
+}
+
+/**
+ * Logger implementation.
+ */
+export class Logger implements ILogger {
+  private readonly pino: pino.Logger;
+
+  /**
+   * Creates a logger.
+   *
+   * @param the logger name. This name should be related
+   * to the file the logger is created in. On a production
+   * environment, it's possible that only this name will
+   * be available to locate the source of the log.
+   * Streams will be created after the first call to the logger
+   */
+  constructor(name: string) {
+    if (!loggerInstance) {
+      throw new Error(
+        'You must use "initLogger" function in @villemontreal/core-utils-logger-nodejs-lib package before making new instance of Logger class.'
+      );
+    }
+    this.pino = loggerInstance.child({ name });
+    loggerChildren.push(this);
+  }
+
+  /**
+   * Logs a DEBUG level message object.
+   *
+   * If the extra "txtMsg" parameter is set, it is
+   * going to be  added to messageObj as a ".msg"
+   * property (if messageObj is an object) or
+   * concatenated to messageObj (if it's not an
+   * object).
+   *
+   * Those types of logs are possible :
+   *
+   * - log.debug("a simple text message");
+   * - log.debug({"name": "an object"});
+   * - log.debug({"name": "an object..."}, "... and an extra text message");
+   * - log.debug(err, "a catched error and an explanation message");
+   */
+  public debug(messageObj: any, txtMsg?: string) {
+    this.log(LogLevel.DEBUG, messageObj, txtMsg);
+  }
+
+  /**
+   * Logs an INFO level message.
+   *
+   * If the extra "txtMsg" parameter is set, it is
+   * going to be  added to messageObj as a ".msg"
+   * property (if messageObj is an object) or
+   * concatenated to messageObj (if it's not an
+   * object).
+   *
+   * Those types of logs are possible :
+   *
+   * - log.info("a simple text message");
+   * - log.info({"name": "an object"});
+   * - log.info({"name": "an object..."}, "... and an extra text message");
+   * - log.info(err, "a catched error and an explanation message");public
+   */
+  public info(messageObj: any, txtMsg?: string) {
+    this.log(LogLevel.INFO, messageObj, txtMsg);
+  }
+
+  /**
+   * Logs a WARNING level message.
+   *
+   * If the extra "txtMsg" parameter is set, it is
+   * going to be  added to messageObj as a ".msg"
+   * property (if messageObj is an object) or
+   * concatenated to messageObj (if it's not an
+   * object).
+   *
+   * Those types of logs are possible :
+   *
+   * - log.warning("a simple text message");
+   * - log.warning({"name": "an object"});
+   * - log.warning({"name": "an object..."}, "... and an extra text message");
+   * - log.warning(err, "a catched error and an explanation mespublic sage");
+   */
+  public warning(messageObj: any, txtMsg?: string) {
+    this.log(LogLevel.WARNING, messageObj, txtMsg);
+  }
+
+  /**
+   * Logs an ERROR level message.
+   *
+   * If the extra "txtMsg" parameter is set, it is
+   * going to be  added to messageObj as a ".msg"
+   * property (if messageObj is an object) or
+   * concatenated to messageObj (if it's not an
+   * object).
+   *
+   * Those types of logs are possible :
+   *
+   * - log.error("a simple text message");
+   * - log.error({"name": "an object"});
+   * - log.error({"name": "an object..."}, "... and an extra text message");
+   * - log.error(err, "a catched error and an explanatpublic ion message");
+   */
+  public error(messageObj: any, txtMsg?: string) {
+    this.log(LogLevel.ERROR, messageObj, txtMsg);
+  }
+
+  /**
+   * Logs a level specific message.
+   *
+   * If the extra "txtMsg" parameter is set, it is
+   * going to be added to messageObj as a ".msg"
+   * property (if messageObj is an object) or
+   * concatenated to messageObj (if it's not an
+   * object).
+   *
+   * Those types of logs are possible :
+   *
+   * - log(LogLevel.XXXXX, "a simple text message");
+   * - log({"name": "an object"});
+   * - log({"name": "an object..."}, "... and an extra text message");
+   * - log(err, "a catched error and an epublic xplanation message");
+   */
+  // tslint:disable-next-line:cyclomatic-complexity
+  public log(level: LogLevel, messageObj: any, txtMsg?: string) {
+    let messageObjClean = messageObj;
+    const txtMsgClean = txtMsg;
+
+    if (messageObjClean === null || messageObjClean === undefined) {
+      messageObjClean = {};
+    } else if (_.isArray(messageObjClean)) {
+      try {
+        loggerInstance.error(
+          `The message object to log can't be an array. An object will be used instead and` +
+            `the content of the array will be moved to an "_arrayMsg" property on it : ${messageObjClean}`
+        );
+      } catch (err) {
+        // too bad
+      }
+      messageObjClean = {
+        _arrayMsg: _.cloneDeep(messageObjClean)
+      };
+    }
+
+    if (utils.isObjectStrict(messageObjClean)) {
+      // ==========================================
+      // The underlying logger may ignore all fields
+      // except "message" if
+      // the message object is an instance of the
+      // native "Error" class. But we may want to use
+      // that Error class to log more fields. For example :
+      //
+      // let error: any = new Error("my message");
+      // error.customKey1 = "value1";
+      // error.customKey2 = "value2";
+      // throw error;
+      //
+      // This is useful if we need a *stackTrace*, which
+      // the Error class allows.
+      //
+      // This is why we create a plain object from that Error
+      // object.
+      // ==========================================
+      if (messageObjClean instanceof Error) {
+        const messageObjNew: any = {};
+        messageObjNew.name = messageObj.name;
+        messageObjNew.msg = messageObj.message;
+        messageObjNew.stack = messageObj.stack;
+
+        // Some extra custom properties?
+        messageObjClean = _.assignIn(messageObjNew, messageObj);
+      } else if (messageObjClean instanceof http.IncomingMessage && messageObjClean.socket) {
+        // ==========================================
+        // This is a weird case!
+        // When logging an Express Request, Pino transforms
+        // it first: https://github.com/pinojs/pino-std-serializers/blob/master/lib/req.js#L65
+        // But doing so it accesses the `connection.remoteAddress` prpperty
+        // and, in some contexts, the simple fact to access this property
+        // throws an error:
+        // "TypeError: Illegal invocation\n    at Socket._getpeername (net.js:712:30)"
+        //
+        // The workaround is to access this property in a try/catch
+        // and, if an error occures, force its value to
+        // a simple string.
+        // ==========================================
+        messageObjClean = _.cloneDeep(messageObjClean);
+        try {
+          // tslint:disable-next-line:no-unused-expression
+          messageObjClean.socket.remoteAddress;
+        } catch (err) {
+          messageObjClean.socket = {
+            ...messageObjClean.socket,
+            remoteAddress: '[not available]'
+          };
+        }
+      } else {
+        messageObjClean = _.cloneDeep(messageObjClean);
+      }
+
+      // ==========================================
+      // Pino will always use the "msg" preoperty of
+      // the object if it exists, even if we pass a
+      // second parameter consisting in the message.
+      // ==========================================
+      if (txtMsgClean) {
+        messageObjClean.msg = (messageObjClean.msg ? messageObjClean.msg + ' - ' : '') + txtMsgClean;
+      }
+    } else {
+      messageObjClean = {
+        msg: messageObjClean + (txtMsgClean ? ` - ${txtMsgClean}` : '')
+      };
+    }
+
+    if (level === LogLevel.DEBUG) {
+      this.pino.debug(this.enhanceLog(messageObjClean));
+    } else if (level === LogLevel.INFO) {
+      this.pino.info(this.enhanceLog(messageObjClean));
+    } else if (level === LogLevel.WARNING) {
+      this.pino.warn(this.enhanceLog(messageObjClean));
+    } else if (level === LogLevel.ERROR) {
+      this.pino.error(this.enhanceLog(messageObjClean));
+    } else {
+      try {
+        loggerInstance.error(`UNMANAGED LEVEL "${level}"`);
+      } catch (err) {
+        // too bad
+      }
+
+      this.pino.error(this.enhanceLog(messageObjClean));
+    }
+  }
+
+  /**
+   * Update the logger based on the parent changes.
+   * Could use something more precise to handle specific event but
+   * people could use it to update the child independently from the parent,
+   * which is not what is intended.
+   */
+  public update() {
+    // Set new level
+    this.pino.level = loggerInstance.level;
+  }
+
+  /**
+   * Adds the file and line number where the log occures.
+   * This particular code is required since our custom Logger
+   * is a layer over Pino and therefore adds an extra level
+   * to the error stack. Without this code, the file and line number
+   * are not the right ones.
+   *
+   * Based by http://stackoverflow.com/a/38197778/843699
+   */
+  private enhanceLog(messageObj: any) {
+    // ==========================================
+    // Adds a property to indicate this is a
+    // Montreal type of log entry.
+    //
+    // TODO validate this + adds standardized
+    // properties.
+    // ==========================================
+    if (!(constants.logging.properties.LOG_TYPE in messageObj)) {
+      messageObj[constants.logging.properties.LOG_TYPE] = constants.logging.logType.MONTREAL;
+
+      // ==========================================
+      // TO UPDATE when the properties added to the
+      // log change!
+      //
+      // 1 : first version with Bunyan
+      // 2 : With Pino
+      // ==========================================
+      messageObj[constants.logging.properties.LOG_TYPE_VERSION] = '2';
+    }
+
+    // ==========================================
+    // cid : correlation id
+    // ==========================================
+    const cid = loggerConfigs.correlationId;
+    if (cid) {
+      messageObj[constants.logging.properties.CORRELATION_ID] = cid;
+    }
+
+    // ==========================================
+    // "app" and "version"
+    // @see https://sticonfluence.interne.montreal.ca/pages/viewpage.action?pageId=43530740
+    // ==========================================
+    messageObj[constants.logging.properties.APP_NAME] = appName;
+    messageObj[constants.logging.properties.APP_VERSION] = appVersion;
+
+    if (!loggerConfigs.isLogSource()) {
+      return messageObj;
+    }
+
+    let stackLine;
+    const stackLines = new Error().stack.split('\n');
+    stackLines.shift();
+    for (const stackLineTry of stackLines) {
+      if (stackLineTry.indexOf(`at ${(Logger as any).name}.`) <= 0) {
+        stackLine = stackLineTry;
+        break;
+      }
+    }
+    if (!stackLine) {
+      return messageObj;
+    }
+
+    let callerLine = '';
+    if (stackLine.indexOf(')') >= 0) {
+      callerLine = stackLine.slice(stackLine.lastIndexOf('/'), stackLine.lastIndexOf(')'));
+      if (callerLine.length === 0) {
+        callerLine = stackLine.slice(stackLine.lastIndexOf('('), stackLine.lastIndexOf(')'));
+      }
+    } else {
+      callerLine = stackLine.slice(stackLine.lastIndexOf('at ') + 2);
+    }
+
+    const firstCommaPos = callerLine.lastIndexOf(':', callerLine.lastIndexOf(':') - 1);
+    const filename = callerLine.slice(1, firstCommaPos);
+    const lineNo = callerLine.slice(firstCommaPos + 1, callerLine.indexOf(':', firstCommaPos + 1));
+
+    messageObj.src = {
+      file: filename,
+      line: lineNo
+    };
+
+    return messageObj;
+  }
+}