DOCSP-46689: Monitoring (#166)

(cherry picked from commit 0741c1b)

Author: mcmorisi

source/includes/monitoring/monitoring.py

@@ -0,0 +1,27 @@
+from pymongo import MongoClient
+from pymongo.monitoring import CommandListener, CommandSucceededEvent, ServerListener, \
+    ConnectionPoolListener, ServerHeartbeatStartedEvent, \
+    ConnectionCreatedEvent
+
+# start-monitoring
+class MyCommandListener(CommandListener):
+    def succeeded(self, event: CommandSucceededEvent):
+        print(f"Command {event.command_name} succeeded")
+
+    # Include other event method implementations here
+
+class MyServerListener(ServerListener):
+    def heartbeat_started(self, event: ServerHeartbeatStartedEvent):
+        print(f"Heartbeat started on server with id: {event.connection_id}")
+
+    # Include other event method implementations here
+
+class MyPoolListener(ConnectionPoolListener):
+    def connection_created(self, event: ConnectionCreatedEvent):
+        print(f"Connection {event.connection_id} created")
+
+    # Include other event method implementations here
+
+listeners = [MyCommandListener(), MyServerListener(), MyPoolListener()]
+client = MongoClient("<connection URI>", event_listeners=listeners)
+# end-monitoring

source/index.txt

@@ -23,6 +23,7 @@ MongoDB {+driver-short+} Documentation
    Security </security>
    Data Formats </data-formats>
    Logging </logging>
+   Monitoring </monitoring>
    Third-Party Tools </tools>
    FAQ </faq>
    Troubleshooting </troubleshooting>

source/monitoring.txt

@@ -0,0 +1,98 @@
+.. _pymongo-monitoring:
+
+==========
+Monitoring
+==========
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: event, subscribe, listener
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn how to configure **monitoring** in {+driver-short+}
+by using {+driver-short+}'s callback-based interface. Monitoring is the process of
+gathering information about your application's performance and resource usage as it runs.
+This can help you make informed decisions when designing and debugging your application.
+
+The driver provides information about your application by emitting events. You can
+listen for driver events to monitor your application.
+
+.. note:: Event Logging
+
+   This page explains how to monitor your application in code. To learn how to record
+   this information to an external log, see the :ref:`pymongo-logging` guide.
+
+Event Types
+-----------
+
+The type of event that the driver emits depends on the operation being performed.
+The following table describes the types of events that the driver emits:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Event Type
+     - Description
+   * - Command events
+     - Events related to MongoDB database commands, such as ``find``, ``insert``,
+       ``delete``, and ``count``. To learn how to use {+driver-short+} to run a
+       database command, see :ref:`<pymongo-run-command>`. For more information about
+       MongoDB database commands, see :manual:`Database Commands </reference/command/>`
+       in the {+mdb-server+} manual.
+
+       As a security measure, the driver redacts the contents of some
+       command events. This protects the sensitive information contained in these command
+       events.
+
+   * - Server Discovery and Monitoring (SDAM) events
+     - Events related to changes in the state of the MongoDB deployment.
+
+   * - Connection Pool events
+     - Events related to the connection pool held by the driver.
+
+For a complete list of events the driver emits, see the
+`pymongo.monitoring <{+api-root+}pymongo/monitoring.html>`__ API documentation.
+
+Listening for Events
+--------------------
+
+To monitor an event, you must pass an event listener to your application's ``MongoClient``.
+The following steps describe how to monitor your application by using an event listener:
+
+1. Create a class that inherits from one of the event listener base classes
+   provided by {+driver-short+}. The base class you choose depends on the type of event
+   you want to monitor. For example, to monitor command events, create a class
+   that inherits from ``CommandListener``.
+#. Implement the methods of the base class that correpond to the events you want to monitor.
+#. Pass an instance of your listener class to the ``MongoClient`` constructor.
+
+The following code implements a ``CommandListener`` to listen for command events, a
+``ServerListener`` to listen for SDAM events, and a ``ConnectionPoolListener`` to listen for
+connection pool events:
+
+.. literalinclude:: /includes/monitoring/monitoring.py
+   :language: python
+   :start-after: start-monitoring
+   :end-before: end-monitoring
+   :copyable: true
+
+API Documentation
+-----------------
+
+To learn more about the methods and classes used to monitor events in the driver, see the
+following API documentation:
+
+- `monitoring <{+api-root+}pymongo/monitoring.html>`__
+- `MongoClient <{+api-root+}pymongo/mongo_client.html#pymongo.mongo_client.MongoClient>`__