Merge pull request #15 from KurtPattyn/develop

Add enrich option to karl configuration

README.md

@@ -148,6 +148,31 @@ To disable this redirection, set the `redirectConsole` option to `false`.
 karl.setOptions({ redirectConsole: false });
 ```
 
+## Log Enrichtment
+Applications can add extra information to a message at the moment it is logged.  
+One example usage is adding request information to the log messages in an express application.
+
+```javascript
+karl.setOption({
+  enrich: addRequestInformation,
+  json:   true
+});
+
+function addRequestInformation(msg) {
+  //fetch request information from somewhere, e.g. by using continuation local storage
+  const request = context.get("request");
+  msg.headers = request.headers;
+}
+
+app.use((req, res, next) => {
+  console.log("Entering application");
+});
+```
+
+```sh
+{"timestamp":"2015-08-02T18:02:39.456Z","level":"DEBUG","hostName":"<hidden>","process":{"name":"karltest","pid":26693},"message":"Entering application","fileName":"karltest.js","lineNumber":41,"functionName":"<anonymous>", "headers": { "host": "localhost", ... }}
+```
+
 ## UncaughtException
 Karl catches any uncaught exception (see [Event 'uncaughtException'](https://nodejs.org/api/process.html#process_event_uncaughtexception)).  
 When such an exception occurs, Karl logs a fatal log message (including stack trace) and then gracefully shuts down the process by emitting a `SIGINT` signal.

lib/karl.js

@@ -370,6 +370,10 @@ LOG_LEVELS.forEach(function(level) {
         lineNumber: caller.getLineNumber(),
         functionName: caller.getFunctionName() || "<anonymous>"
       };
+
+      if (logOptions.enrich) {
+        logOptions.enrich(message);
+      }
       let msg = format(message) + "\n";
 
       if (logOptions.colorize) {
@@ -430,6 +434,7 @@ if (defaultLogOptions.redirectConsole) {
  * @param {Boolean} [options.colorize=false] When true, karl outputs error and fatal messages in red, warning errors in yellow and other messages in the current text color.
  * @param {Boolean} [options.redirectConsole=true] When true, console messages are redirected through karl (optionally including location information and adding color).
  * @param {Boolean} [options.json=true] When true, messages are printed as json messages, otherwise plain text is printed.
+ * @param {Function} [options.enrich] An optional callback method that can be used to add additional information to a log message. The enrich method takes a message JSON struct as parameter. The enrich method should directly change the message object and does not have to return anything.
  *
  * @public
 */