READ.ME 8.99 KB
# LOG STAT ALARM

  ### Log

    * Append JSON object, array, or string to a log file
    * All type will be converted to string automatically
    * ISO string and unix time will be with each log by default

  ### Stat

    * Keep track of value within the applications
    * Call 'increment' method of specific value whenever incrementation is needed
    * Stat will automatically append all value into a file when it reaches its configured interval
    * Value can be pre-configured for alarm (threshold, inverted threshold: read more on Alarm section)
    * ISO string and unix time will be with each stat by default

  ### Alarm

    * If any stat value exceed its pre-configured threshold, it will be logged into alarm file
    * If any stat value does not reach its pre-configured inverted threshold, it will also be logged into alarm file
    * Before logging into alarm file, the module will call external functions that are being provided on init method (more on example)
    * Stat module will consistently check the above rules in at the end of each interval

  ### File Management

    * Every module has option to configure file rotation frequency
    * File rotation can be configured in two ways:
      * Rotate by time (in millisecond)
      * Rotate by file max size (in byte)
    * Each module can be configured with both options ( read more on example section )

  ### Example

    ##### Initialization

      Initialization should be called only once in each application
      Use the response object for log stat alarm

      Options
        * dirname: the parent folder for log, stat, and alarm ('./logstatalarm'). Log, stat and alarm files will be auto generated as child folders ( Type: string )
          * ./logstatalarm/log/
          * ./logstatalarm/stat/
          * ./logstatalarm/alarm/
        * log.rotation: seperate files into time frame ( Type: integer (ms) )
          * 1000 = 1 second
          * 60 * 1000 = 60 seconds
          * 15 * 60 * 1000 = 15 minutes
        * log.maxsize: if the current time frame for the file exceed maxsize, it will auto generate file with same time frame with suffix to count ( Type: integer (byte) )
          * 1 = 1 byte
          * 1000 = 1 Kb
          * 1000000 = 1 Mb
        * stat.rotation: seperate files into time frame ( Type: integer (ms) )
          * 1000 = 1 second
          * 60 * 1000 = 60 seconds
          * 15 * 60 * 1000 = 15 minutes
        * stat.maxsize: if the current time frame for the file exceed maxsize, it will auto generate file with same time frame with suffix to count ( Type: integer (byte) )
          * 1 = 1 byte
          * 1000 = 1 Kb
          * 1000000 = 1 Mb
        * stat.interval: interval defines how frequent stat should be append to file. All value counter will be reset to 0 and if any value is not within the configured threshold range, it will be log to alarm file. ( Type: interger (ms) )
          * 1000 = 1 second
          * 2 * 1000 = 2 seconds
          * 2 * 60 * 1000 = 2 minutes
        * stat.data: Data can be pre-configured with threshold and inverted threshold ( Type: array of object )
          * Object data type: { key: string, threshold: integer (min 0), threshold_inv: integer (min 0) }
          * Threshold and threshold_inv is not required
          * At the end of each interval, stat value will be checked if it exceed threshold or haven't reach threshold_inv. If so, it will log to alarm file automatically
        * alarm.rotation: seperate files into time frame ( Type: integer (ms) )
          * 1000 = 1 second
          * 60 * 1000 = 60 seconds
          * 15 * 60 * 1000 = 15 minutes
        * alarm.maxsize: if the current time frame for the file exceed maxsize, it will auto generate file with same time frame with suffix to count ( Type: integer (byte) )
          * 1 = 1 byte
          * 1000 = 1 Kb
          * 1000000 = 1 Mb
        * alarm.external: ( Type: Array )
        * alarm.external[].fn: ( Type: Function)
          * This function will be called right before the module log into alarm log file (Use cases: http request, snmp request, syslog file logging, etc.)
          * All functions will be called asynchronously
          * All callback function within these functions will be ignored
          * All return data within these functions will also be ignored
          * Make sure the first argument of this function is for data (This data is the same data that logged in to alarm file))
          * Error handling have to be carefully implemented because all return data will be ignored
        * alarm.external[].args: ( Type: Array )
        * alarm.external[].args[]: arguments for function above ( Type: Any )
          * Args will be use for executing the alarm.external[].fn function (more on examples)


      Note*: In this example, we will be using request module (npm install request) on alarm external function for demonstration purpose only.
      ```
        var logstatalarm = require('logstatalarm');
        var request = require('request');
        var http_request = function(data, host, port, path, method) {         // make sure your first argument is Data
          var opts = {
            host: host,
            port: port,
            path: path,
            method: method,
            body: data                                                        // Data will always be in type: String
          request(opts, function(err, res) {                                  // Any callback or return data will be ignore
            if(err) {
              console.log(err);
            }
          };

        }
        var opts = {
          dirname: './logstatalarm/',               // required
          log: {
            rotation: 15 * 60 * 1000,               // not required, default: 15 minutes
            maxsize: 2000000                        // not required, default: 20 Mb
          },                                        // required ({} if no configuration is needed)
          stat: {
            rotation: 30 * 60 * 1000,               // not required, default: 15 minutes
            maxsize: 2000000,                       // not required, default: 20 Mb
            interval: 2 * 60 * 1000,                // not required, default: 1 minute
            data: [
              {key: 'userLogin', threshold_inv: 100},
              {key: 'Error 400', threshold: 1000, threshold_inv: 10},
              {key: 'Error 500', threshold: 1}
            ]                                       // not required, default: []
          },                                        // required ({} if no configuration is needed)
          alarm: {
            rotation: 60 * 60 * 1000,               // not required, default: 15 minutes
            maxsize: 2000000                        // not required, default: 20 Mb
            external: [
              { fn: http_request, args: ["http://localhost", "3000", "/alarm", "POST"] },  // required
              { fn: http_request, args: ["http://someserver.com", "9999", "/alarm", "POST"] }    // not required
            ]                                       // not required
          },                                        // required ({} if no configuration is needed)
        };

        //Call init method only once
        var logObj = logstatalarm.init(opts);

        // NOTE *: in case if there is any error, the module will throw error and crash the applicatio (Configuration error)
      ```

    ##### Log
      We will be using variable logObj throughout the application
      ```
        var exampleLogData = {
          path: '/user',
          method: 'GET',
          resquest: {},
          response: {statusCode: 200}
        }
        logObj.log.append(exampleLogData);
      ```

    ##### Stat
      After initialization of the module, start method have to be called once inorder to start the interval logging of stat values
      Then freely use increment method any where any time needed
      We will be using variable logObj throughout the application
      ```
        logObj.stat.start();                  // call this once
        logObj.stat.increment('Error 500');
        logObj.stat.increment('Error 400');
        logObj.stat.increment(User + 'user login');
      ```
      At any point in time stop method can be called to stop logging interval
      ```
        logObj.stat.stop();
      ```
    ##### Alarm
      External functions will be executed before logging in to alarm file.
      You don't need to do anything with the alarm module. It will be logged automatically from stat module.

    ##### File management
      Example of log file with this configuration:
        rotation: 1000
        maxsize: 20000

      -rw-r--r--  test  20K Jun 20 15:00 2016-06-20T15:00:19_00001.txt
      -rw-r--r--  test  11K Jun 20 15:00 2016-06-20T15:00:19_00002.txt
      -rw-r--r--  test  20K Jun 20 15:00 2016-06-20T15:00:20_00001.txt
      -rw-r--r--  test  11K Jun 20 15:00 2016-06-20T15:00:20_00002.txt

      As you can see, the file is set to maximum at 20Kb and is rotate every 1 second
      If the file reaches maxsize before 1 second it will append log into the same time frame with incremental suffix