new: audit logger plugin now supports custom context objects (#1519)

docs/api/plugins.md

@@ -231,6 +231,11 @@ event, e.g., `server.on('after', plugins.auditLogger());`:
 * `auditLogger(options)` - an audit logger for recording all handled requests
   * `options.event` {String} The name of the event, one of `pre`, `routed`, or `after`
   * `options.log` {Object} bunyan logger
+  * `[opts.context]` {Function} The optional context function of signature
+   f(req, res, route, err).  Invoked each time an audit log is generated. This
+   function can return an object that customizes the format of anything off the
+   req, res, route, and err objects. The output of this function will be
+   available on the `context` key in the audit object.
   * `[options.server]` {Object} restify server. if passed in, causes server to
      emit 'auditlog' event after audit logs are flushed
   * `[options.printLog]` {Boolean} when true, prints audit logs. defaults to true.

lib/plugins/audit.js

@@ -41,8 +41,13 @@ function getResponseHeaders(res) {
  * @param {Object} opts.log The logger.
  * @param {String} opts.event The event from the server which initiates the
  * log, one of 'pre', 'routed', or 'after'
- * @param {Server} [opts.server] The restify server, used to emit the audit log
- * object programttically
+ * @param {Function} [opts.context] The optional context function of signature
+ * f(req, res, route, err).  Invoked each time an audit log is generated. This
+ * function can return an object that customizes the format of anything off the
+ * req, res, route, and err objects. The output of this function will be
+ * available on the `context` key in the audit object.
+ * @param {Object} [opts.server] The restify server, used to emit the audit log
+ * object programmatically
  * @param {boolean} [opts.printLog=true] Whether to print the log
  * via the logger.
  * @returns {Function}
@@ -66,9 +71,8 @@ function getResponseHeaders(res) {
  * @example
  * <caption>
  * You pass in the auditor a bunyan logger, optionally server object,
- * Ringbuffer and a flag printLog indicate if
- * log needs to be print out at info level or not.  By default, without
- * specify printLog flag, it will write out
+ * Ringbuffer and a flag printLog indicate if log needs to be print out at info
+ * level or not.  By default, without specify printLog flag, it will write out
  * record lookling like this:
  * </caption>
  *
@@ -168,6 +172,7 @@ function auditLogger(opts) {
     assert.object(opts, 'opts');
     assert.object(opts.log, 'opts.log');
     assert.string(opts.event, 'opts.event');
+    assert.optionalFunc(opts.context, 'opts.context');
     assert.optionalObject(opts.server, 'opts.server');
     assert.optionalBool(opts.printLog, 'opts.printLog');
 
@@ -266,6 +271,12 @@ function auditLogger(opts) {
             event: opts.event
         };
 
+        // run through the custom context function
+        if (opts.context) {
+            obj.context = opts.context(req, res, route, err);
+        }
+
+
         if (printLog) {
             switch (opts.event) {
                 case 'after':