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 754c8f004..cf958eb19 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. +{+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 ` -- :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 `. +To learn how to record events in the driver, see the {+driver-short+}'s +:ref:`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 `. +To learn more about MongoDB database commands, see the +:manual:`Database Commands ` 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 `. + :spec:`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 ` 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 `. +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. 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 the + :spec:`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 ` 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 `__. +To learn more information about JMX, see the official +`Oracle JMX documentation `__. 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 `__ -- `MXBean Documentation `__ -- `MBean Documentation `__ +- `Platform MBean Server Reference documentation `__ +- `MXBean documentation `__ +- `MBean documentation `__ 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 `__. + - `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. +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 `__. +- `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 +422,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