Simplify changes for custom fields and custom field names

Author: simonkotwicz

.eslintrc

@@ -0,0 +1,10 @@
+rules:
+    semi: error
+    quotes: [error, single, {allowTemplateLiterals: true}]
+    indent: [error, 4]
+    linebreak-style: [error, unix]
+    no-unused-vars: warn
+env:
+    es6: true
+    node: true
+extends: eslint:recommended

.eslintrc.yml

@@ -26,87 +26,57 @@ You must add the following to the list of appenders in your `log4js.json` file:
 
 ```
 {
-  "type": "log4js-logmet-appender",
-  "options": {
-    "level": "INFO"
-  }
+  "type": "log4js-logmet-appender"
 }
  ```
- You may substitute `INFO` with your own level above (for ex: `WARN`, `ERROR`, etc). Please check [log4js](https://www.npmjs.com/package/log4js) documentation for level based filtering since there might be some differences between versions.  
 
-To use custom fields to send logmet, you should define `eventMap` object under `options`. If it is not defined then default mapping is used. 
+Using this configuration log messages to logmet will contain the following fields:
+- `component`: value of the environment variable `log4js_logmet_component`
+- `host-ip`: value of the environmental variable `CF_INSTANCE_IP`
+- `instance-id`: value of the environmental variable `CF_INSTANCE_INDEX`
+- `loglevel`: logging level (eg. `INFO`)
+- `logtime`: time message was logged in ISO string format (eg. `2011-10-05T14:48:00.000Z`)
+- `message`: log message/data, data array elements are concatenated with ` | ` delimeter
 
-Default Event object (object sending to Logmet) consists of `component`, `host-ip`, `instance-id`, `loglevel`, `logtime`, `message` values. 
+### Custom Fields
 
-For custom fields, values can be map are given below:
-- `component`: The name of your component / service. 
-- `host-ip`: The cloudfoundary ip defined as environmental variable CF_INSTANCE_IP
-- `instance-id`: The cloudfounrday index defined as environmental variable CF_INSTANCE_INDEX
-- `loglevel`: Logging level string. (exp. TRACE, DEBUG, INFO, WARN, ERROR, FATAL)
-- `logtime`: Logging time as ISO string format (exp. 2011-10-05T14:48:00.000Z)
-- `message`: Log message based on log4js configuration. If log data is multiple string, then is is merged with ` | ` delimiter. 
-- `process.*` : To reach variables from `process` within two layer. (exp. process.pid, process.env.USER)
-- `data.*` : To reach variables from optional `object` type from log data within two layer. This is useful, if you want to pass a custom object and use the value in your logs withing a custom field. (exp. You can pass `{clientId: '123'}` object to log and map it as `CLIENT_ID: data.clientId`)
+To use custom fields, you should define an `options.fields` object.
+Note: If a `fields` object is defined, none of the default fields will be sent.
 
-Example `log4js.json` file given below (for log4js version 0.6.38 and below).
-```
-{
-  "appenders": [
-    {
-      "type": "console",
-      "layout": { "type": "coloured" }
-    },
-    { 
-      "type": "logLevelFilter", 
-      "level": "INFO", 
-      "appender": {
-        "type": "log4js-logmet-appender",
-        "options": {
-          "eventMap": {
-            "TIMESTAMP": "logtime",
-            "PRIORITY": "loglevel",
-            "MESSAGE": "message",
-            "SERVICE": "component",
-            "_PID": "process.pid",
-            "USER": "process.env.USER",
-            "CUSTOM_ENV": "process.env.CUSTOM_VARIABLE"
-            "TEST": "data.test",
-            "TEST12": "data.test1.test2"
-          }
-        }
-     }
-   }
-  ],
-  "replaceConsole": true
-}
-```
-And example `debug` logging call;
-```
-var log4js = require('log4js');
-log4js.configure('/path/to/log4js.json');
-var logger = log4js.getLogger();
-logger.level = 'debug';
-const objectToTest = { test: 'test 1 is good', test1: { test2: 'test 2 is better' } };
-logger.debug("Some debug messages", objectToTest);
-```
-This example prints coloured console log and filters `INFO` levels for `log4js-logmet-appender` appender. 
-`eventMap` determines the custom mapping for the object sending logmet. Values will be replaced based on event mapping and will send to logmet. 
+You can choose names for the log level (`"level_field_name"`), timestamp (`"timestamp_field_name"`) and data/message (`"data_field_name"`) fields. You may also add more custom static fields (under the `"static_fields"` object), fields that have node `process` object properties as values (under the `"process_fields"` object), and fields that have environment variables as values (under the `"env_fields"` object).
 
-Example data to be sent to logmet based on given `log4js.json`
+Example with custom fields:
 ```
-{
-    "TIMESTAMP": "2011-10-05T14:48:00.000Z",
-    "PRIORITY": "INFO",
-    "MESSAGE": "Your log message",
-    "SERVICE": "name of your component",
-    "_PID": 1234,
-    "USER": "Username of the process",
-    "CUSTOM_ENV": "Environmental value defined as CUSTOM_VARIABLE",
-    "TEST": "test 1 is good",
-    "TEST12": "test 2 is better"
+{ 
+  "type": "log4js-logmet-appender",
+  "options": {
+    "fields": {
+      "level_field_name": "PRIORITY",
+      "timestamp_field_name": "TIMESTAMP",
+      "data_field_name": "MESSAGE"
+
+      "static_fields": {
+        "COMPONENT": "otc-api"
+      },
+
+      "process_fields": {
+        "PROCESS_ID": "pid"
+      },
+
+      "env_fields": {
+        "INSTANCE_INDEX": "CF_INSTANCE_INDEX"
+      }
+    }
+  }
 }
 ```
 
+You may also define custom dynamic fields by setting `options.fields` `"data_field_augment"` to `true` and passing a single object argument to the logger. Object keys will be mapped to field names.
+
+Example: `logger.info({ MESSAGE: "hello", FLAG: "urgent" });`
+
+Note: If `"data_field_augment"` is set to `true` and a single object argument is NOT passed to the logger, the log message/data will still be sent as a regular field if `"data_field_name"` is also set.
+
 ## Pending work
 No automated tests currently
 
@@ -120,4 +90,4 @@ Contributions are welcome via Pull Requests. Please submit your very first Pull
 
 ```
 Signed-off-by: John Doe <john.doe@example.org>
-```
+```

README.md

@@ -19,17 +19,7 @@ module.exports = {
     shutdown: shutdown
 };
 
-const messageSeperator = " | ";
-const defaultEventMap = {
-    'component': 'component',
-    'host-ip':  'host-ip',
-    'instance-id':'instance-id',
-    'loglevel': 'loglevel',
-    'logtime': 'logtime',
-    'message': 'message'
-};
-
-function sendData(level, options, tlsOpts, log) {
+function sendData(options, tlsOpts, log) {
     var event = buildEvent(log, options);
     logmetConnection.producer.sendData(event, log.categoryName, options.space_id, function(/*error, status*/) {
         // message is dropped if an error is returned, errors already logged by logmet client
@@ -38,67 +28,37 @@ function sendData(level, options, tlsOpts, log) {
 
 function buildEvent(log, options) {
     // build up message to send
-    var event = {};
-    if(options && options.event_map){
-        for (var key in options.event_map) {
-            if (!options.event_map.hasOwnProperty(key)) continue;
-            var value = options.event_map[key];
-            event[key] = getValueForMapping(value, options, log);
-        }
-    }
-    return event;
-}
+    let event = {};
+    let fields = options.fields;
 
-function getValueForMapping(key, options, log){
-    var valueMapped;
-    if(key === 'component'){
-        valueMapped = options.component;
-    } else if(key === 'host-ip'){
-        valueMapped = process.env.CF_INSTANCE_IP;
-    } else if(key === 'instance-id'){
-        valueMapped = process.env.CF_INSTANCE_INDEX;
-    } else if(key === 'loglevel'){
-        valueMapped = log.level && log.level.levelStr;
-    } else if(key === 'logtime'){
-        valueMapped = log.startTime && log.startTime.toISOString();
-    } else if(key === 'message'){
-        valueMapped = log.data && log.data.reduce(function (a, b) {
-            return ((typeof(a)==="object" && JSON.stringify(a)) || a) + messageSeperator + ((typeof(b)==="object" && JSON.stringify(b)) || b);
-        });
-    } else if(key.startsWith('process.') && key.length > 8){
-        var processValue = key.substring(8).split('.');
-        if(processValue.length == 1){
-            valueMapped = process[processValue[0]];
-        } else if (processValue.length == 2){ 
-            valueMapped = process[processValue[0]] && process[processValue[0]][processValue[1]];
-        }
-        else{
-            //do nothing - currently only support for 2 layer process information
-        }
-    } else if(key.startsWith('data.') && key.length > 5){ //Custom data parsing using log data array's first `object` type element
-        var logDataObject = log.data && log.data.find(function(element) {
-            return (typeof(element)==="object");
-        });
-        if(logDataObject){
-            var dataValue = key.substring(5).split('.');
-            if(dataValue.length == 1){
-                valueMapped = logDataObject[dataValue[0]];
-            } else if (dataValue.length == 2){ 
-                valueMapped = logDataObject[dataValue[0]] && logDataObject[dataValue[0]][dataValue[1]];
-            } else {
-                 //do nothing - currently only support for 2 layer data information
-            }
-        }
-        else{
-            //do nothing - there is no data object
+    if (fields.level_field_name) { 
+        event[fields.level_field_name] = log.level && log.level.levelStr; 
+    }
+    if (fields.timestamp_field_name) { 
+        event[fields.timestamp_field_name] = log.startTime && log.startTime.toISOString();
+    }
+    if (fields.data_field_augment && log.data && log.data.length === 1 && typeof log.data[0] === 'object') {
+        let customDynamicFields = log.data[0];
+        for (let customDynamicFieldName in customDynamicFields) {
+            event[customDynamicFieldName] = customDynamicFields[customDynamicFieldName];
         }
-    } else {
-        // No valid mapping found for given key.
+    } else if (fields.data_field_name) {
+        event[fields.data_field_name] = log.data && log.data.join(' | ');
+    }
+    for (let staticFieldName in fields.static_fields) {
+        event[staticFieldName] = fields.static_fields[staticFieldName];
+    }
+    for (let processFieldName in fields.process_fields) {
+        event[processFieldName] = process[fields.process_fields[processFieldName]];
     }
-    return valueMapped;
+    for (let envFieldName in fields.env_fields) {
+        event[envFieldName] = process.env[fields.env_fields[envFieldName]];
+    }
+
+    return event;
 }
 
-function appender(level, options, tlsOpts) {
+function appender(options, tlsOpts) {
     logmetConnection.producer = new logmet.LogmetProducer(tlsOpts.host, tlsOpts.port, options.space_id, options.logging_token, false, {bufferSize: logmetConnection.BUFFER_SIZE});
     logmetConnection.producer.connect(function(error, status) {
         if (error) {
@@ -107,17 +67,30 @@ function appender(level, options, tlsOpts) {
             util.log('Logmet Appender: LogmetClient is ready to send data.'); 
         }
     });
-    return sendData.bind(this, level, options, tlsOpts);
+    return sendData.bind(this, options, tlsOpts);
 }
 
 function configure(config) {
     if (process.env.log4js_logmet_enabled !== 'true') return function() {};
 
+    const defaultFields = {
+        'level_field_name': 'loglevel',
+        'timestamp_field_name': 'logtime',
+        'data_field_name': 'message',
+
+        'static_fields': {
+            'component': process.env.log4js_logmet_component || config.options && config.options.component
+        },
+        'env_fields': {
+            'host-ip': 'CF_INSTANCE_IP',
+            'instance-id': 'CF_INSTANCE_INDEX'
+        }
+    };
+
     const options = {
-        component: process.env.log4js_logmet_component || config.options && config.options.component,
         logging_token: process.env.log4js_logmet_logging_token || config.options && config.options.logging_token,
         space_id: process.env.log4js_logmet_space_id || config.options && config.options.space_id,
-        event_map: (config.options && config.options.eventMap) || defaultEventMap
+        fields: (config.options && config.options.fields) || defaultFields
     };
 
     const tlsOpts = {
@@ -143,10 +116,8 @@ function configure(config) {
         config.actualAppender = log4js.appenderMakers[config.appender.type](config.appender);
     }
 
-    const level = log4js.levels[config.options.level] && log4js.levels[config.options.level].level || Number.MIN_VALUE;
-
     util.log('Logmet Appender configured');
-    return appender(level, options, tlsOpts);
+    return appender(options, tlsOpts);
 }
 
 function shutdown(callback) {

index.js

@@ -1,6 +1,6 @@
 {
   "name": "log4js-logmet-appender",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Logmet appender for node-log4js",
   "author": "Herman Singh Badwal <hermanba@ca.ibm.com>",
   "license": "MIT",