From 5fa7e284757a79876f0e9522d67ed3361cfe8f18 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 26 Feb 2025 16:36:16 -0500 Subject: [PATCH 1/6] DOCSP-47042 Monitoring --- source/logging-monitoring/monitoring.txt | 94 +++++++++++++----------- 1 file changed, 51 insertions(+), 43 deletions(-) diff --git a/source/logging-monitoring/monitoring.txt b/source/logging-monitoring/monitoring.txt index 754c8f004..beb6560ef 100644 --- a/source/logging-monitoring/monitoring.txt +++ b/source/logging-monitoring/monitoring.txt @@ -2,8 +2,6 @@ Monitoring ========== - - .. contents:: On this page :local: :backlinks: none @@ -13,31 +11,26 @@ Monitoring Overview -------- -.. What is on this page? - In this guide, you can learn how to set up and configure **monitoring** in the -MongoDB Java driver. - -.. What do any new terms mean? +{+driver-long+}. -Monitoring is the process of getting information about the activities a running -program performs for use in an application or an application performance +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 Java driver lets you understand the -driver's resource usage and performance, and can help you make informed +Monitoring your application lets you understand the driver's resource usage +and performance and can help you make informed decisions when designing and debugging your application. -.. What can you expect to see on this page? - In this guide you will learn how to perform these tasks: -- :ref:`Monitor different types of events in the MongoDB Java Driver ` -- :ref:`Monitor connection pool events with Java Management Extensions (JMX) and JConsole ` +- :ref:`Monitor Events ` +- :ref:`Monitor Connection Pool Events with Java Management Extensions (JMX) + and JConsole ` This guide shows how to use information about the activity of the driver in code. If you would like to learn how to record events in the driver, -consider reading our :doc:`guide on logging `. +see the {+driver-short+}'s :ref:`Logging ` guide. .. _monitoring-monitor-events: @@ -65,8 +58,10 @@ The MongoDB Java driver organizes the events it defines into three categories: 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 Java Driver <{+api+}/apidocs/mongodb-driver-core/com/mongodb/event/package-summary.html>`__. +To learn more about the events you can monitor, `see the event package of the +MongoDB Java Driver <{+api+}/apidocs/mongodb-driver-core/com/mongodb/event/package-summary.html>`__. + +.. fix this link text^ .. _command-events-java: @@ -81,13 +76,16 @@ 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 about MongoDB database commands, see the -:manual:`MongoDB manual entry on database commands `. +To learn more about MongoDB database commands, see the +:manual:`MongoDB manual entry on database commands ` in the +Server (or MongoDB?) Manual. + +.. fix this link ^ .. 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 + The {+driver-short+} 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). @@ -98,6 +96,8 @@ For more information about MongoDB database commands, see the full list of redacted command events, see the :spec:`MongoDB command logging and monitoring specification `. +.. ^fix this link + Example ^^^^^^^ @@ -109,7 +109,7 @@ 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. +#. Configure a ``MongoClient`` instance by using the ``MongoClientSettings`` object. The following code defines the ``CommandCounter`` class which implements the ``CommandListener`` interface: @@ -121,8 +121,8 @@ The following code defines the ``CommandCounter`` class which implements the :end-before: end command-listener-impl The following code adds an instance of the ``CommandCounter`` class to a -``MongoClientSettings`` object, and configures a ``MongoClient`` instance with the -``MongoClientSettings`` object. The code then runs some database commands to test the +``MongoClientSettings`` object, and configures a ``MongoClient`` instance by using the +``MongoClientSettings`` object. The code then runs sample ``find()`` commands to test the counter. .. _listener-mongo-client-settings-example: @@ -142,7 +142,7 @@ The preceding code snippet produces output that resembles the following: {find=2} {find=2, endSessions=1} -For more information about the classes and methods mentioned in this section, see +To learn more about the classes and methods mentioned in this section, see the following API Documentation: - `CommandListener <{+api+}/apidocs/mongodb-driver-core/com/mongodb/event/CommandListener.html>`__ @@ -159,8 +159,8 @@ 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: +between three separate listener interfaces. The following are the three interfaces +and the events they listen for: - ``ClusterListener``: :spec:`topology ` related events @@ -172,11 +172,14 @@ implements one of the three preceding interfaces and register an instance of tha class with your ``MongoClient`` instance. For a detailed description of each SDAM event in the driver, see the -:spec:`MongoDB SDAM Logging and Monitoring Specification `. +:spec:`MongoDB SDAM Logging and Monitoring Specification +`. .. note:: Load Balanced Mode - The driver doesn't emit heartbeat related events when in load balanced mode. For more details about SDAM events with load balancing, see :spec:`MongoDB Load Balancer Support Specification `. + The driver doesn't emit heartbeat related events when in load balanced mode. + To learn more about SDAM events with load balancing, see + :spec:`MongoDB Load Balancer Support Specification `. Example ^^^^^^^ @@ -203,7 +206,8 @@ The following code adds an instance of the ``IsWritable`` class to a :start-after: start monitor-cluster-example :end-before: end monitor-cluster-example -The preceding code snippet produces output that resembles the following: +The preceding code snippet produces a confirmation message that resembles the +following: .. code-block:: none :copyable: false @@ -226,8 +230,12 @@ 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. +your application needs to perform with a MongoDB instance and can help your +application run faster. + +.. Add when page is ready: To learn more about connection pools, see the {+driver-short+}'s +.. :ref:`Connection Pools ` guide. + To monitor connection pool events, write a class that implements the ``ConnectionPoolListener`` interface and register an instance of that class with your @@ -240,7 +248,7 @@ 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. +``ConnectionPoolListener`` interface: .. literalinclude:: /includes/fundamentals/code-snippets/Monitoring.java :language: java @@ -250,7 +258,7 @@ The following code defines the ``ConnectionPoolLibrarian`` class which implement The following code adds an instance of the ``ConnectionPoolLibrarian`` class to a ``MongoClient`` object. The code then runs a database command to test the -librarian. +librarian: .. literalinclude:: /includes/fundamentals/code-snippets/Monitoring.java :language: java @@ -282,8 +290,8 @@ 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 about JMX, see -`the official Oracle JMX documentation `__. +To learn more information about JMX, see the official +`Oracle JMX documentation `__. JMX Support ~~~~~~~~~~~ @@ -333,7 +341,7 @@ MXBeans registered on the platform MBean server have the following properties: All MXBean instances created by the driver are under the domain ``"org.mongodb.driver"``. -For more information about the topics discussed in this subsection, see the +To learn more about the topics discussed in this subsection, see the following resources from Oracle: - `Platform MBean Server Reference Documentation `__ @@ -358,7 +366,7 @@ the Java Platform. 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. +navigate to JConsole and inspect your connection pools: .. literalinclude:: /includes/fundamentals/code-snippets/JMXMonitoring.java :language: java @@ -393,13 +401,13 @@ following: - Exit JConsole by closing the JConsole window - Stop the Java program running the preceding code snippet -For more information about JMX and JConsole, see the following resources from +To learn more about JMX and JConsole, see the following resources from Oracle: - `JConsole Documentation `__. - `Monitoring and Management Guide `__ -For more information about the ``JMXConnectionPoolListener`` class, see +To learn more about the ``JMXConnectionPoolListener`` class, see the API Documentation for `JMXConnectionPoolListener <{+api+}/apidocs/mongodb-driver-core/com/mongodb/management/JMXConnectionPoolListener.html>`__. @@ -418,8 +426,8 @@ 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 `__ +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 :github:`TraceMongoCommandListener From 4ef4c3326775cb4ca48cc5de297287fb1879f60c Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 26 Feb 2025 16:54:50 -0500 Subject: [PATCH 2/6] code edits --- .../fundamentals/code-snippets/Monitoring.java | 6 +++--- source/logging-monitoring/monitoring.txt | 16 +++++----------- 2 files changed, 8 insertions(+), 14 deletions(-) diff --git a/source/includes/fundamentals/code-snippets/Monitoring.java b/source/includes/fundamentals/code-snippets/Monitoring.java index 46a2c50be..14e2d6d0e 100644 --- a/source/includes/fundamentals/code-snippets/Monitoring.java +++ b/source/includes/fundamentals/code-snippets/Monitoring.java @@ -42,7 +42,7 @@ private void monitorCommandEvent() { MongoClient mongoClient = MongoClients.create(settings); MongoDatabase database = mongoClient.getDatabase(DATABASE); MongoCollection collection = database.getCollection(COLLECTION); - // Run some commands to test the timer + // Runs sample find() commands to test the timer collection.find().first(); collection.find().first(); mongoClient.close(); @@ -61,7 +61,7 @@ private void monitorClusterEvent() { MongoClient mongoClient = MongoClients.create(settings); MongoDatabase database = mongoClient.getDatabase(DATABASE); MongoCollection collection = database.getCollection(COLLECTION); - // Run a command to trigger a ClusterDescriptionChangedEvent event + // Runs a sample find() command to trigger a ClusterDescriptionChangedEvent event collection.find().first(); // end monitor-cluster-example mongoClient.close(); @@ -79,7 +79,7 @@ private void monitorConnectionPoolEvent() { MongoClient mongoClient = MongoClients.create(settings); MongoDatabase database = mongoClient.getDatabase(DATABASE); MongoCollection collection = database.getCollection(COLLECTION); - // Run a command to trigger connection pool events + // Runs a sample find() command to trigger connection pool events collection.find().first(); // end monitor-cp-example /* We do not close this connection in order to prevent the driver from requesting two connections, giving diff --git a/source/logging-monitoring/monitoring.txt b/source/logging-monitoring/monitoring.txt index beb6560ef..530c8c6dc 100644 --- a/source/logging-monitoring/monitoring.txt +++ b/source/logging-monitoring/monitoring.txt @@ -58,10 +58,8 @@ The MongoDB Java driver organizes the events it defines into three categories: The following sections show how to monitor each event category. -To learn more about the events you can monitor, `see the event package of the -MongoDB Java Driver <{+api+}/apidocs/mongodb-driver-core/com/mongodb/event/package-summary.html>`__. - -.. fix this link text^ +To learn more about the events you can monitor, see the API documentation for `event classes +<{+api+}/apidocs/mongodb-driver-core/com/mongodb/event/package-summary.html>`__. .. _command-events-java: @@ -78,9 +76,7 @@ To monitor command events, write a class that implements the To learn more about MongoDB database commands, see the :manual:`MongoDB manual entry on database commands ` in the -Server (or MongoDB?) Manual. - -.. fix this link ^ +Server Manual. .. note:: Internal Commands @@ -94,9 +90,8 @@ Server (or MongoDB?) Manual. 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 `. - -.. ^fix this link + :spec:`MongoDB command logging and monitoring specification ` + in GitHub. Example ^^^^^^^ @@ -236,7 +231,6 @@ application run faster. .. Add when page is ready: To learn more about connection pools, see the {+driver-short+}'s .. :ref:`Connection Pools ` guide. - To monitor connection pool events, write a class that implements the ``ConnectionPoolListener`` interface and register an instance of that class with your ``MongoClient`` instance. From 75b8326ded6d8afab849bff74a3fd1c74226302b Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 26 Feb 2025 17:11:59 -0500 Subject: [PATCH 3/6] more edits --- source/logging-monitoring/monitoring.txt | 28 +++++++++++++----------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/source/logging-monitoring/monitoring.txt b/source/logging-monitoring/monitoring.txt index 530c8c6dc..d3b70c48a 100644 --- a/source/logging-monitoring/monitoring.txt +++ b/source/logging-monitoring/monitoring.txt @@ -75,7 +75,7 @@ To monitor command events, write a class that implements the ``MongoClient`` instance. To learn more about MongoDB database commands, see the -:manual:`MongoDB manual entry on database commands ` in the +:manual:`Database Commands ` guide in the Server Manual. .. note:: Internal Commands @@ -90,8 +90,8 @@ 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. For a full list of redacted command events, see the - :spec:`MongoDB command logging and monitoring specification ` - in GitHub. + :spec:`Security ` + section of the MongoDB Command Logging and Monitoring specification in GitHub. Example ^^^^^^^ @@ -166,15 +166,17 @@ 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 in the driver, see the -:spec:`MongoDB SDAM Logging and Monitoring Specification -`. +For a detailed description of each SDAM event in the driver, see the +:spec:`Server API +` +section of th MongoDB SDAM Logging and Monitoring Specification in GitHub. .. note:: Load Balanced Mode The driver doesn't emit heartbeat related events when in load balanced mode. - To learn more about SDAM events with load balancing, see - :spec:`MongoDB Load Balancer Support Specification `. + To learn more about SDAM events with load balancing, see the + :spec:`Server Discovery Logging and Monitoring ` + section of the MongoDB Load Balancer Support Specification in GitHub. Example ^^^^^^^ @@ -338,9 +340,9 @@ All MXBean instances created by the driver are under the domain To learn more about the topics discussed in this subsection, see the following resources from Oracle: -- `Platform MBean Server Reference Documentation `__ -- `MXBean Documentation `__ -- `MBean Documentation `__ +- `Platform MBean Server Reference documentation `__ +- `MXBean documentation `__ +- `MBean documentation `__ JMX and JConsole Example ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -355,7 +357,7 @@ the Java Platform. 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 @@ -398,7 +400,7 @@ following: To learn more about JMX and JConsole, see the following resources from Oracle: -- `JConsole Documentation `__. +- `JConsole documentation `__. - `Monitoring and Management Guide `__ To learn more about the ``JMXConnectionPoolListener`` class, see From 197ec35e99af25f489fd0b8194b57092dd1cf822 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 26 Feb 2025 17:18:07 -0500 Subject: [PATCH 4/6] edits --- source/logging-monitoring/monitoring.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/logging-monitoring/monitoring.txt b/source/logging-monitoring/monitoring.txt index d3b70c48a..0469f495a 100644 --- a/source/logging-monitoring/monitoring.txt +++ b/source/logging-monitoring/monitoring.txt @@ -29,8 +29,8 @@ In this guide you will learn how to perform these tasks: and JConsole ` This guide shows how to use information about the activity of the driver in code. -If you would like to learn how to record events in the driver, -see the {+driver-short+}'s :ref:`Logging ` guide. +To learn how to record events in the driver, see the {+driver-short+}'s +:ref:`Logging ` guide. .. _monitoring-monitor-events: From fd1eaf73d8609488d33f05f7cd15b43cd1d7f3fc Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Fri, 28 Feb 2025 13:02:43 -0500 Subject: [PATCH 5/6] tech review --- source/logging-monitoring/monitoring.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/logging-monitoring/monitoring.txt b/source/logging-monitoring/monitoring.txt index 0469f495a..c26a2ec86 100644 --- a/source/logging-monitoring/monitoring.txt +++ b/source/logging-monitoring/monitoring.txt @@ -14,11 +14,11 @@ Overview In this guide, you can learn how to set up and configure **monitoring** in the {+driver-long+}. -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 involves collecting information about the activities of a running program, +which you can use in your application or with an application performance management +library. -Monitoring your application lets you understand the driver's resource usage +Monitoring the {+driver-short+} lets you understand the driver's resource usage and performance and can help you make informed decisions when designing and debugging your application. From abf778b7b43a2735479359739e195b1a00a0b5e5 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Fri, 28 Feb 2025 16:34:22 -0500 Subject: [PATCH 6/6] monitoring def edit --- source/logging-monitoring/monitoring.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/logging-monitoring/monitoring.txt b/source/logging-monitoring/monitoring.txt index c26a2ec86..cf958eb19 100644 --- a/source/logging-monitoring/monitoring.txt +++ b/source/logging-monitoring/monitoring.txt @@ -14,9 +14,9 @@ Overview In this guide, you can learn how to set up and configure **monitoring** in the {+driver-long+}. -Monitoring involves collecting information about the activities of a running program, -which you can use in your application or with an application performance management -library. +Monitoring involves collecting information about the activities of a running +program, which you can use with an application performance management +library. Monitoring the {+driver-short+} lets you understand the driver's resource usage and performance and can help you make informed