diff --git a/source/includes/monitoring/monitoring.py b/source/includes/monitoring/monitoring.py new file mode 100644 index 00000000..4b8ff2fa --- /dev/null +++ b/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("", event_listeners=listeners) +# end-monitoring \ No newline at end of file diff --git a/source/index.txt b/source/index.txt index d131f2ad..e375ec73 100644 --- a/source/index.txt +++ b/source/index.txt @@ -23,6 +23,7 @@ MongoDB {+driver-short+} Documentation Security Data Formats Logging + Monitoring Third-Party Tools FAQ Troubleshooting diff --git a/source/monitoring.txt b/source/monitoring.txt new file mode 100644 index 00000000..7e34c857 --- /dev/null +++ b/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:``. For more information about + MongoDB database commands, see :manual:`Database Commands ` + 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>`__ \ No newline at end of file