command-monitoring.txt

.. _node-command-monitoring:

==================
Command Monitoring
==================

.. facet::
   :name: genre
   :values: reference

.. meta:: 
   :keywords: code example, node.js, watch, command status
   :description: Monitor the success or failure of MongoDB commands by subscribing to command monitoring events in your application.

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecols

Overview
--------

This guide shows you how to monitor the success or failure of commands
sent by the driver to your MongoDB deployment.

The following sections demonstrate how to record command status in your
application and explore the information provided in these events.

Event Subscription Example
--------------------------

You can access one or more command monitoring events using the driver by
subscribing to them in your application. The following example demonstrates
connecting to a replica set and subscribing to one of the command monitoring
events created by the MongoDB deployment:

.. literalinclude:: /code-snippets/monitoring/apm-subscribe.js
   :language: javascript

.. note::

   Command monitoring is disabled by default. To enable command
   monitoring, pass the ``monitorCommands`` option as ``true`` to
   your ``MongoClient`` constructor. 

Event Descriptions
------------------

You can subscribe to any of the following command monitoring events:

.. list-table::
   :widths: 33 67
   :header-rows: 1

   * - Event Name
     - Description

   * - ``commandStarted``
     - Created when a command is started.

   * - ``commandSucceeded``
     - Created when a command succeeded.

   * - ``commandFailed``
     - Created when a command failed.

Example Event Documents
-----------------------

The following sections show sample output for each type of command monitoring event.

commandStarted
^^^^^^^^^^^^^^

.. code-block:: javascript
   :copyable: false

   CommandStartedEvent {
     requestId: 1534,
     databaseName: "app",
     commandName: "find",
     address: 'localhost:27017',
     connectionId: 812613,
     command: {
       find: { firstName: "Jane", lastName: "Doe" }
     }
   }

commandSucceeded
^^^^^^^^^^^^^^^^

.. code-block:: javascript
   :copyable: false

   CommandSucceededEvent {
     requestId: 1534,
     commandName: "find",
     address: 'localhost:27017',
     connectionId: 812613,
     duration: 15,
     reply: {
       cursor: {
         firstBatch: [
           {
             _id: ObjectId("5e8e2ca217b5324fa9847435"),
             firstName: "Jane",
             lastName: "Doe"
           }
         ],
         _id: 0,
         ns: "app.users"
       },
       ok: 1,
       operationTime: 1586380205
     }
   }


commandFailed
^^^^^^^^^^^^^

.. code-block:: javascript
   :copyable: false

   CommandFailedEvent {
     requestId: 1534,
     commandName: "find",
     address: 'localhost:27017',
     connectionId: 812613,
     failure: Error("something failed"),
     duration: 11
   }