Merged APM prototype

Author: christkv

docs/content/tutorials/tracing.md

@@ -50,3 +50,176 @@ MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {
 In this code we change the behavior of the findOne method by wrapping it in our own method that records the start and end times of the findOne operation and prints the number of milliseconds it took to the console. The cool thing is that this is global. Once we changed `Collection.prototype` we automatically get our new wrapped method for all methods that create a new `Collection` instance allowing us to instruments all calls using `Collection.findOne` across our application.
 
 There is not much more to it so go ahead and think of some crazy ways to use this and if you do something very clever let me know :).
+
+# APM Integration Interface API
+
+The `2.0.29` driver introduces an Application Performance Monitoring integration interface to allow for more streamlined interfacing with the driver. The API exposes all the integration points the driver exposes for instrumentation and this should allow minimizing the breakage going forward when the driver adds or removed methods.
+
+Interfacing is straight forward.
+
+```js
+var mongodb = require('mongodb');
+mongodb.instrument(function(err, instrumentations) {
+  
+});
+```
+
+Where `instrumentations` is an array of prototypes that can be instrumented and their metadata. In the case of the gridstore it might look like the following.
+
+```js
+{
+  name: 'GridStore',
+  obj: GridStore,
+  stream: true, 
+  instrumentations: [
+    { methods: [
+      'open', 'getc', 'puts', 'write', 'writeFile', 'close', 'unlink', 'readlines',
+      'rewind', 'read', 'tell', 'seek'
+    ], options: { callback: true, promise:false } },
+    { methods: [
+      'collection' 
+    ], options: { callback: true, promise:false, returns: connect.Collection } },
+    { methods: [
+      'exist', 'list', 'read', 'readlines', 'unlink'
+    ], options: { callback: false, promise:false, static:true } },
+    { methods: [
+      'eof', 'destroy', 'chunkCollection'
+    ], options: { callback: false, promise:false } }
+  ]    
+}
+```
+
+Let's break down the object to see what it contains and how we can use it to wrap the code. The first part of the object is the.
+
+| `Parameter`          | `Type` | `Description`                              |
+| :------------- | :--------- | :-----------------------------------------------------------|
+| name | string | The name of the Prototype |
+| obj | object | The prototype object |
+| stream | boolean | Is the Prototype a stream |
+| instrumentations | array | Array of instrumentation integrations |
+
+Each of the entries in the `instrumentations` array contains a list of methods on the prototype and the associated metadata for those methods. Let's break down the examples from the GridStore object above.
+
+```js
+{ 
+  methods: ['open', 'getc', 'puts', 'write', 
+    'writeFile', 'close', 'unlink', 'readlines',
+    'rewind', 'read', 'tell', 'seek'], 
+  options: { 
+    callback: true, 
+    promise:false 
+  } 
+}
+```
+
+Looking at the instrumentation description above we see that the `methods` array is a list methods names on the GridStore prototype. The `options` object contains metadata about the methods describing their structure. In this case it tells us that these methods take a `callback` and do not return a `promise`. Let's look at some other examples of metadata.
+
+```js
+{ 
+  methods: ['collection'], 
+  options: { 
+    callback: true, 
+    promise:false, 
+    returns: [Collection] 
+  } 
+}
+```
+
+This options object contains one difference from the previous one, namely the `returns` field. In short this method provides both a callback and a return value. An example of this in the driver would be the `Db.prototype.collection` method that can either take a callback or just return a collection. Let's look at the next instrumentation.
+
+```js
+{ 
+  methods: ['exist', 'list', 'read', 'readlines', 'unlink'], 
+  options: { 
+    callback: false, 
+    promise:false, 
+    static:true 
+  } 
+}
+```
+
+The options contain the `static` field that tells us that all the methods in this instrumentation are on the `GridStore` directly. An example method might be `GridStore.exist`.
+
+```js
+{ 
+  methods: ['eof', 'destroy', 'chunkCollection'], 
+  options: { 
+    callback: false, 
+    promise:false 
+  } 
+}
+```
+
+The final example tells us the method don't take a callback, return a promise or any other value. Let's describe the available options.
+
+| `Parameter`          | `Type` | `Description`                              |
+| :------------- | :--------- | :-----------------------------------------------------------|
+| callback | boolean | Method accepts a callback |
+| promise | boolean | The method returns a promise |
+| returns | array | The method return an array of possible return values |
+| static | boolean | Method is static on the prototype |
+| cursor | boolean | Method returns a cursor object |
+
+Let's look at a simple example that wraps the callback only instrumentations.
+
+```js
+require('../..').instrument(function(err, instrumentations) {
+  instrumentations.forEach(function(obj) {
+    var object = obj.obj;
+    
+    // Iterate over all the methods that are just callback with no return
+    obj.instrumentations.forEach(function(instr) {
+      var options = instr.options;
+
+      if(options.callback 
+        && !options.promise 
+        && !options.returns && !options.static) {
+
+        // Method name
+        instr.methods.forEach(function(method) {
+          var applyMethod = function(_method) {
+            var func = object.prototype[_method];
+            object.prototype[_method] = function() {
+              if(!methodsCalled[_method]) methodsCalled[_method] = 0;
+              methodsCalled[_method] = methodsCalled[_method] + 1;
+              var args = Array.prototype.slice.call(arguments, 0);
+              func.apply(this, args);                
+            }                
+          }
+
+          applyMethod(method);
+        });
+      }
+    });
+  });
+});
+```
+
+## Available Integration Points
+
+Currently the available integration points are.
+
+| `Prototype`          | `Description`                              |
+| :------------- | :-----------------------------------------------------------|
+| Db | Db methods |
+| Collection | Collection methods |
+| GridStore | GridStore methods |
+| OrderedBulkOperation | Ordered bulk operation methods |
+| UnorderedBulkOperation | Unordered bulk operation methods |
+| CommandCursor | Command cursor queries |
+| AggregationCursor | Aggregation cursor queries |
+| Cursor | Query cursor queries |
+| Server | Low level server operations, return objects always contain the connection they where executed against |
+| ReplSet | Low level server operations, return objects always contain the connection they where executed against |
+| Mongos | Low level server operations, return objects always contain the connection they where executed against |
+
+
+
+
+
+
+
+
+
+
+

