Skip to content

DOCSP-47042 Monitoring Edits #633

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Feb 28, 2025
Merged

DOCSP-47042 Monitoring Edits #633

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
5fa7e28
DOCSP-47042 Monitoring
lindseymoore Feb 26, 2025
4ef4c33
code edits
lindseymoore Feb 26, 2025
75b8326
more edits
lindseymoore Feb 26, 2025
197ec35
edits
lindseymoore Feb 26, 2025
fd1eaf7
tech review
lindseymoore Feb 28, 2025
abf778b
monitoring def edit
lindseymoore Feb 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions source/includes/fundamentals/code-snippets/Monitoring.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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();
Expand All @@ -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();
Expand All @@ -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
Expand Down
106 changes: 55 additions & 51 deletions source/logging-monitoring/monitoring.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,6 @@
Monitoring
==========



.. contents:: On this page
:local:
:backlinks: none
Expand All @@ -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 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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This wording seems awkward. In particular, I am not sure what it means to get "information ... for use in an application".

Possible reword, which may or may not capture the intended meaning:

Monitoring involves collecting information about the activities of a running program, which can be used to support application development or in an application performance management library.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the potential reword! What do you think about this:
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 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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the prior focus on the driver seemed clearer. None of the monitoring discussed is app-level, it is all driver level?


.. 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
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice word reductions, these help clarity 👍

:ref:`Logging <logging>` guide.

.. _monitoring-monitor-events:

Expand Down Expand Up @@ -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:

Expand All @@ -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).

Expand All @@ -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
^^^^^^^
Expand All @@ -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:
Expand All @@ -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:
Expand All @@ -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>`__
Expand All @@ -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
Expand All @@ -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
^^^^^^^
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
~~~~~~~~~~~
Expand Down Expand Up @@ -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
~~~~~~~~~~~~~~~~~~~~~~~~
Expand All @@ -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
Expand Down Expand Up @@ -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>`__.

Expand All @@ -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
Expand Down
Loading