DOCSP-47042 Monitoring Edits (#633)

* DOCSP-47042 Monitoring

* code edits

* more edits

* edits

* tech review

* monitoring def edit

Author: lindseymoore

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<Document> 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<Document> 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<Document> 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

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.
+{+driver-long+}.
 
-.. What do any new terms mean?
+Monitoring involves collecting information about the activities of a running
+program, which you can use with an application performance management
+library.
 
-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 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.
 
-.. 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 <monitoring-monitor-events>`
-- :ref:`Monitor connection pool events with Java Management Extensions (JMX) and JConsole <monitoring-jmx>`
+- :ref:`Monitor Events <monitoring-monitor-events>`
+- :ref:`Monitor Connection Pool Events with Java Management Extensions (JMX) 
+  and JConsole <monitoring-jmx>`
 
 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 </logging>`.
+To learn how to record events in the driver, see the {+driver-short+}'s 
+:ref:`Logging <logging>` guide. 
 
 .. _monitoring-monitor-events:
 
@@ -65,8 +58,8 @@ 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 API documentation for `event classes 
+<{+api+}/apidocs/mongodb-driver-core/com/mongodb/event/package-summary.html>`__.
 
 .. _command-events-java:
 
@@ -81,13 +74,14 @@ 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 </reference/command/>`.
+To learn more about MongoDB database commands, see the
+:manual:`Database Commands </reference/command/>` guide in the
+Server Manual.
 
 .. 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).
 
@@ -96,7 +90,8 @@ For more information about MongoDB database commands, see the
    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 </command-logging-and-monitoring/command-logging-and-monitoring.rst#security>`.
+   :spec:`Security </command-logging-and-monitoring/command-logging-and-monitoring.md#security>`
+   section of the MongoDB Command Logging and Monitoring specification in GitHub.
 
 Example
 ^^^^^^^
@@ -109,7 +104,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 +116,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 +137,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 +154,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 </server-discovery-and-monitoring/server-discovery-and-monitoring.md#topology>`
   related events
@@ -171,12 +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 </server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.md#events-api>`.
+For a detailed description of each SDAM event in the driver, see the 
+:spec:`Server API  
+</server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.md#events-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. For more details about SDAM events with load balancing, see :spec:`MongoDB Load Balancer Support Specification </load-balancers/load-balancers.md#server-discovery-logging-and-monitoring>`.
+   The driver doesn't emit heartbeat related events when in load balanced mode. 
+   To learn more about SDAM events with load balancing, see the 
+   :spec:`Server Discovery Logging and Monitoring </load-balancers/load-balancers.md#server-discovery-logging-and-monitoring>`
+   section of the MongoDB Load Balancer Support Specification in GitHub.
 
 Example
 ^^^^^^^
@@ -203,7 +203,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 +227,11 @@ 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 <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 +244,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 +254,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 +286,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 <https://docs.oracle.com/javase/tutorial/jmx/index.html>`__.
+To learn more information about JMX, see the official 
+`Oracle JMX documentation <https://docs.oracle.com/javase/tutorial/jmx/index.html>`__.
 
 JMX Support
 ~~~~~~~~~~~
@@ -333,12 +337,12 @@ 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 <https://docs.oracle.com/en/java/javase/16/management/overview-java-se-monitoring-and-management.html#GUID-F7B9AB8A-F5A8-472A-AEC6-93B5B7FBE7CE>`__
-- `MXBean Documentation <https://docs.oracle.com/javase/tutorial/jmx/mbeans/mxbeans.html>`__
-- `MBean Documentation <https://docs.oracle.com/javase/tutorial/jmx/mbeans/standard.html>`__
+- `Platform MBean Server Reference documentation <https://docs.oracle.com/en/java/javase/16/management/overview-java-se-monitoring-and-management.html#GUID-F7B9AB8A-F5A8-472A-AEC6-93B5B7FBE7CE>`__
+- `MXBean documentation <https://docs.oracle.com/javase/tutorial/jmx/mbeans/mxbeans.html>`__
+- `MBean documentation <https://docs.oracle.com/javase/tutorial/jmx/mbeans/standard.html>`__
 
 JMX and JConsole Example
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -353,12 +357,12 @@ the Java Platform.
    rather than a source of truth. For guaranteed up to date information, consult
    the following official Oracle resources:
 
-   - `JConsole documentation <https://www.oracle.com/technical-resources/articles/java/jconsole.html>`__.
+   - `JConsole documentation <https://www.oracle.com/technical-resources/articles/java/jconsole.html>`__
    - `JMX documentation <https://docs.oracle.com/javase/tutorial/jmx/index.html>`__
 
 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 +397,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 <https://www.oracle.com/technical-resources/articles/java/jconsole.html>`__.
+- `JConsole documentation <https://www.oracle.com/technical-resources/articles/java/jconsole.html>`__.
 - `Monitoring and Management Guide <https://docs.oracle.com/en/java/javase/16/management/monitoring-and-management-using-jmx-technology.html>`__
 
-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 +422,8 @@ include MongoDB event data in the
 `Zipkin <https://zipkin.io/>`__ 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 <https://docs.spring.io/spring-cloud-sleuth/docs/current-SNAPSHOT/reference/html/getting-started.html#getting-started-terminology>`__
+tracing system other than Zipkin, you must write a command event listener that manages 
+`spans <https://docs.spring.io/spring-cloud-sleuth/docs/current-SNAPSHOT/reference/html/getting-started.html#getting-started-terminology>`__
 for your desired distributed tracing system. To see an implementation of such a
 listener, see the
 :github:`TraceMongoCommandListener