index.js

@@ -40,11 +40,37 @@ connect.connect = connect;
 // Instrumentation instance
 var instrumentation = null;
 
-// // Set up the instrumentation method
-// connect.instrument = function(options) {
-//   if(!instrumentation) instrumentation = new Instrumentation(core, options)
-//   return instrumentation;
-// }
+// Set up the instrumentation method
+connect.instrument = function(options) {
+  if(!instrumentation) instrumentation = new Instrumentation(core, options)
+  return instrumentation;
+}
+// Get prototype
+var AggregationCursor = require('./lib/aggregation_cursor'),
+  CommandCursor = require('./lib/command_cursor'),
+  OrderedBulkOperation = require('./lib/bulk/ordered').OrderedBulkOperation,
+  UnorderedBulkOperation = require('./lib/bulk/unordered').UnorderedBulkOperation,
+  Admin = require('./lib/admin');
+
+// Instrument Hook
+connect.instrument = function(callback) {
+  var instrumentations = []
+
+  // Classes to support
+  var classes = [connect.GridStore, connect.Server, connect.ReplSet, connect.Mongos,
+    OrderedBulkOperation, UnorderedBulkOperation, CommandCursor, AggregationCursor,
+    connect.Cursor, connect.Collection, connect.Db];
+
+  // Add instrumentations to the available list
+  for(var i = 0; i < classes.length; i++) {
+    if(classes[i].define) {
+      instrumentations.push(classes[i].define.generate());
+    }
+  }
+
+  // Return the list of instrumentation points
+  callback(null, instrumentations);
+}
 
 // Set our exports to be the connect function
 module.exports = connect;

lib/aggregation_cursor.js

@@ -11,6 +11,7 @@ var inherits = require('util').inherits
   , ReadPreference = require('./read_preference')
   , MongoError = require('mongodb-core').MongoError
   , Readable = require('stream').Readable || require('readable-stream').Readable
+  , Define = require('./metadata')
   , CoreCursor = require('./cursor')
   , Query = require('mongodb-core').Query
   , CoreReadPreference = require('mongodb-core').ReadPreference;
@@ -144,6 +145,8 @@ for(var name in CoreCursor.prototype) {
   AggregationCursor.prototype[name] = CoreCursor.prototype[name];
 }
 
