===
APM
===

Application Performance Monitoring support is a driver
feature that allows monitoring services to hook into the
driver in a forward compatible and stable way. The API is
not applied to the driver unless explicitly initialized to
avoid any performance penalties.

API
---

The following code example shows how to enable Command Monitoring

.. code-block:: js

   const { MongoClient } = require('mongodb');

   // Connection URL
   const url = 'mongodb://localhost:27017';
   
   
   const client = new MongoClient(url, {
     // Enables APM
     monitorCommands: true
   });

   client.on('commandStarted', event => {
     // command start event (see https://github.com/mongodb/specifications/blob/master/source/command-monitoring/command-monitoring.rst)
   });

   client.on('commandSucceeded', event => {
     // command success event (see https://github.com/mongodb/specifications/blob/master/source/command-monitoring/command-monitoring.rst)
   });

   client.on('commandFailed', event => {
     // command failure event (see https://github.com/mongodb/specifications/blob/master/source/command-monitoring/command-monitoring.rst)
   });

Command Monitoring
------------------

Command monitoring is based on the cross-driver specification for MongoDB found in the Command monitoring `specification <https://github.com/mongodb/specifications/blob/master/source/command-monitoring/command-monitoring.rst>`_.

The Command monitoring specification is a low-level monitoring specification that sends a notification when a new command is executed against MongoDB and if it fails or succeeds. In most cases this is straightforward and you will receive a single start and either a success or failure event. 

In this example, the user executes the ``isMaster`` command against the server and receives the following messages (full objects are abbreviated for simplicity's sake). When the ``isMaster`` command starts execution we receive the following event (this result is from ``JSON.stringify``\ ; in the real event the connectionId is the actual connection object the command was executed against).

.. code-block:: js

   {
     "command": {
       "ismaster": true
     },
     "databaseName": "system",
     "commandName": "ismaster",
     "requestId": 7,
     "operationId": 1,
     "connectionId": {
       "id": 8,
       "host": "localhost",
       "port": 27017
     }
   }

   {
    "command": {
      "ismaster": 1,
      "lsid": {
        "id": "+qymQ+CFSySihSWSFC0kWw=="
      },
      "$db": "test"
    },
    "databaseName": "test",
    "commandName": "ismaster",
    "requestId": 1,
    "connectionId": "localhost:27017"
  }

``requestId`` is the id used for the wire protocol message sent to MongoDB and allows you to correlate the commands executed on MongoDB with the commands from the driver.

After the command executed successfully it sends the following result:

.. code-block:: js

   {
     "duration": 4.51708,
     "commandName": "ismaster",
     "reply": {
       "ismaster": true,
       "maxBsonObjectSize": 16777216,
       "maxMessageSizeBytes": 48000000,
       "maxWriteBatchSize": 100000,
       "localTime": "2019-10-11T21:14:44.793Z",
       "logicalSessionTimeoutMinutes": 30,
       "minWireVersion": 0,
       "maxWireVersion": 7,
       "readOnly": false,
       "ok": 1
     },
     "requestId": 1,
     "connectionId": "localhost:27017"
   }

Notice that the ``requestId`` matches up to the start message, allowing the user of the API to correlate the two events. 
