DOCSP-47042 Monitoring

Author: lindseymoore

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 <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>`.
+see the {+driver-short+}'s :ref:`Logging <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 </reference/command/>`.
+To learn more about MongoDB database commands, see the
+:manual:`MongoDB manual entry on database commands </reference/command/>` 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 </command-logging-and-monitoring/command-logging-and-monitoring.rst#security>`.
 
+.. ^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 </server-discovery-and-monitoring/server-discovery-and-monitoring.md#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 </server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.md#events-api>`.
+:spec:`MongoDB SDAM Logging and Monitoring Specification 
+</server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.md#events-api>`.
 
 .. 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 
+   :spec:`MongoDB Load Balancer Support Specification </load-balancers/load-balancers.md#server-discovery-logging-and-monitoring>`.
 
 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 <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 <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,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 <https://docs.oracle.com/en/java/javase/16/management/overview-java-se-monitoring-and-management.html#GUID-F7B9AB8A-F5A8-472A-AEC6-93B5B7FBE7CE>`__
@@ -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 <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 +426,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