From 826abec5d89941f0061e8a86f8bcfcf1d7f6ad06 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Tue, 28 Jan 2025 16:13:38 -0500 Subject: [PATCH 01/14] monitoring page --- source/includes/monitoring_JMX.kt | 30 ++ source/includes/monitoring_counter.kt | 45 +++ source/includes/monitoring_librarian.kt | 38 +++ source/includes/monitoring_writable.kt | 49 +++ source/monitoring.txt | 384 ++++++++++++++++++++++++ 5 files changed, 546 insertions(+) create mode 100644 source/includes/monitoring_JMX.kt create mode 100644 source/includes/monitoring_counter.kt create mode 100644 source/includes/monitoring_librarian.kt create mode 100644 source/includes/monitoring_writable.kt create mode 100644 source/monitoring.txt diff --git a/source/includes/monitoring_JMX.kt b/source/includes/monitoring_JMX.kt new file mode 100644 index 00000000..c5839a72 --- /dev/null +++ b/source/includes/monitoring_JMX.kt @@ -0,0 +1,30 @@ +import com.mongodb.kotlin.client.MongoClient +import org.bson.json.JsonWriterSettings +import com.mongodb.event.* +import com.mongodb.MongoClientSettings +import com.mongodb.ConnectionString +import com.mongodb.management.JMXConnectionPoolListener + + +fun main() { + val uri = "" + +// Instantiate your JMX listener + val connectionPoolListener = JMXConnectionPoolListener() + +// Include the listener in your client settings + val settings = MongoClientSettings.builder() + .applyConnectionString(ConnectionString(uri)) + .addCommandListener(connectionPoolListener) + .build() + +// Pause execution + try { + println("Navigate to JConsole to see your connection pools...") + Thread.sleep(Long.MAX_VALUE) + } catch (e: Exception) { + e.printStackTrace() + } + + mongoClient.close() +} \ No newline at end of file diff --git a/source/includes/monitoring_counter.kt b/source/includes/monitoring_counter.kt new file mode 100644 index 00000000..69412879 --- /dev/null +++ b/source/includes/monitoring_counter.kt @@ -0,0 +1,45 @@ +import com.mongodb.kotlin.client.MongoClient +import org.bson.json.JsonWriterSettings +import com.mongodb.event.* +import com.mongodb.MongoClientSettings +import com.mongodb.ConnectionString + +class CommandCounter : CommandListener { + private val commands = mutableMapOf() + + override fun commandSucceeded(event: CommandSucceededEvent) { + val commandName = event.commandName + val count = commands[commandName] ?: 0 + commands[commandName] = count + 1 + println(commands.toString()) + } + + override fun commandFailed(event: CommandFailedEvent) { + println("Failed execution of command '${event.commandName}' with id ${event.requestId}") + } +} + + +fun main() { + val uri = "" + +// Instantiate your new listener + val commandCounter = CommandCounter() + +// Include the listener in your client settings + val settings = MongoClientSettings.builder() + .applyConnectionString(ConnectionString(uri)) + .addCommandListener(commandCounter) + .build() + +// Connect to your database + val mongoClient = MongoClient.create(settings) + val database = mongoClient.getDatabase("sample_mflix") + val collection = database.getCollection("movies") + +// Run some commands to test the counter + collection.find().firstOrNull() + collection.find().firstOrNull() + + mongoClient.close() +} \ No newline at end of file diff --git a/source/includes/monitoring_librarian.kt b/source/includes/monitoring_librarian.kt new file mode 100644 index 00000000..4ed5f805 --- /dev/null +++ b/source/includes/monitoring_librarian.kt @@ -0,0 +1,38 @@ +import com.mongodb.kotlin.client.MongoClient +import org.bson.json.JsonWriterSettings +import com.mongodb.event.* +import com.mongodb.MongoClientSettings +import com.mongodb.ConnectionString + +class ConnectionPoolLibrarian : ConnectionPoolListener { + override fun connectionCheckedOut(event: ConnectionCheckedOutEvent) { + println("Let me get you the connection with id ${event.connectionId.localValue}...") + } + override fun connectionCheckOutFailed(event: ConnectionCheckOutFailedEvent) { + println("Something went wrong! Failed to checkout connection.") + } +} + + +fun main() { + val uri = "" + +// Instantiate your new listener +val cpListener = ConnectionPoolLibrarian() + +// Include the listener in your client settings + val settings = MongoClientSettings.builder() + .applyConnectionString(ConnectionString(uri)) + .addCommandListener(cpListener) + .build() + +// Connect to your database + val mongoClient = MongoClient.create(settings) + val database = mongoClient.getDatabase("sample_mflix") + val collection = database.getCollection("movies") + +// Run some commands to test the counter + collection.find().firstOrNull() + + mongoClient.close() +} \ No newline at end of file diff --git a/source/includes/monitoring_writable.kt b/source/includes/monitoring_writable.kt new file mode 100644 index 00000000..df1e4e78 --- /dev/null +++ b/source/includes/monitoring_writable.kt @@ -0,0 +1,49 @@ +import com.mongodb.kotlin.client.MongoClient +import org.bson.json.JsonWriterSettings +import com.mongodb.event.* +import com.mongodb.MongoClientSettings +import com.mongodb.ConnectionString + +class IsWriteable : ClusterListener { + private var isWritable = false + + override fun clusterDescriptionChanged(event: ClusterDescriptionChangedEvent) { + if (!isWritable) { + if (event.newDescription.hasWritableServer()) { + isWritable = true + println("Able to write to cluster") + } + } else { + if (!event.newDescription.hasWritableServer()) { + isWritable = false + println("Unable to write to cluster") + } + } + } +} + + +fun main() { + val uri = "" + +// Instantiate your new listener + val clusterListener = IsWriteable() + +// Include the listener in your client settings + val settings = MongoClientSettings.builder() + .applyConnectionString(ConnectionString(uri)) + .applyToClusterSettings { builder -> + builder.addClusterListener(clusterListener) + } + .build() + +// Connect to your database + val mongoClient = MongoClient.create(settings) + val database = mongoClient.getDatabase("sample_mflix") + val collection = database.getCollection("movies") + +// Run a command to trigger a ClusterDescriptionChangedEvent event + collection.find().firstOrNull() + + mongoClient.close() +} \ No newline at end of file diff --git a/source/monitoring.txt b/source/monitoring.txt new file mode 100644 index 00000000..f7cfd39d --- /dev/null +++ b/source/monitoring.txt @@ -0,0 +1,384 @@ +========== +Monitoring +========== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to set up and configure **monitoring** in the +MongoDB Kotlin driver. + +Monitoring is the process of getting information about the activities a running +program performs for use in an application or an application performance +management library. + +Monitoring the MongoDB Kotlin driver lets you understand the +driver's resource usage and performance, and can help you make informed +decisions when designing and debugging your application. + +In this guide you will learn how to perform these tasks: + +- :ref:`Monitor different types of events in the MongoDB Kotlin driver ` +- :ref:`Monitor connection pool events with Java Management Extensions (JMX) and JConsole ` + +This guide shows how to use information about the meta activity of the driver. +If you would like to learn how to record data transactions, consider reading +our :ref:`Monitoring Data Changes ` page. + +.. _monitoring-monitor-events: + +Monitor Events +-------------- + +To monitor an **event**, you must register a **listener** on your ``MongoClient`` +instance. + +An event is any action that happens in a running program. The driver includes functionality +for listening to a subset of the events that occur when the driver is running. + +A listener is a class that performs some action when certain events occur. +A listener's API defines the events it can respond to. + +Each method of a listener class represents a response to a certain event. Each +method receives one argument: an object representing the event the method +responds to. + +The MongoDB Kotlin driver organizes the events it defines into three categories: + +- Command Events +- Server Discovery and Monitoring Events +- Connection Pool Events + +The following sections show how to monitor each event category. + +For a full list of the events you can monitor, +`see the event package of the MongoDB Kotlin driver <{+api+}/apidocs/mongodb-driver-core/com/mongodb/event/package-summary.html>`__. + +.. _command-events-kotlin: + +Command Events +~~~~~~~~~~~~~~ + +A command event is an event related to a MongoDB database command. Some +examples of database commands that produce command events are ``find``, +``insert``, ``delete``, and ``count``. + +To monitor command events, write a class that implements the +``CommandListener`` interface and register an instance of that class with your +``MongoClient`` instance. + +For more information on MongoDB database commands, see the +:manual:`MongoDB manual entry on database commands `. + +.. note:: Internal Commands + + The driver does not publish events for commands it calls internally. This + includes database commands the driver uses to monitor your cluster and + commands related to connection establishment (such as the initial ``hello`` + command). + +.. important:: Redacted Output + + As a security measure, the driver redacts the contents of some command events. This + protects the sensitive information contained in these command events. For a + full list of redacted command events, see the + :spec:`MongoDB command logging and monitoring specification `. + +Example +^^^^^^^ + +This example shows how to make a counter for database commands. The counter +keeps track of the number of times the driver successfully executes each database +command, and prints this information every time a database command finishes. + +To make a counter, do the following: + +#. Make a class with counter functionality that implements the ``CommandListener`` interface. +#. Add an instance of the new class that implements ``CommandListener`` to a ``MongoClientSettings`` object. +#. Configure a ``MongoClient`` instance with the ``MongoClientSettings`` object. + +The following code defines the ``CommandCounter`` class which implements the +``CommandListener`` interface, then adds an instance of the ``CommandCounter`` class to a +``MongoClientSettings`` object. Then it configures a ``MongoClient`` instance with the +``MongoClientSettings`` object. The code then runs some database commands to test the +counter: + +.. _listener-mongo-client-settings-example: + +.. io-code-block:: + + .. input:: /includes/monitoring_counter.kt + :language: kotlin + + .. output:: + :language: console + + {find=1} + {find=2} + {find=2, endSessions=1} + +For more information on the classes and methods mentioned in this section, see +the following API Documentation: + +- `CommandListener <{+api+}/apidocs/mongodb-driver-core/com/mongodb/event/CommandListener.html>`__ +- `MongoClientSettings <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html>`__ +- `MongoClient <{+api+}/apidocs/mongodb-driver-kotlin-sync/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-client/index.html>`__ +- `CommandStartedEvent <{+api+}/apidocs/mongodb-driver-core/com/mongodb/event/CommandStartedEvent.html>`__ +- `CommandSucceededEvent <{+api+}/apidocs/mongodb-driver-core/com/mongodb/event/CommandSucceededEvent.html>`__ +- `CommandFailedEvent <{+api+}/apidocs/mongodb-driver-core/com/mongodb/event/CommandFailedEvent.html>`__ + +Server Discovery and Monitoring Events +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A server discovery and monitoring (SDAM) event is an event related to a change +in the state of the MongoDB instance or cluster you have connected the driver to. + +The driver defines nine SDAM events. The driver divides these nine events +between three separate listener interfaces which each listen for three of the +nine events. Here are the three interfaces and the events they listen for: + +- ``ClusterListener``: topology-related events +- ``ServerListener``: events related to ``mongod`` or ``mongos`` processes +- ``ServerMonitorListener``: heartbeat related events + +To monitor a type of SDAM event, write a class that +implements one of the three preceding interfaces and register an instance of that +class with your ``MongoClient`` instance. + +For a detailed description of each SDAM event, see the :spec:`MongoDB SDAM monitoring events specification `. + +Example +^^^^^^^ + +This example shows how to make a listener class that prints a message that lets +you know if the driver can write to your MongoDB instance. + +The following code defines the ``IsWritable`` class which implements the +``ClusterListener`` interface. Then it adds an instance of the ``IsWritable`` class to a +``MongoClient`` object. The code then runs a find operation to test the +``IsWritable`` class: + +.. io-code-block:: + + .. input:: /includes/monitoring_writable.kt + :language: kotlin + + .. output:: + :language: console + + Able to write to server + +For more information on the classes and methods mentioned in this section, see +the following API Documentation: + +- `ClusterListener <{+api+}/apidocs/mongodb-driver-core/com/mongodb/event/ClusterListener.html>`__ +- `ServerListener <{+api+}/apidocs/mongodb-driver-core/com/mongodb/event/ServerListener.html>`__ +- `ServerMonitorListener <{+api+}/apidocs/mongodb-driver-core/com/mongodb/event/ServerMonitorListener.html>`__ +- `MongoClientSettings <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html>`__ +- `MongoClient <{+api+}/apidocs/mongodb-driver-kotlin-sync/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-client/index.html>`__ +- `ClusterDescriptionChangedEvent <{+api+}/apidocs/mongodb-driver-core/com/mongodb/event/ClusterDescriptionChangedEvent.html>`__ + +Connection Pool Events +~~~~~~~~~~~~~~~~~~~~~~ + +A connection pool event is an event related to a **connection pool** held by the driver. +A connection pool is a set of open TCP connections your driver maintains with +a MongoDB instance. Connection pools help reduce the number of network handshakes +your application needs to perform with a MongoDB instance, and can help your +application run faster. + +To monitor connection pool events, write a class that implements the +``ConnectionPoolListener`` interface and register an instance of that class with your +``MongoClient`` instance. + +Example +^^^^^^^ + +This example shows how to make a listener class that prints a message each time +you check out a connection from your connection pool. + +The following code defines the ``ConnectionPoolLibrarian`` class which implements the +``ConnectionPoolListener`` interface. Then it adds an instance of the +``ConnectionPoolLibrarian`` class to a ``MongoClient`` object. The code then +runs a database command to test the librarian. + +.. io-code-block:: + + .. input:: /includes/monitoring_librarian.kt + :language: kotlin + + .. output:: + :language: console + + Let me get you the connection with id 21... + +For more information on the classes and methods mentioned in this section, see +the following API Documentation: + +- `ConnectionPoolListener <{+api+}/apidocs/mongodb-driver-core/com/mongodb/event/ConnectionPoolListener.html>`__ +- `MongoClientSettings <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html>`__ +- `MongoClient <{+api+}/apidocs/mongodb-driver-kotlin-sync/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-client/index.html>`__ +- `ConnectionCheckedOutEvent <{+api+}/apidocs/mongodb-driver-core/com/mongodb/event/ConnectionCheckedOutEvent.html>`__ +- `ConnectionCheckOutFailedEvent <{+api+}/apidocs/mongodb-driver-core/com/mongodb/event/ConnectionCheckOutFailedEvent.html>`__ + +.. _monitoring-jmx: + +Monitor Connection Pool Events with JMX +--------------------------------------- + +You can monitor connection pool events using **Java Management Extensions (JMX)**. +JMX provides tools to monitor applications and devices. + +For more information on JMX, see +`the official Oracle JMX documentation `__. + +JMX Support +~~~~~~~~~~~ + +To enable JMX connection pool monitoring, add an instance of the +``JMXConnectionPoolListener`` class to your ``MongoClient`` object. + +The ``JMXConnectionPoolListener`` class performs the following actions: + +#. Creates MXBean instances for each ``mongod`` or ``mongos`` process the driver + maintains a connection pool with. +#. Registers these MXBean instances with the platform MBean server. + +MXBeans registered on the platform MBean server have the following properties: + +.. list-table:: + :header-rows: 1 + :widths: 10 20 + + * - Property + - Description + + * - ``clusterId`` + - A client-generated unique identifier. This identifier ensures that + each MXBean the driver makes has a unique name when an application has + multiple ``MongoClient`` instances connected to the same MongoDB deployment. + + * - ``host`` + - The hostname of the machine running the ``mongod`` or ``mongos`` process. + + * - ``port`` + - The port on which the ``mongod`` or ``mongos`` process is listening. + + * - ``minSize`` + - The minimum size of the connection pool, including idle and in-use connections. + + * - ``maxSize`` + - The maximum size of the connection pool, including idle and in-use connections. + + * - ``size`` + - The current size of the connection pool, including idle and in-use connections. + + * - ``checkedOutCount`` + - The current count of connections that are in use. + + +All MXBean instances created by the driver are under the domain +``"org.mongodb.driver"``. + +For more information on the topics discussed in this subsection, see the +following resources from Oracle: + +- `Platform MBean Server Reference Documentation `__ +- `MXBean Documentation `__ +- `MBean Documentation `__ + +JMX and JConsole Example +~~~~~~~~~~~~~~~~~~~~~~~~ + +This example shows how you can monitor the driver's connection pools using JMX +and **JConsole**. JConsole is a JMX compliant GUI monitoring tool that comes with +the Java Platform. + +.. tip:: Consult the Official JMX and JConsole Documentation + + The descriptions of JMX and JConsole in this example are illustrative + rather than a source of truth. For guaranteed up to date information, consult + the following official Oracle resources: + + - `JConsole documentation `__. + - `JMX documentation `__ + +The following code snippet adds a ``JMXConnectionPoolListener`` to a +``MongoClient`` instance. The code then pauses execution so you can +navigate to JConsole and inspect your connection pools. + +.. io-code-block:: + + .. input:: /includes/monitoring_JMX.kt + :language: kotlin + + .. output:: + :language: console + + Navigate to JConsole to see your connection pools... + +Once you have started your server, open JConsole in your terminal using the +following command: + +.. code-block:: shell + + jconsole + +Once JConsole is open, perform the following actions in the GUI: + +#. Select the process running the preceding example code. +#. Press :guilabel:`Insecure Connection` in the warning dialog box. +#. Click on the :guilabel:`MBeans` tab. +#. Inspect your connection pool events under the ``"org.mongodb.driver"`` domain. + +When you no longer want to inspect your connection pools in JConsole, do the +following: + +- Exit JConsole by closing the JConsole window +- Stop the program running the preceding code snippet + +For more information on JMX and JConsole, see the following resources from +Oracle: + +- `JConsole Documentation `__. +- `Monitoring and Management Guide `__ + +For more information on the ``JMXConnectionPoolListener`` class, see +the API Documentation for +`JMXConnectionPoolListener <{+api+}/apidocs/mongodb-driver-core/com/mongodb/management/JMXConnectionPoolListener.html>`__. + +Include the Driver in Your Distributed Tracing System +----------------------------------------------------- + +If you use a **distributed tracing system**, you can include event data from the +driver. A distributed tracing system is an application that +tracks requests as they propagate throughout different services in a +service-oriented architecture. + +If you use the driver in a `Spring Cloud `__ +application, use +`Spring Cloud Sleuth `__ to +include MongoDB event data in the +`Zipkin `__ distributed tracing system. + +If you do not use Spring Cloud or need to include driver event data in a distributed +tracing system other than Zipkin, you must write a command event listener that +manages `spans `__ +for your desired distributed tracing system. To see an implementation of such a +listener, see the Java source code for the +:github:`TraceMongoCommandListener +` +class in the Spring Cloud Sleuth source code. + +To learn more about Spring Cloud Sleuth, see +`Getting Started `__ +in the Spring Cloud Sleuth documentation. + +To view a detailed description of a distributed tracing system, see +`Dapper `__ from Google Research. From 00e71f2b8318603882b68dbf6d4aa0fb83672121 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Wed, 29 Jan 2025 08:37:11 -0500 Subject: [PATCH 02/14] rebase --- source/index.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/source/index.txt b/source/index.txt index 902854c6..4534ed0f 100644 --- a/source/index.txt +++ b/source/index.txt @@ -23,6 +23,7 @@ Specialized Data Formats Builders Run a Command + Monitoring Security In-Use Encryption Compatibility From ab48182b7c00cfae323e6b2141141bcf3a973400 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Wed, 29 Jan 2025 08:45:39 -0500 Subject: [PATCH 03/14] vaile --- source/monitoring.txt | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/source/monitoring.txt b/source/monitoring.txt index f7cfd39d..e7254fed 100644 --- a/source/monitoring.txt +++ b/source/monitoring.txt @@ -28,8 +28,7 @@ In this guide you will learn how to perform these tasks: - :ref:`Monitor connection pool events with Java Management Extensions (JMX) and JConsole ` This guide shows how to use information about the meta activity of the driver. -If you would like to learn how to record data transactions, consider reading -our :ref:`Monitoring Data Changes ` page. +To learn how to record data transactions, see the :ref:`Monitoring Data Changes ` page. .. _monitoring-monitor-events: @@ -190,7 +189,7 @@ Connection Pool Events A connection pool event is an event related to a **connection pool** held by the driver. A connection pool is a set of open TCP connections your driver maintains with a MongoDB instance. Connection pools help reduce the number of network handshakes -your application needs to perform with a MongoDB instance, and can help your +your application performs with a MongoDB instance, and can help your application run faster. To monitor connection pool events, write a class that implements the @@ -367,7 +366,7 @@ application, use include MongoDB event data in the `Zipkin `__ distributed tracing system. -If you do not use Spring Cloud or need to include driver event data in a distributed +If you do not use Spring Cloud or want to include driver event data in a distributed tracing system other than Zipkin, you must write a command event listener that manages `spans `__ for your desired distributed tracing system. To see an implementation of such a From 99d7ec8ec4308ef52d90daa12125fa8c88b2e6d0 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Wed, 29 Jan 2025 10:18:13 -0500 Subject: [PATCH 04/14] title change --- source/index.txt | 2 +- source/monitoring.txt | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/source/index.txt b/source/index.txt index 4534ed0f..154853be 100644 --- a/source/index.txt +++ b/source/index.txt @@ -23,7 +23,7 @@ Specialized Data Formats Builders Run a Command - Monitoring + Cluster Monitoring Security In-Use Encryption Compatibility diff --git a/source/monitoring.txt b/source/monitoring.txt index e7254fed..835bd93b 100644 --- a/source/monitoring.txt +++ b/source/monitoring.txt @@ -1,6 +1,6 @@ -========== -Monitoring -========== +================== +Cluster Monitoring +================== .. contents:: On this page :local: From d7dd4c825a6f4ae2881b5ea46ed81d93641a7d08 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Wed, 29 Jan 2025 14:44:33 -0500 Subject: [PATCH 05/14] NR feedback 1 --- source/index.txt | 2 +- source/monitoring.txt | 41 ++++++++++++++++++++--------------------- 2 files changed, 21 insertions(+), 22 deletions(-) diff --git a/source/index.txt b/source/index.txt index 154853be..4534ed0f 100644 --- a/source/index.txt +++ b/source/index.txt @@ -23,7 +23,7 @@ Specialized Data Formats Builders Run a Command - Cluster Monitoring + Monitoring Security In-Use Encryption Compatibility diff --git a/source/monitoring.txt b/source/monitoring.txt index 835bd93b..46533789 100644 --- a/source/monitoring.txt +++ b/source/monitoring.txt @@ -1,6 +1,6 @@ -================== -Cluster Monitoring -================== +========== +Monitoring +========== .. contents:: On this page :local: @@ -12,23 +12,25 @@ Overview -------- In this guide, you can learn how to set up and configure **monitoring** in the -MongoDB Kotlin driver. +{+driver-short+}. Monitoring is the process of getting information about the activities a running program performs for use in an application or an application performance management library. -Monitoring the MongoDB Kotlin driver lets you understand the -driver's resource usage and performance, and can help you make informed -decisions when designing and debugging your application. +Monitoring the {+driver-short+} to monitor cluster, driver command, and +connection pool events. These features help you make informed decisions when +designing and debugging your application. In this guide you will learn how to perform these tasks: -- :ref:`Monitor different types of events in the MongoDB Kotlin driver ` +- :ref:`Monitor specific events by using the {+driver-short+} ` - :ref:`Monitor connection pool events with Java Management Extensions (JMX) and JConsole ` -This guide shows how to use information about the meta activity of the driver. -To learn how to record data transactions, see the :ref:`Monitoring Data Changes ` page. +.. tip:: + + This guide shows how to use information about the meta activity of the driver. + To learn how to record data transactions, see the :ref:`Monitoring Data Changes ` page. .. _monitoring-monitor-events: @@ -44,20 +46,17 @@ for listening to a subset of the events that occur when the driver is running. A listener is a class that performs some action when certain events occur. A listener's API defines the events it can respond to. -Each method of a listener class represents a response to a certain event. Each -method receives one argument: an object representing the event the method -responds to. - -The MongoDB Kotlin driver organizes the events it defines into three categories: +Each method of a listener class represents a response to a certain event, and +accepts as an argument an event object representing the event. -- Command Events -- Server Discovery and Monitoring Events -- Connection Pool Events +The {+driver-short+} organizes the events it defines into three categories: -The following sections show how to monitor each event category. +- Command events +- Server Discovery and Monitoring events +- Connection Pool events -For a full list of the events you can monitor, -`see the event package of the MongoDB Kotlin driver <{+api+}/apidocs/mongodb-driver-core/com/mongodb/event/package-summary.html>`__. +The following sections show how to monitor each event category. For a full list of the events you can monitor, +`see the event package of the {+driver-short+} <{+api+}/com/mongodb/event/package-summary.html>`__. .. _command-events-kotlin: From 25df8ed615baad82cd558b591c0571b3d17d585a Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Wed, 29 Jan 2025 15:28:09 -0500 Subject: [PATCH 06/14] NR feedback 2 --- source/monitoring.txt | 130 ++++++++++++++++++++++++------------------ 1 file changed, 74 insertions(+), 56 deletions(-) diff --git a/source/monitoring.txt b/source/monitoring.txt index 46533789..a8adc355 100644 --- a/source/monitoring.txt +++ b/source/monitoring.txt @@ -67,7 +67,7 @@ A command event is an event related to a MongoDB database command. Some examples of database commands that produce command events are ``find``, ``insert``, ``delete``, and ``count``. -To monitor command events, write a class that implements the +To monitor command events, create a class that implements the ``CommandListener`` interface and register an instance of that class with your ``MongoClient`` instance. @@ -78,8 +78,8 @@ For more information on MongoDB database commands, see the The driver does not publish events for commands it calls internally. This includes database commands the driver uses to monitor your cluster and - commands related to connection establishment (such as the initial ``hello`` - command). + commands related to connection establishment, such as the initial ``hello`` + command. .. important:: Redacted Output @@ -93,19 +93,15 @@ Example This example shows how to make a counter for database commands. The counter keeps track of the number of times the driver successfully executes each database -command, and prints this information every time a database command finishes. +command and prints this information every time a database command finishes. -To make a counter, do the following: +To make a counter, follow these steps: #. Make a class with counter functionality that implements the ``CommandListener`` interface. -#. Add an instance of the new class that implements ``CommandListener`` to a ``MongoClientSettings`` object. -#. Configure a ``MongoClient`` instance with the ``MongoClientSettings`` object. +#. Add an instance of the new class to a ``MongoClientSettings`` object. +#. Configure you ``MongoClient`` instance with the ``MongoClientSettings`` object. -The following code defines the ``CommandCounter`` class which implements the -``CommandListener`` interface, then adds an instance of the ``CommandCounter`` class to a -``MongoClientSettings`` object. Then it configures a ``MongoClient`` instance with the -``MongoClientSettings`` object. The code then runs some database commands to test the -counter: +The following code implements these steps: .. _listener-mongo-client-settings-example: @@ -116,20 +112,21 @@ counter: .. output:: :language: console + :visible: false {find=1} {find=2} {find=2, endSessions=1} For more information on the classes and methods mentioned in this section, see -the following API Documentation: +the following API documentation: -- `CommandListener <{+api+}/apidocs/mongodb-driver-core/com/mongodb/event/CommandListener.html>`__ -- `MongoClientSettings <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html>`__ +- `CommandListener <{+api+}/com/mongodb/event/CommandListener.html>`__ +- `MongoClientSettings <{+api+}/com/mongodb/MongoClientSettings.html>`__ - `MongoClient <{+api+}/apidocs/mongodb-driver-kotlin-sync/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-client/index.html>`__ -- `CommandStartedEvent <{+api+}/apidocs/mongodb-driver-core/com/mongodb/event/CommandStartedEvent.html>`__ -- `CommandSucceededEvent <{+api+}/apidocs/mongodb-driver-core/com/mongodb/event/CommandSucceededEvent.html>`__ -- `CommandFailedEvent <{+api+}/apidocs/mongodb-driver-core/com/mongodb/event/CommandFailedEvent.html>`__ +- `CommandStartedEvent <{+api+}/com/mongodb/event/CommandStartedEvent.html>`__ +- `CommandSucceededEvent <{+api+}/com/mongodb/event/CommandSucceededEvent.html>`__ +- `CommandFailedEvent <{+api+}/com/mongodb/event/CommandFailedEvent.html>`__ Server Discovery and Monitoring Events ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -137,17 +134,16 @@ Server Discovery and Monitoring Events A server discovery and monitoring (SDAM) event is an event related to a change in the state of the MongoDB instance or cluster you have connected the driver to. -The driver defines nine SDAM events. The driver divides these nine events -between three separate listener interfaces which each listen for three of the -nine events. Here are the three interfaces and the events they listen for: +The driver defines nine SDAM events and provides the following listener +interfaces, which listen for three SDAM events each: - ``ClusterListener``: topology-related events - ``ServerListener``: events related to ``mongod`` or ``mongos`` processes - ``ServerMonitorListener``: heartbeat related events -To monitor a type of SDAM event, write a class that -implements one of the three preceding interfaces and register an instance of that -class with your ``MongoClient`` instance. +To monitor a type of SDAM event, create a class that implements one of the three +preceding interfaces and register an instance of that class with your +``MongoClient`` instance. For a detailed description of each SDAM event, see the :spec:`MongoDB SDAM monitoring events specification `. @@ -157,10 +153,14 @@ Example This example shows how to make a listener class that prints a message that lets you know if the driver can write to your MongoDB instance. -The following code defines the ``IsWritable`` class which implements the -``ClusterListener`` interface. Then it adds an instance of the ``IsWritable`` class to a -``MongoClient`` object. The code then runs a find operation to test the -``IsWritable`` class: +To make an event that reports write status: + +#. Make a class that tracks and checks cluster description changes, and + implements the ``CommandListener`` interface. +#. Add an instance of the new class to a ``MongoClientSettings`` object. +#. Configure your ``MongoClient`` instance with the ``MongoClientSettings`` object. + +The following code implements these steps: .. io-code-block:: @@ -169,18 +169,19 @@ The following code defines the ``IsWritable`` class which implements the .. output:: :language: console + :visible: false Able to write to server For more information on the classes and methods mentioned in this section, see -the following API Documentation: +the following API documentation: -- `ClusterListener <{+api+}/apidocs/mongodb-driver-core/com/mongodb/event/ClusterListener.html>`__ -- `ServerListener <{+api+}/apidocs/mongodb-driver-core/com/mongodb/event/ServerListener.html>`__ -- `ServerMonitorListener <{+api+}/apidocs/mongodb-driver-core/com/mongodb/event/ServerMonitorListener.html>`__ -- `MongoClientSettings <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html>`__ +- `ClusterListener <{+core-api+}/com/mongodb/event/ClusterListener.html>`__ +- `ServerListener <{+api+}/com/mongodb/event/ServerListener.html>`__ +- `ServerMonitorListener <{+api+}/com/mongodb/event/ServerMonitorListener.html>`__ +- `MongoClientSettings <{+api+}/com/mongodb/MongoClientSettings.html>`__ - `MongoClient <{+api+}/apidocs/mongodb-driver-kotlin-sync/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-client/index.html>`__ -- `ClusterDescriptionChangedEvent <{+api+}/apidocs/mongodb-driver-core/com/mongodb/event/ClusterDescriptionChangedEvent.html>`__ +- `ClusterDescriptionChangedEvent <{+api+}/com/mongodb/event/ClusterDescriptionChangedEvent.html>`__ Connection Pool Events ~~~~~~~~~~~~~~~~~~~~~~ @@ -188,10 +189,10 @@ Connection Pool Events A connection pool event is an event related to a **connection pool** held by the driver. A connection pool is a set of open TCP connections your driver maintains with a MongoDB instance. Connection pools help reduce the number of network handshakes -your application performs with a MongoDB instance, and can help your +your application performs with a MongoDB instance and can help your application run faster. -To monitor connection pool events, write a class that implements the +To monitor connection pool events, create a class that implements the ``ConnectionPoolListener`` interface and register an instance of that class with your ``MongoClient`` instance. @@ -201,10 +202,13 @@ Example This example shows how to make a listener class that prints a message each time you check out a connection from your connection pool. -The following code defines the ``ConnectionPoolLibrarian`` class which implements the -``ConnectionPoolListener`` interface. Then it adds an instance of the -``ConnectionPoolLibrarian`` class to a ``MongoClient`` object. The code then -runs a database command to test the librarian. +To make an event that reports connection checkouts: + +#. Make a class that tracks checkouts and implements the ``CommandListener`` interface. +#. Add an instance of the new class to a ``MongoClientSettings`` object. +#. Configure your ``MongoClient`` instance with the ``MongoClientSettings`` object. + +The following code implements these steps: .. io-code-block:: @@ -213,17 +217,18 @@ runs a database command to test the librarian. .. output:: :language: console + :visible: false Let me get you the connection with id 21... For more information on the classes and methods mentioned in this section, see -the following API Documentation: +the following API documentation: -- `ConnectionPoolListener <{+api+}/apidocs/mongodb-driver-core/com/mongodb/event/ConnectionPoolListener.html>`__ -- `MongoClientSettings <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html>`__ +- `ConnectionPoolListener <{+api+}/com/mongodb/event/ConnectionPoolListener.html>`__ +- `MongoClientSettings <{+api+}/com/mongodb/MongoClientSettings.html>`__ - `MongoClient <{+api+}/apidocs/mongodb-driver-kotlin-sync/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-client/index.html>`__ -- `ConnectionCheckedOutEvent <{+api+}/apidocs/mongodb-driver-core/com/mongodb/event/ConnectionCheckedOutEvent.html>`__ -- `ConnectionCheckOutFailedEvent <{+api+}/apidocs/mongodb-driver-core/com/mongodb/event/ConnectionCheckOutFailedEvent.html>`__ +- `ConnectionCheckedOutEvent <{+api+}/com/mongodb/event/ConnectionCheckedOutEvent.html>`__ +- `ConnectionCheckOutFailedEvent <{+api+}/com/mongodb/event/ConnectionCheckOutFailedEvent.html>`__ .. _monitoring-jmx: @@ -301,10 +306,10 @@ the Java Platform. .. tip:: Consult the Official JMX and JConsole Documentation The descriptions of JMX and JConsole in this example are illustrative - rather than a source of truth. For guaranteed up to date information, consult + rather than a source of truth. For guaranteed up-to-date information, consult the following official Oracle resources: - - `JConsole documentation `__. + - `JConsole documentation `__ - `JMX documentation `__ The following code snippet adds a ``JMXConnectionPoolListener`` to a @@ -318,6 +323,7 @@ navigate to JConsole and inspect your connection pools. .. output:: :language: console + :visible: false Navigate to JConsole to see your connection pools... @@ -338,18 +344,18 @@ Once JConsole is open, perform the following actions in the GUI: When you no longer want to inspect your connection pools in JConsole, do the following: -- Exit JConsole by closing the JConsole window -- Stop the program running the preceding code snippet +#. Exit JConsole by closing the JConsole window +#. Stop the program running by the preceding code snippet For more information on JMX and JConsole, see the following resources from Oracle: -- `JConsole Documentation `__. +- `JConsole Documentation `__ - `Monitoring and Management Guide `__ For more information on the ``JMXConnectionPoolListener`` class, see -the API Documentation for -`JMXConnectionPoolListener <{+api+}/apidocs/mongodb-driver-core/com/mongodb/management/JMXConnectionPoolListener.html>`__. +the API documentation for +`JMXConnectionPoolListener <{+core-api+}/com/mongodb/management/JMXConnectionPoolListener.html>`__. Include the Driver in Your Distributed Tracing System ----------------------------------------------------- @@ -367,11 +373,10 @@ include MongoDB event data in the If you do not use Spring Cloud or want to include driver event data in a distributed tracing system other than Zipkin, you must write a command event listener that -manages `spans `__ +manages `spans +`__ for your desired distributed tracing system. To see an implementation of such a -listener, see the Java source code for the -:github:`TraceMongoCommandListener -` +listener, see the Java source code for the :github:`TraceMongoCommandListener ` class in the Spring Cloud Sleuth source code. To learn more about Spring Cloud Sleuth, see @@ -380,3 +385,16 @@ in the Spring Cloud Sleuth documentation. To view a detailed description of a distributed tracing system, see `Dapper `__ from Google Research. + +.. tip:: + + To learn more about the concepts discussed in this section, review the + following resources: + + - `Spring Cloud `__ + - `Spring Cloud Sleuth `__ + - `spans `__ + - :github:`TraceMongoCommandListener ` + - `Getting Started `__ + - `Zipkin `__ + - `Dapper `__ From 790f5cafd6e9fa90429f9da102ae5d126bdf0cd4 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Wed, 29 Jan 2025 15:51:52 -0500 Subject: [PATCH 07/14] update links --- source/monitoring.txt | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/source/monitoring.txt b/source/monitoring.txt index a8adc355..fd6c7ede 100644 --- a/source/monitoring.txt +++ b/source/monitoring.txt @@ -56,7 +56,8 @@ The {+driver-short+} organizes the events it defines into three categories: - Connection Pool events The following sections show how to monitor each event category. For a full list of the events you can monitor, -`see the event package of the {+driver-short+} <{+api+}/com/mongodb/event/package-summary.html>`__. +`see the event package of the {+driver-short+} +<{+core-api+}/com/mongodb/event/package-summary.html>`__. .. _command-events-kotlin: @@ -121,12 +122,12 @@ The following code implements these steps: For more information on the classes and methods mentioned in this section, see the following API documentation: -- `CommandListener <{+api+}/com/mongodb/event/CommandListener.html>`__ -- `MongoClientSettings <{+api+}/com/mongodb/MongoClientSettings.html>`__ -- `MongoClient <{+api+}/apidocs/mongodb-driver-kotlin-sync/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-client/index.html>`__ -- `CommandStartedEvent <{+api+}/com/mongodb/event/CommandStartedEvent.html>`__ -- `CommandSucceededEvent <{+api+}/com/mongodb/event/CommandSucceededEvent.html>`__ -- `CommandFailedEvent <{+api+}/com/mongodb/event/CommandFailedEvent.html>`__ +- `CommandListener <{+core-api+}/com/mongodb/event/CommandListener.html>`__ +- `MongoClientSettings <{+core-api+}/com/mongodb/MongoClientSettings.html>`__ +- `MongoClient <{+api+}/com.mongodb.kotlin.client/-mongo-client/index.html>`__ +- `CommandStartedEvent <{+core-api+}/com/mongodb/event/CommandStartedEvent.html>`__ +- `CommandSucceededEvent <{+core-api+}/com/mongodb/event/CommandSucceededEvent.html>`__ +- `CommandFailedEvent <{+core-api+}/com/mongodb/event/CommandFailedEvent.html>`__ Server Discovery and Monitoring Events ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -177,11 +178,11 @@ For more information on the classes and methods mentioned in this section, see the following API documentation: - `ClusterListener <{+core-api+}/com/mongodb/event/ClusterListener.html>`__ -- `ServerListener <{+api+}/com/mongodb/event/ServerListener.html>`__ -- `ServerMonitorListener <{+api+}/com/mongodb/event/ServerMonitorListener.html>`__ +- `ServerListener <{+core-api+}/com/mongodb/event/ServerListener.html>`__ +- `ServerMonitorListener <{+core-api+}/com/mongodb/event/ServerMonitorListener.html>`__ - `MongoClientSettings <{+api+}/com/mongodb/MongoClientSettings.html>`__ - `MongoClient <{+api+}/apidocs/mongodb-driver-kotlin-sync/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-client/index.html>`__ -- `ClusterDescriptionChangedEvent <{+api+}/com/mongodb/event/ClusterDescriptionChangedEvent.html>`__ +- `ClusterDescriptionChangedEvent <{+core-api+}/com/mongodb/event/ClusterDescriptionChangedEvent.html>`__ Connection Pool Events ~~~~~~~~~~~~~~~~~~~~~~ @@ -224,11 +225,11 @@ The following code implements these steps: For more information on the classes and methods mentioned in this section, see the following API documentation: -- `ConnectionPoolListener <{+api+}/com/mongodb/event/ConnectionPoolListener.html>`__ +- `ConnectionPoolListener <{+core-api+}/com/mongodb/event/ConnectionPoolListener.html>`__ - `MongoClientSettings <{+api+}/com/mongodb/MongoClientSettings.html>`__ - `MongoClient <{+api+}/apidocs/mongodb-driver-kotlin-sync/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-client/index.html>`__ -- `ConnectionCheckedOutEvent <{+api+}/com/mongodb/event/ConnectionCheckedOutEvent.html>`__ -- `ConnectionCheckOutFailedEvent <{+api+}/com/mongodb/event/ConnectionCheckOutFailedEvent.html>`__ +- `ConnectionCheckedOutEvent <{+core-api+}/com/mongodb/event/ConnectionCheckedOutEvent.html>`__ +- `ConnectionCheckOutFailedEvent <{+core-api+}/com/mongodb/event/ConnectionCheckOutFailedEvent.html>`__ .. _monitoring-jmx: From 19dfc0164461bbc3029b541d4fdd617e0494a55b Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Wed, 29 Jan 2025 16:07:29 -0500 Subject: [PATCH 08/14] final link updates --- source/monitoring.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/source/monitoring.txt b/source/monitoring.txt index fd6c7ede..bc1b7fdc 100644 --- a/source/monitoring.txt +++ b/source/monitoring.txt @@ -56,7 +56,7 @@ The {+driver-short+} organizes the events it defines into three categories: - Connection Pool events The following sections show how to monitor each event category. For a full list of the events you can monitor, -`see the event package of the {+driver-short+} +`see the event package of the {+language+} driver <{+core-api+}/com/mongodb/event/package-summary.html>`__. .. _command-events-kotlin: @@ -180,8 +180,8 @@ the following API documentation: - `ClusterListener <{+core-api+}/com/mongodb/event/ClusterListener.html>`__ - `ServerListener <{+core-api+}/com/mongodb/event/ServerListener.html>`__ - `ServerMonitorListener <{+core-api+}/com/mongodb/event/ServerMonitorListener.html>`__ -- `MongoClientSettings <{+api+}/com/mongodb/MongoClientSettings.html>`__ -- `MongoClient <{+api+}/apidocs/mongodb-driver-kotlin-sync/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-client/index.html>`__ +- `MongoClientSettings <{+core-api+}/com/mongodb/MongoClientSettings.html>`__ +- `MongoClient <{+api+}/com.mongodb.kotlin.client/-mongo-client/index.html>`__ - `ClusterDescriptionChangedEvent <{+core-api+}/com/mongodb/event/ClusterDescriptionChangedEvent.html>`__ Connection Pool Events @@ -226,8 +226,8 @@ For more information on the classes and methods mentioned in this section, see the following API documentation: - `ConnectionPoolListener <{+core-api+}/com/mongodb/event/ConnectionPoolListener.html>`__ -- `MongoClientSettings <{+api+}/com/mongodb/MongoClientSettings.html>`__ -- `MongoClient <{+api+}/apidocs/mongodb-driver-kotlin-sync/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-client/index.html>`__ +- `MongoClientSettings <{+core-api+}/com/mongodb/MongoClientSettings.html>`__ +- `MongoClient <{+api+}/com.mongodb.kotlin.client/-mongo-client/index.html>`__ - `ConnectionCheckedOutEvent <{+core-api+}/com/mongodb/event/ConnectionCheckedOutEvent.html>`__ - `ConnectionCheckOutFailedEvent <{+core-api+}/com/mongodb/event/ConnectionCheckOutFailedEvent.html>`__ From d2b111cd4e7ff4692b235f2eafba1df6c4e57be7 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Thu, 30 Jan 2025 09:21:17 -0500 Subject: [PATCH 09/14] NR feedback --- source/monitoring.txt | 60 ++++++++++++++++++------------------------- 1 file changed, 25 insertions(+), 35 deletions(-) diff --git a/source/monitoring.txt b/source/monitoring.txt index bc1b7fdc..669dde30 100644 --- a/source/monitoring.txt +++ b/source/monitoring.txt @@ -18,11 +18,11 @@ Monitoring is the process of getting information about the activities a running program performs for use in an application or an application performance management library. -Monitoring the {+driver-short+} to monitor cluster, driver command, and +You can use the {+driver-short+} to monitor cluster, driver command, and connection pool events. These features help you make informed decisions when designing and debugging your application. -In this guide you will learn how to perform these tasks: +This guide shows how to perform the following tasks: - :ref:`Monitor specific events by using the {+driver-short+} ` - :ref:`Monitor connection pool events with Java Management Extensions (JMX) and JConsole ` @@ -56,7 +56,7 @@ The {+driver-short+} organizes the events it defines into three categories: - Connection Pool events The following sections show how to monitor each event category. For a full list of the events you can monitor, -`see the event package of the {+language+} driver +`see the Java event package <{+core-api+}/com/mongodb/event/package-summary.html>`__. .. _command-events-kotlin: @@ -72,8 +72,9 @@ To monitor command events, create a class that implements the ``CommandListener`` interface and register an instance of that class with your ``MongoClient`` instance. -For more information on MongoDB database commands, see the -:manual:`MongoDB manual entry on database commands `. +For more information on MongoDB database commands, see the +:manual:`MongoDB manual entry on database commands `in +the {+mdb-server+} manual. .. note:: Internal Commands @@ -100,7 +101,7 @@ To make a counter, follow these steps: #. Make a class with counter functionality that implements the ``CommandListener`` interface. #. Add an instance of the new class to a ``MongoClientSettings`` object. -#. Configure you ``MongoClient`` instance with the ``MongoClientSettings`` object. +#. Configure your ``MongoClient`` instance with the ``MongoClientSettings`` object. The following code implements these steps: @@ -138,9 +139,9 @@ in the state of the MongoDB instance or cluster you have connected the driver to The driver defines nine SDAM events and provides the following listener interfaces, which listen for three SDAM events each: -- ``ClusterListener``: topology-related events -- ``ServerListener``: events related to ``mongod`` or ``mongos`` processes -- ``ServerMonitorListener``: heartbeat related events +- ``ClusterListener``: Listens for topology-related events +- ``ServerListener``: Listens for events related to ``mongod`` or ``mongos`` processes +- ``ServerMonitorListener``: Listens for heartbeat-related events To monitor a type of SDAM event, create a class that implements one of the three preceding interfaces and register an instance of that class with your @@ -151,12 +152,12 @@ For a detailed description of each SDAM event, see the :spec:`MongoDB SDAM monit Example ^^^^^^^ -This example shows how to make a listener class that prints a message that lets -you know if the driver can write to your MongoDB instance. +This example shows how to make a listener class that prints a message about the write +availability of your MongoDB instance. -To make an event that reports write status: +To make an event that reports write status, perform the following tasks: -#. Make a class that tracks and checks cluster description changes, and +#. Make a class that tracks cluster description changes, and implements the ``CommandListener`` interface. #. Add an instance of the new class to a ``MongoClientSettings`` object. #. Configure your ``MongoClient`` instance with the ``MongoClientSettings`` object. @@ -203,7 +204,7 @@ Example This example shows how to make a listener class that prints a message each time you check out a connection from your connection pool. -To make an event that reports connection checkouts: +To make an event that reports connection checkouts, perform the following tasks: #. Make a class that tracks checkouts and implements the ``CommandListener`` interface. #. Add an instance of the new class to a ``MongoClientSettings`` object. @@ -328,7 +329,7 @@ navigate to JConsole and inspect your connection pools. Navigate to JConsole to see your connection pools... -Once you have started your server, open JConsole in your terminal using the +Once you have started your server, open JConsole in your terminal by using the following command: .. code-block:: shell @@ -345,8 +346,8 @@ Once JConsole is open, perform the following actions in the GUI: When you no longer want to inspect your connection pools in JConsole, do the following: -#. Exit JConsole by closing the JConsole window -#. Stop the program running by the preceding code snippet +#. Exit JConsole by closing the JConsole window. +#. Stop the program running by the preceding code snippet. For more information on JMX and JConsole, see the following resources from Oracle: @@ -367,25 +368,12 @@ tracks requests as they propagate throughout different services in a service-oriented architecture. If you use the driver in a `Spring Cloud `__ -application, use -`Spring Cloud Sleuth `__ to -include MongoDB event data in the -`Zipkin `__ distributed tracing system. +application, use to include MongoDB event data in the `Zipkin +`__ distributed tracing system. If you do not use Spring Cloud or want to include driver event data in a distributed tracing system other than Zipkin, you must write a command event listener that -manages `spans -`__ -for your desired distributed tracing system. To see an implementation of such a -listener, see the Java source code for the :github:`TraceMongoCommandListener ` -class in the Spring Cloud Sleuth source code. - -To learn more about Spring Cloud Sleuth, see -`Getting Started `__ -in the Spring Cloud Sleuth documentation. - -To view a detailed description of a distributed tracing system, see -`Dapper `__ from Google Research. +manages **spans** for your desired distributed tracing system. .. tip:: @@ -395,7 +383,9 @@ To view a detailed description of a distributed tracing system, see - `Spring Cloud `__ - `Spring Cloud Sleuth `__ - `spans `__ - - :github:`TraceMongoCommandListener ` + - :github:`TraceMongoCommandListener ` : An + implementation of an event listen than manages spans - `Getting Started `__ - `Zipkin `__ - - `Dapper `__ + - `Dapper `__ : A detailed + description of a distributed tracing system from Google Research From e473cf48e06bbad9f3660d1b43502daecc611b26 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Thu, 30 Jan 2025 09:27:53 -0500 Subject: [PATCH 10/14] bullet formatting --- source/monitoring.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/monitoring.txt b/source/monitoring.txt index 669dde30..453fe3dd 100644 --- a/source/monitoring.txt +++ b/source/monitoring.txt @@ -383,8 +383,8 @@ manages **spans** for your desired distributed tracing system. - `Spring Cloud `__ - `Spring Cloud Sleuth `__ - `spans `__ - - :github:`TraceMongoCommandListener ` : An - implementation of an event listen than manages spans + - :github:`TraceMongoCommandListener ` + : An implementation of an event listen than manages spans - `Getting Started `__ - `Zipkin `__ - `Dapper `__ : A detailed From 89120dfcf1b5a5c80c66110b2033d8f5e6735f48 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Fri, 31 Jan 2025 13:40:26 -0500 Subject: [PATCH 11/14] NH feedback --- source/includes/monitoring_JMX.kt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/includes/monitoring_JMX.kt b/source/includes/monitoring_JMX.kt index c5839a72..3f1eaecb 100644 --- a/source/includes/monitoring_JMX.kt +++ b/source/includes/monitoring_JMX.kt @@ -1,11 +1,8 @@ import com.mongodb.kotlin.client.MongoClient -import org.bson.json.JsonWriterSettings -import com.mongodb.event.* import com.mongodb.MongoClientSettings import com.mongodb.ConnectionString import com.mongodb.management.JMXConnectionPoolListener - fun main() { val uri = "" @@ -15,8 +12,11 @@ fun main() { // Include the listener in your client settings val settings = MongoClientSettings.builder() .applyConnectionString(ConnectionString(uri)) - .addCommandListener(connectionPoolListener) + .applyToConnectionPoolSettings { + it.addConnectionPoolListener(connectionPoolListener) + } .build() + val mongoClient: MongoClient = MongoClient.create(settings) // Pause execution try { From 7189dffd303d724bced7fd0fe00050894f53722d Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Mon, 3 Feb 2025 10:50:49 -0500 Subject: [PATCH 12/14] NH feedback --- source/includes/monitoring_JMX.kt | 14 ++++++++++---- source/includes/monitoring_counter.kt | 2 +- source/includes/monitoring_librarian.kt | 6 ++++-- source/includes/monitoring_writable.kt | 2 +- 4 files changed, 16 insertions(+), 8 deletions(-) diff --git a/source/includes/monitoring_JMX.kt b/source/includes/monitoring_JMX.kt index 3f1eaecb..d3c3877f 100644 --- a/source/includes/monitoring_JMX.kt +++ b/source/includes/monitoring_JMX.kt @@ -1,4 +1,5 @@ import com.mongodb.kotlin.client.MongoClient +import org.bson.Document import com.mongodb.MongoClientSettings import com.mongodb.ConnectionString import com.mongodb.management.JMXConnectionPoolListener @@ -16,15 +17,20 @@ fun main() { it.addConnectionPoolListener(connectionPoolListener) } .build() - val mongoClient: MongoClient = MongoClient.create(settings) -// Pause execution try { +// Connect to your database + val mongoClient = MongoClient.create(settings) + val database = mongoClient.getDatabase("sample_mflix") + val collection = database.getCollection("movies") + collection.find().firstOrNull() + collection.find().firstOrNull() println("Navigate to JConsole to see your connection pools...") + +// Pause execution Thread.sleep(Long.MAX_VALUE) + mongoClient.close() } catch (e: Exception) { e.printStackTrace() } - - mongoClient.close() } \ No newline at end of file diff --git a/source/includes/monitoring_counter.kt b/source/includes/monitoring_counter.kt index 69412879..254b7cdc 100644 --- a/source/includes/monitoring_counter.kt +++ b/source/includes/monitoring_counter.kt @@ -1,5 +1,5 @@ import com.mongodb.kotlin.client.MongoClient -import org.bson.json.JsonWriterSettings +import org.bson.Document import com.mongodb.event.* import com.mongodb.MongoClientSettings import com.mongodb.ConnectionString diff --git a/source/includes/monitoring_librarian.kt b/source/includes/monitoring_librarian.kt index 4ed5f805..dd2abed2 100644 --- a/source/includes/monitoring_librarian.kt +++ b/source/includes/monitoring_librarian.kt @@ -1,5 +1,5 @@ import com.mongodb.kotlin.client.MongoClient -import org.bson.json.JsonWriterSettings +import org.bson.Document import com.mongodb.event.* import com.mongodb.MongoClientSettings import com.mongodb.ConnectionString @@ -23,7 +23,9 @@ val cpListener = ConnectionPoolLibrarian() // Include the listener in your client settings val settings = MongoClientSettings.builder() .applyConnectionString(ConnectionString(uri)) - .addCommandListener(cpListener) + .applyToConnectionPoolSettings({ + it.addConnectionPoolListener(cpListener) + }) .build() // Connect to your database diff --git a/source/includes/monitoring_writable.kt b/source/includes/monitoring_writable.kt index df1e4e78..6d81036f 100644 --- a/source/includes/monitoring_writable.kt +++ b/source/includes/monitoring_writable.kt @@ -1,5 +1,5 @@ import com.mongodb.kotlin.client.MongoClient -import org.bson.json.JsonWriterSettings +import org.bson.Document import com.mongodb.event.* import com.mongodb.MongoClientSettings import com.mongodb.ConnectionString From c74ddce28576da4b0802f721130d6a4409c94ea5 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Wed, 5 Feb 2025 08:55:48 -0500 Subject: [PATCH 13/14] NH feedback --- source/monitoring.txt | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/source/monitoring.txt b/source/monitoring.txt index 453fe3dd..2ae6bec2 100644 --- a/source/monitoring.txt +++ b/source/monitoring.txt @@ -139,9 +139,9 @@ in the state of the MongoDB instance or cluster you have connected the driver to The driver defines nine SDAM events and provides the following listener interfaces, which listen for three SDAM events each: -- ``ClusterListener``: Listens for topology-related events -- ``ServerListener``: Listens for events related to ``mongod`` or ``mongos`` processes -- ``ServerMonitorListener``: Listens for heartbeat-related events +- ` ``ClusterListener`` <{+core-api+}/com/mongodb/event/ClusterListener.html>`__ : Listens for topology-related events +- ` ``ServerListener`` <{+core-api+}/com/mongodb/event/ServerListener.html>`__ : Listens for events related to ``mongod`` or ``mongos`` processes +- ` ``ServerMonitorListener`` <{+core-api+}/com/mongodb/event/ServerMonitorListener.html>`__ : Listens for heartbeat-related events To monitor a type of SDAM event, create a class that implements one of the three preceding interfaces and register an instance of that class with your @@ -158,7 +158,7 @@ availability of your MongoDB instance. To make an event that reports write status, perform the following tasks: #. Make a class that tracks cluster description changes, and - implements the ``CommandListener`` interface. + implements the ``ClusterListener`` interface. #. Add an instance of the new class to a ``MongoClientSettings`` object. #. Configure your ``MongoClient`` instance with the ``MongoClientSettings`` object. @@ -368,8 +368,8 @@ tracks requests as they propagate throughout different services in a service-oriented architecture. If you use the driver in a `Spring Cloud `__ -application, use to include MongoDB event data in the `Zipkin -`__ distributed tracing system. +application, use Spring Cloud Sleuth to include MongoDB event data in the +`Zipkin `__ distributed tracing system. If you do not use Spring Cloud or want to include driver event data in a distributed tracing system other than Zipkin, you must write a command event listener that From 7b12d2065b654d9bfcfd43b6daa3687c16d634f2 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Wed, 5 Feb 2025 09:01:06 -0500 Subject: [PATCH 14/14] NH feedback --- source/monitoring.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/monitoring.txt b/source/monitoring.txt index 2ae6bec2..403f3e0a 100644 --- a/source/monitoring.txt +++ b/source/monitoring.txt @@ -139,9 +139,9 @@ in the state of the MongoDB instance or cluster you have connected the driver to The driver defines nine SDAM events and provides the following listener interfaces, which listen for three SDAM events each: -- ` ``ClusterListener`` <{+core-api+}/com/mongodb/event/ClusterListener.html>`__ : Listens for topology-related events -- ` ``ServerListener`` <{+core-api+}/com/mongodb/event/ServerListener.html>`__ : Listens for events related to ``mongod`` or ``mongos`` processes -- ` ``ServerMonitorListener`` <{+core-api+}/com/mongodb/event/ServerMonitorListener.html>`__ : Listens for heartbeat-related events +- `ClusterListener <{+core-api+}/com/mongodb/event/ClusterListener.html>`__ : Listens for topology-related events +- `ServerListener <{+core-api+}/com/mongodb/event/ServerListener.html>`__ : Listens for events related to ``mongod`` or ``mongos`` processes +- `ServerMonitorListener <{+core-api+}/com/mongodb/event/ServerMonitorListener.html>`__ : Listens for heartbeat-related events To monitor a type of SDAM event, create a class that implements one of the three preceding interfaces and register an instance of that class with your