+var define = AggregationCursor.define = new Define('AggregationCursor', AggregationCursor, true);
+
 /**
  * Set the batch size for the cursor.
  * @method
@@ -159,6 +162,8 @@ AggregationCursor.prototype.batchSize = function(value) {
   return this;
 }
 
+define.classMethod('batchSize', {callback: false, promise:false, returns: [AggregationCursor]});
+
 /**
  * Add a geoNear stage to the aggregation pipeline
  * @method
@@ -170,6 +175,8 @@ AggregationCursor.prototype.geoNear = function(document) {
   return this;
 }
 
+define.classMethod('geoNear', {callback: false, promise:false, returns: [AggregationCursor]});
+
 /**
  * Add a group stage to the aggregation pipeline
  * @method
@@ -181,6 +188,8 @@ AggregationCursor.prototype.group = function(document) {
   return this;
 }
 
+define.classMethod('group', {callback: false, promise:false, returns: [AggregationCursor]});
+
 /**
  * Add a limit stage to the aggregation pipeline
  * @method
@@ -192,6 +201,8 @@ AggregationCursor.prototype.limit = function(value) {
   return this;
 }
 
+define.classMethod('limit', {callback: false, promise:false, returns: [AggregationCursor]});
+
 /**
  * Add a match stage to the aggregation pipeline
  * @method
@@ -203,6 +214,8 @@ AggregationCursor.prototype.match = function(document) {
   return this;
 }
 
+define.classMethod('match', {callback: false, promise:false, returns: [AggregationCursor]});
+
 /**
  * Add a maxTimeMS stage to the aggregation pipeline
  * @method
@@ -216,6 +229,8 @@ AggregationCursor.prototype.maxTimeMS = function(value) {
   return this;
 }
 
+define.classMethod('maxTimeMS', {callback: false, promise:false, returns: [AggregationCursor]});
+
 /**
  * Add a out stage to the aggregation pipeline
  * @method
@@ -227,6 +242,8 @@ AggregationCursor.prototype.out = function(destination) {
   return this;
 }
 
+define.classMethod('out', {callback: false, promise:false, returns: [AggregationCursor]});
+
 /**
  * Add a project stage to the aggregation pipeline
  * @method
@@ -238,6 +255,8 @@ AggregationCursor.prototype.project = function(document) {
   return this;
 }
 
+define.classMethod('project', {callback: false, promise:false, returns: [AggregationCursor]});
+
 /**
  * Add a redact stage to the aggregation pipeline
  * @method
@@ -249,6 +268,8 @@ AggregationCursor.prototype.redact = function(document) {
   return this;
 }
 
+define.classMethod('redact', {callback: false, promise:false, returns: [AggregationCursor]});
+
 /**
  * Add a skip stage to the aggregation pipeline
  * @method
@@ -260,6 +281,8 @@ AggregationCursor.prototype.skip = function(value) {
   return this;
 }
 
+define.classMethod('skip', {callback: false, promise:false, returns: [AggregationCursor]});
+
 /**
  * Add a sort stage to the aggregation pipeline
  * @method
@@ -271,6 +294,8 @@ AggregationCursor.prototype.sort = function(document) {
   return this;
 }
 
+define.classMethod('sort', {callback: false, promise:false, returns: [AggregationCursor]});
+
 /**
  * Add a unwind stage to the aggregation pipeline
  * @method
@@ -282,8 +307,24 @@ AggregationCursor.prototype.unwind = function(field) {
   return this;
 }
 
+define.classMethod('unwind', {callback: false, promise:false, returns: [AggregationCursor]});
+
 AggregationCursor.prototype.get = AggregationCursor.prototype.toArray;
 
+define.classMethod('get', {callback: true, promise:false});
+
+// Inherited methods
+define.classMethod('toArray', {callback: true, promise:false});
+define.classMethod('each', {callback: true, promise:false});
+define.classMethod('forEach', {callback: true, promise:false});
+define.classMethod('next', {callback: true, promise:false});
+define.classMethod('explain', {callback: true, promise:false});
+define.classMethod('close', {callback: true, promise:false});
+define.classMethod('isClosed', {callback: false, promise:false, returns: [Boolean]});
+define.classMethod('rewind', {callback: false, promise:false});
+define.classMethod('bufferedCount', {callback: false, promise:false, returns: [Number]});
+define.classMethod('readBufferedDocuments', {callback: false, promise:false, returns: [Array]});
+
 /**
  * Get the next available document from the cursor, returns null if no more documents are available.
  * @function AggregationCursor.prototype.next

lib/bulk/ordered.js

@@ -9,6 +9,7 @@ var common = require('./common')
   , BulkWriteResult = common.BulkWriteResult
   , LegacyOp = common.LegacyOp
   , ObjectID = require('mongodb-core').BSON.ObjectID
+  , Define = require('../metadata')
   , Batch = common.Batch
   , mergeBatchResults = common.mergeBatchResults;
 
@@ -288,6 +289,8 @@ function OrderedBulkOperation(topology, collection, options) {
   }
 }
 
+var define = OrderedBulkOperation.define = new Define('OrderedBulkOperation', OrderedBulkOperation, false);
+
 OrderedBulkOperation.prototype.raw = function(op) {
   var key = Object.keys(op)[0];
 
@@ -498,6 +501,8 @@ OrderedBulkOperation.prototype.execute = function(_writeConcern, callback) {
   });
 }
 
+define.classMethod('execute', {callback: true, promise:false});
+
 /**
  * Returns an unordered batch object
  * @ignore
@@ -506,5 +511,6 @@ var initializeOrderedBulkOp = function(topology, collection, options) {
 	return new OrderedBulkOperation(topology, collection, options);
 }
 
+initializeOrderedBulkOp.OrderedBulkOperation = OrderedBulkOperation;
 module.exports = initializeOrderedBulkOp;
 module.exports.Bulk = OrderedBulkOperation;