NR feedback 2

Author: rachel-mack

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,38 +112,38 @@ 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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 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 </server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.md>`.
 
@@ -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,29 +169,30 @@ 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
 ~~~~~~~~~~~~~~~~~~~~~~
 
 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 <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
@@ -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 <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 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 <https://docs.spring.io/spring-cloud-sleuth/docs/current-SNAPSHOT/reference/html/getting-started.html#getting-started-terminology>`__
+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 Java source code for the
-:github:`TraceMongoCommandListener
-<spring-cloud/spring-cloud-sleuth/blob/eb01d5952b2e736970efbe3fc7e9784d119eeae9/spring-cloud-sleuth-instrumentation/src/main/java/org/springframework/cloud/sleuth/instrument/mongodb/TraceMongoCommandListener.java>`
+listener, see the Java source code for the :github:`TraceMongoCommandListener <spring-cloud/spring-cloud-sleuth/blob/eb01d5952b2e736970efbe3fc7e9784d119eeae9/spring-cloud-sleuth-instrumentation/src/main/java/org/springframework/cloud/sleuth/instrument/mongodb/TraceMongoCommandListener.java>`
 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 <https://research.google/pubs/pub36356/>`__ from Google Research.
+
+.. tip::
+
+   To learn more about the concepts discussed in this section, review the
+   following resources:
+
+   - `Spring Cloud <https://spring.io/projects/spring-cloud>`__
+      - `Spring Cloud Sleuth <https://spring.io/projects/spring-cloud-sleuth>`__
+      - `spans <https://docs.spring.io/spring-cloud-sleuth/docs/current-SNAPSHOT/reference/html/getting-started.html#getting-started-terminology>`__
+      - :github:`TraceMongoCommandListener <spring-cloud/spring-cloud-sleuth/blob/eb01d5952b2e736970efbe3fc7e9784d119eeae9/spring-cloud-sleuth-instrumentation/src/main/java/org/springframework/cloud/sleuth/instrument/mongodb/TraceMongoCommandListener.java>`
+      - `Getting Started <https://docs.spring.io/spring-cloud-sleuth/docs/current-SNAPSHOT/reference/html/getting-started.html>`__
+   - `Zipkin <https://zipkin.io/>`__
+   - `Dapper <https://research.google/pubs/pub36356/>`__