doc(apm): document apm events that are emitted from topologies

NODE-1390

Author: mbroadst

index.js

@@ -55,7 +55,6 @@ connect.instrument = function(options, callback) {
     options = {};
   }
 
-  // return new Instrumentation(core, options, callback);
   const instrumentation = new Instrumentation();
   instrumentation.instrument(connect.MongoClient, callback);
   return instrumentation;

lib/apm.js

@@ -13,7 +13,7 @@ class Instrumentation extends EventEmitter {
 
     const instrumentation = this;
     MongoClient.prototype.connect = function(callback) {
-      this.s.options.enableCommandMonitoring = true;
+      this.s.options.monitorCommands = true;
       this.on('commandStarted', event => instrumentation.emit('started', event));
       this.on('commandSucceeded', event => instrumentation.emit('succeeded', event));
       this.on('commandFailed', event => instrumentation.emit('failed', event));

lib/mongo_client.js

@@ -107,7 +107,7 @@ var validOptionNames = [
   'numberOfRetries',
   'auto_reconnect',
   'minSize',
-  'enableCommandMonitoring'
+  'monitorCommands'
 ];
 
 var ignoreOptionNames = ['native_parser'];
@@ -200,7 +200,7 @@ function validOptions(options) {
  * @param {array} [options.readPreferenceTags=null] Read preference tags
  * @param {number} [options.numberOfRetries=5] The number of retries for a tailable cursor
  * @param {boolean} [options.auto_reconnect=true] Enable auto reconnecting for single server instances
- * @param {boolean} [options.enableCommandMonitoring=false] Enable command monitoring for this client
+ * @param {boolean} [options.monitorCommands=false] Enable command monitoring for this client
  * @param {MongoClient~connectCallback} [callback] The command result callback
  * @return {MongoClient} a MongoClient instance
  */

lib/topologies/mongos.js

@@ -59,7 +59,7 @@ var legalOptionNames = [
   'promoteValues',
   'promoteBuffers',
   'promiseLibrary',
-  'enableCommandMonitoring'
+  'monitorCommands'
 ];
 
 /**
@@ -90,6 +90,7 @@ var legalOptionNames = [
  * @param {number} [options.socketOptions.connectTimeoutMS=0] TCP Connection timeout setting
  * @param {number} [options.socketOptions.socketTimeoutMS=0] TCP Socket timeout setting
  * @param {boolean} [options.domainsEnabled=false] Enable the wrapping of the callback in the current domain, disabled by default to avoid perf hit.
+ * @param {boolean} [options.monitorCommands=false] Enable command monitoring for this topology
  * @fires Mongos#connect
  * @fires Mongos#ha
  * @fires Mongos#joined
@@ -100,6 +101,9 @@ var legalOptionNames = [
  * @fires Mongos#error
  * @fires Mongos#timeout
  * @fires Mongos#parseError
+ * @fires Mongos#commandStarted
+ * @fires Mongos#commandSucceeded
+ * @fires Mongos#commandFailed
  * @property {string} parserType the parser type used (c++ or js).
  * @return {Mongos} a Mongos instance.
  */
@@ -151,10 +155,8 @@ class Mongos extends TopologyBase {
         reconnect: reconnect,
         emitError: typeof options.emitError === 'boolean' ? options.emitError : true,
         size: typeof options.poolSize === 'number' ? options.poolSize : 5,
-        enableCommandMonitoring:
-          typeof options.enableCommandMonitoring === 'boolean'
-            ? options.enableCommandMonitoring
-            : false
+        monitorCommands:
+          typeof options.monitorCommands === 'boolean' ? options.monitorCommands : false
       }
     );
 
@@ -454,4 +456,25 @@ define.classMethod('connections', { callback: false, promise: false, returns: [A
  * @type {object}
  */
 
+/**
+ * An event emitted indicating a command was started, if command monitoring is enabled
+ *
+ * @event Mongos#commandStarted
+ * @type {object}
+ */
+
+/**
+ * An event emitted indicating a command succeeded, if command monitoring is enabled
+ *
+ * @event Mongos#commandSucceeded
+ * @type {object}
+ */
+
+/**
+ * An event emitted indicating a command failed, if command monitoring is enabled
+ *
+ * @event Mongos#commandFailed
+ * @type {object}
+ */
+
 module.exports = Mongos;

lib/topologies/replset.js

@@ -67,7 +67,7 @@ var legalOptionNames = [
   'maxStalenessSeconds',
   'promiseLibrary',
   'minSize',
-  'enableCommandMonitoring'
+  'monitorCommands'
 ];
 
 /**
@@ -101,6 +101,7 @@ var legalOptionNames = [
  * @param {number} [options.socketOptions.socketTimeoutMS=0] TCP Socket timeout setting
  * @param {boolean} [options.domainsEnabled=false] Enable the wrapping of the callback in the current domain, disabled by default to avoid perf hit.
  * @param {number} [options.maxStalenessSeconds=undefined] The max staleness to secondary reads (values under 10 seconds cannot be guaranteed);
+ * @param {boolean} [options.monitorCommands=false] Enable command monitoring for this topology
  * @fires ReplSet#connect
  * @fires ReplSet#ha
  * @fires ReplSet#joined
@@ -111,6 +112,9 @@ var legalOptionNames = [
  * @fires ReplSet#error
  * @fires ReplSet#timeout
  * @fires ReplSet#parseError
+ * @fires ReplSet#commandStarted
+ * @fires ReplSet#commandSucceeded
+ * @fires ReplSet#commandFailed
  * @property {string} parserType the parser type used (c++ or js).
  * @return {ReplSet} a ReplSet instance.
  */
@@ -158,10 +162,8 @@ class ReplSet extends TopologyBase {
         reconnect: false,
         emitError: typeof options.emitError === 'boolean' ? options.emitError : true,
         size: typeof options.poolSize === 'number' ? options.poolSize : 5,
-        enableCommandMonitoring:
-          typeof options.enableCommandMonitoring === 'boolean'
-            ? options.enableCommandMonitoring
-            : false
+        monitorCommands:
+          typeof options.monitorCommands === 'boolean' ? options.monitorCommands : false
       }
     );
 
@@ -498,4 +500,25 @@ define.classMethod('connections', { callback: false, promise: false, returns: [A
  * @type {object}
  */
 
+/**
+ * An event emitted indicating a command was started, if command monitoring is enabled
+ *
+ * @event ReplSet#commandStarted
+ * @type {object}
+ */
+
+/**
+ * An event emitted indicating a command succeeded, if command monitoring is enabled
+ *
+ * @event ReplSet#commandSucceeded
+ * @type {object}
+ */
+
+/**
+ * An event emitted indicating a command failed, if command monitoring is enabled
+ *
+ * @event ReplSet#commandFailed
+ * @type {object}
+ */
+
 module.exports = ReplSet;

lib/topologies/server.js

@@ -62,7 +62,7 @@ var legalOptionNames = [
   'promoteBuffers',
   'compression',
   'promiseLibrary',
-  'enableCommandMonitoring'
+  'monitorCommands'
 ];
 
 /**
@@ -96,12 +96,16 @@ var legalOptionNames = [
  * @param {number} [options.monitoring=true] Triggers the server instance to call ismaster
  * @param {number} [options.haInterval=10000] The interval of calling ismaster when monitoring is enabled.
  * @param {boolean} [options.domainsEnabled=false] Enable the wrapping of the callback in the current domain, disabled by default to avoid perf hit.
+ * @param {boolean} [options.monitorCommands=false] Enable command monitoring for this topology
  * @fires Server#connect
  * @fires Server#close
  * @fires Server#error
  * @fires Server#timeout
  * @fires Server#parseError
  * @fires Server#reconnect
+ * @fires Server#commandStarted
+ * @fires Server#commandSucceeded
+ * @fires Server#commandFailed
  * @property {string} parserType the parser type used (c++ or js).
  * @return {Server} a Server instance.
  */
@@ -151,10 +155,8 @@ class Server extends TopologyBase {
         reconnect: reconnect,
         emitError: typeof options.emitError === 'boolean' ? options.emitError : true,
         size: typeof options.poolSize === 'number' ? options.poolSize : 5,
-        enableCommandMonitoring:
-          typeof options.enableCommandMonitoring === 'boolean'
-            ? options.enableCommandMonitoring
-            : false
+        monitorCommands:
+          typeof options.monitorCommands === 'boolean' ? options.monitorCommands : false
       }
     );
 
@@ -458,4 +460,25 @@ define.classMethod('connections', { callback: false, promise: false, returns: [A
  * @type {object}
  */
 
+/**
+ * An event emitted indicating a command was started, if command monitoring is enabled
+ *
+ * @event Server#commandStarted
+ * @type {object}
+ */
+
+/**
+ * An event emitted indicating a command succeeded, if command monitoring is enabled
+ *
+ * @event Server#commandSucceeded
+ * @type {object}
+ */
+
+/**
+ * An event emitted indicating a command failed, if command monitoring is enabled
+ *
+ * @event Server#commandFailed
+ * @type {object}
+ */
+
 module.exports = Server;