From aa439e59f84955162112f9c32657781df0e30666 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 6 Dec 2024 16:02:23 -0600 Subject: [PATCH 1/6] first draft --- source/fundamentals.txt | 4 +- source/fundamentals/java-monitoring.txt | 434 ++++++++++++++++++++++++ source/fundamentals/monitoring.txt | 115 +++++++ 3 files changed, 552 insertions(+), 1 deletion(-) create mode 100644 source/fundamentals/java-monitoring.txt create mode 100644 source/fundamentals/monitoring.txt diff --git a/source/fundamentals.txt b/source/fundamentals.txt index d785a332..fe326063 100644 --- a/source/fundamentals.txt +++ b/source/fundamentals.txt @@ -32,6 +32,7 @@ Fundamentals Store Large Files Replica Set Operations OData + Monitoring - :ref:`Connecting to MongoDB ` - :ref:`csharp-db-coll` @@ -53,4 +54,5 @@ Fundamentals - :ref:`csharp-geo` - :ref:`csharp-gridfs` - :ref:`csharp-read-write-config` -- :ref:`csharp-odata` \ No newline at end of file +- :ref:`csharp-odata` +- :ref:`csharp-monitoring` \ No newline at end of file diff --git a/source/fundamentals/java-monitoring.txt b/source/fundamentals/java-monitoring.txt new file mode 100644 index 00000000..33d17e71 --- /dev/null +++ b/source/fundamentals/java-monitoring.txt @@ -0,0 +1,434 @@ +========== +Monitoring +========== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +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? + +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 +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 ` + +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 `. + +.. _monitoring-monitor-events: + +Monitor Events +-------------- + +To monitor an **event**, you must register a **listener** on your ``MongoClient`` +instance. + +An event is any action that happens in a running program. The driver includes functionality +for listening to a subset of the events that occur when the driver is running. + +A listener is a class that performs some action when certain events occur. +A listener's API defines the events it can respond to. + +Each method of a listener class represents a response to a certain event. Each +method receives one argument: an object representing the event the method +responds to. + +The MongoDB Java driver organizes the events it defines into three categories: + +- Command Events +- Server Discovery and Monitoring Events +- Connection Pool Events + +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>`__. + +.. _command-events-java: + +Command Events +~~~~~~~~~~~~~~ + +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 +``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 `. + +.. 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 + commands related to connection establishment (such as the initial ``hello`` + command). + +.. important:: Redacted Output + + 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 `. + +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. + +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. + +The following code defines the ``CommandCounter`` class which implements the +``CommandListener`` interface: + +.. literalinclude:: /includes/fundamentals/code-snippets/Monitoring.java + :language: java + :dedent: + :start-after: start command-listener-impl + :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 +counter. + +.. _listener-mongo-client-settings-example: + +.. literalinclude:: /includes/fundamentals/code-snippets/Monitoring.java + :language: java + :dedent: + :start-after: start monitor-command-example + :end-before: end monitor-command-example + +The preceding code snippet produces output that resembles the following: + +.. code-block:: none + :copyable: false + + {find=1} + {find=2} + {find=2, endSessions=1} + +For more information 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>`__ +- `MongoClientSettings <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html>`__ +- `MongoClient <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoClient.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>`__ + +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: + +- ``ClusterListener``: :spec:`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. + +For a detailed description of each SDAM event in the driver, see the +:spec:`MongoDB SDAM Logging and Monitoring Specification `. + +.. 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 `. + +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. + +.. literalinclude:: /includes/fundamentals/code-snippets/Monitoring.java + :language: java + :dedent: + :start-after: start cluster-listener-impl + :end-before: end cluster-listener-impl + +The following code adds an instance of the ``IsWritable`` class to a +``MongoClient`` object. The code then runs a find operation to test the +``IsWritable`` class. + +.. literalinclude:: /includes/fundamentals/code-snippets/Monitoring.java + :language: java + :dedent: + :start-after: start monitor-cluster-example + :end-before: end monitor-cluster-example + +The preceding code snippet produces output that resembles the following: + +.. code-block:: none + :copyable: false + + Able to write to server + +For more information about the classes and methods mentioned in this section, see +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>`__ +- `MongoClient <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoClient.html>`__ +- `ClusterDescriptionChangedEvent <{+api+}/apidocs/mongodb-driver-core/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 needs to perform with a MongoDB instance, and can help your +application run faster. + +To monitor connection pool events, write a class that implements the +``ConnectionPoolListener`` interface and register an instance of that class with your +``MongoClient`` instance. + +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. + +.. literalinclude:: /includes/fundamentals/code-snippets/Monitoring.java + :language: java + :dedent: + :start-after: start cp-listener-impl + :end-before: end cp-listener-impl + +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. + +.. literalinclude:: /includes/fundamentals/code-snippets/Monitoring.java + :language: java + :dedent: + :start-after: start monitor-cp-example + :end-before: end monitor-cp-example + +The preceding code snippet produces output that resembles the following: + +.. code-block:: none + :copyable: false + + Let me get you the connection with id 21... + +For more information about the classes and methods mentioned in this section, see +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>`__ +- `MongoClient <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoClient.html>`__ +- `ConnectionCheckedOutEvent <{+api+}/apidocs/mongodb-driver-core/com/mongodb/event/ConnectionCheckedOutEvent.html>`__ +- `ConnectionCheckOutFailedEvent <{+api+}/apidocs/mongodb-driver-core/com/mongodb/event/ConnectionCheckOutFailedEvent.html>`__ + +.. _monitoring-jmx: + +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 `__. + +JMX Support +~~~~~~~~~~~ + +To enable JMX connection pool monitoring, add an instance of the +``JMXConnectionPoolListener`` class to your ``MongoClient`` object. + +The ``JMXConnectionPoolListener`` class performs the following actions: + +#. Creates MXBean instances for each ``mongod`` or ``mongos`` process the driver + maintains a connection pool with. +#. Registers these MXBean instances with the platform MBean server. + +MXBeans registered on the platform MBean server have the following properties: + +.. list-table:: + :header-rows: 1 + :widths: 10 20 + + * - Property + - Description + + * - ``clusterId`` + - A client-generated unique identifier. This identifier ensures that + each MXBean the driver makes has a unique name when an application has + multiple ``MongoClient`` instances connected to the same MongoDB deployment. + + * - ``host`` + - The hostname of the machine running the ``mongod`` or ``mongos`` process. + + * - ``port`` + - The port on which the ``mongod`` or ``mongos`` process is listening. + + * - ``minSize`` + - The minimum size of the connection pool, including idle and in-use connections. + + * - ``maxSize`` + - The maximum size of the connection pool, including idle and in-use connections. + + * - ``size`` + - The current size of the connection pool, including idle and in-use connections. + + * - ``checkedOutCount`` + - The current count of connections that are in use. + + +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 +following resources from Oracle: + +- `Platform MBean Server Reference Documentation `__ +- `MXBean Documentation `__ +- `MBean Documentation `__ + +JMX and JConsole Example +~~~~~~~~~~~~~~~~~~~~~~~~ + +This example shows how you can monitor the driver's connection pools using JMX +and **JConsole**. JConsole is a JMX compliant GUI monitoring tool that comes with +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 + the following official Oracle resources: + + - `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. + +.. literalinclude:: /includes/fundamentals/code-snippets/JMXMonitoring.java + :language: java + :dedent: + :start-after: start jmx-example + :end-before: end jmx-example + +The preceding code snippet produces output that resembles the following: + +.. code-block:: none + :copyable: false + + Navigate to JConsole to see your connection pools... + +Once you have started your server, open JConsole in your terminal using the +following command: + +.. code-block:: shell + + jconsole + +Once JConsole is open, perform the following actions in the GUI: + +#. Select the Java process running the preceding example code. +#. Press :guilabel:`Insecure Connection` in the warning dialog box. +#. Click on the :guilabel:`MBeans` tab. +#. Inspect your connection pool events under the ``"org.mongodb.driver"`` domain. + +When you no longer want to inspect your connection pools in JConsole, do the +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 +Oracle: + +- `JConsole Documentation `__. +- `Monitoring and Management Guide `__ + +For more information about the ``JMXConnectionPoolListener`` class, see +the API Documentation for +`JMXConnectionPoolListener <{+api+}/apidocs/mongodb-driver-core/com/mongodb/management/JMXConnectionPoolListener.html>`__. + +Include the Driver in Your Distributed Tracing System +----------------------------------------------------- + +If you use a **distributed tracing system**, you can include event data from the +driver. A distributed tracing system is an application that +tracks requests as they propagate throughout different services in a +service-oriented architecture. + +If you use the driver in a `Spring Cloud `__ +application, use +`Spring Cloud Sleuth `__ to +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 `__ +for your desired distributed tracing system. To see an implementation of such a +listener, see the +:github:`TraceMongoCommandListener +` +class in the Spring Cloud Sleuth source code. + +To learn more about Spring Cloud Sleuth, see +`Getting Started `__ +in the Spring Cloud Sleuth documentation. + +To view a detailed description of a distributed tracing system, see +`Dapper `__ from Google Research. diff --git a/source/fundamentals/monitoring.txt b/source/fundamentals/monitoring.txt new file mode 100644 index 00000000..e7a0a785 --- /dev/null +++ b/source/fundamentals/monitoring.txt @@ -0,0 +1,115 @@ +.. _csharp-monitoring: + +========== +Monitoring +========== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: event, subscribe, listener + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +On this page, you can learn how to configure **monitoring** in the +{+driver-long+}. Monitoring is the process of gathering information about your +application's performance and resource usage as it runs. +This can help you make informed decisions when designing and debugging your application. + +The driver provides information about your application by emitting events. You can +subscribe to these driver events to monitor your application. + +.. note:: Event Logging + + This page explains how to monitor your application in code. To learn how to record + this information to an external log, see :ref:`Logging .` + +.. _csharp-event-types: + +Event Types +----------- + +The type of event that the driver emits depends on the operation being performed. +The following table describes the types of events that the driver emits: + +.. list-table:: + + * - Event Type + - Description + * - Command Events + - Events related to MongoDB database commands, such as ``find``, ``insert``, + ``delete``, and ``count``. To learn how to use the {+driver-short+} to run a + database command, see :ref:``. For more information about + MongoDB database commands, see :manual:`Database Commands ` + in the {+mdb-server+} manual. + + .. important:: Redacted Output + + 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 `. + + * - Server Discovery and Monitoring (SDAM) Events + - Events related to changes in the state of the MongoDB instance or cluster. + + * - Connection Pool Events + - Events related to the connection pool held by the driver. + +For a complete list of events the driver emits, see the API documentation for the +`MongoDB.Driver.Core.Events <{+new-api-root+/MongoDB.Driver/MongoDB.Driver.Core.Events.html>`__ +namespace. + +.. _csharp-monitor-events: + +Subscribing to Events +--------------------- + +To monitor an event, you must subscribe a listener method on your ``MongoClient`` instance. +The following steps describe how to subscribe to events: + +1. Create a ``MongoClientSettings`` object. +#. Set the ``ClusterConfigurator`` property on the ``MongoClientSettings`` object to a + lambda function that accepts a ``ClusterBuilder`` object. +#. In the lambda function, call the ``Subscribe()`` + method on the ``ClusterBuilder`` object for each event you want to subscribe to. + Replace ``TEvent`` with the event type. Pass the event handler + method as an argument to the ``Subscribe()`` method. + +The following code example shows how to subscribe to the ``ClusterOpenedEvent``, +``ServerHeartbeatSucceededEvent``, and ``ConnectionPoolReadyEvent``. This example +assumes that the ``ClusterEventHandler``, ``HeartbeatEventHandler``, +and ``ConnectionPoolEventHandler`` methods are defined elsewhere in your code. + +.. code-block:: csharp + + var clientSettings = MongoClientSettings.FromConnectionString(MongoConnectionString); + clientSettings.ClusterConfigurator = clusterBuilder => + { + clusterBuilder + .Subscribe(ClusterEventHandler) + .Subscribe(HeartbeatEventHandler) + .Subscribe(ConnectionPoolEventHandler); + }; + +.. tip:: + + You can subscribe to any number of events, and these events can be of different types. + +API Documentation +----------------- + +To learn more about the methods and classes used to monitor events in the driver, see the +following API documentation: + +- `MongoDB.Driver.Core.Events <{+new-api-root+/MongoDB.Driver/MongoDB.Driver.Core.Events.html>`__ +- `Subscribe() <{+new-api-root+/MongoDB.Driver/MongoDB.Driver.Core.Events.ClusterBuilder.Subscribe.html>`__ From ba14229237e256be691ce8c073fcb06b226d84ec Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 6 Dec 2024 16:05:13 -0600 Subject: [PATCH 2/6] delete java file --- source/fundamentals/java-monitoring.txt | 434 ------------------------ 1 file changed, 434 deletions(-) delete mode 100644 source/fundamentals/java-monitoring.txt diff --git a/source/fundamentals/java-monitoring.txt b/source/fundamentals/java-monitoring.txt deleted file mode 100644 index 33d17e71..00000000 --- a/source/fundamentals/java-monitoring.txt +++ /dev/null @@ -1,434 +0,0 @@ -========== -Monitoring -========== - -.. default-domain:: mongodb - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -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? - -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 -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 ` - -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 `. - -.. _monitoring-monitor-events: - -Monitor Events --------------- - -To monitor an **event**, you must register a **listener** on your ``MongoClient`` -instance. - -An event is any action that happens in a running program. The driver includes functionality -for listening to a subset of the events that occur when the driver is running. - -A listener is a class that performs some action when certain events occur. -A listener's API defines the events it can respond to. - -Each method of a listener class represents a response to a certain event. Each -method receives one argument: an object representing the event the method -responds to. - -The MongoDB Java driver organizes the events it defines into three categories: - -- Command Events -- Server Discovery and Monitoring Events -- Connection Pool Events - -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>`__. - -.. _command-events-java: - -Command Events -~~~~~~~~~~~~~~ - -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 -``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 `. - -.. 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 - commands related to connection establishment (such as the initial ``hello`` - command). - -.. important:: Redacted Output - - 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 `. - -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. - -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. - -The following code defines the ``CommandCounter`` class which implements the -``CommandListener`` interface: - -.. literalinclude:: /includes/fundamentals/code-snippets/Monitoring.java - :language: java - :dedent: - :start-after: start command-listener-impl - :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 -counter. - -.. _listener-mongo-client-settings-example: - -.. literalinclude:: /includes/fundamentals/code-snippets/Monitoring.java - :language: java - :dedent: - :start-after: start monitor-command-example - :end-before: end monitor-command-example - -The preceding code snippet produces output that resembles the following: - -.. code-block:: none - :copyable: false - - {find=1} - {find=2} - {find=2, endSessions=1} - -For more information 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>`__ -- `MongoClientSettings <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html>`__ -- `MongoClient <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoClient.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>`__ - -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: - -- ``ClusterListener``: :spec:`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. - -For a detailed description of each SDAM event in the driver, see the -:spec:`MongoDB SDAM Logging and Monitoring Specification `. - -.. 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 `. - -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. - -.. literalinclude:: /includes/fundamentals/code-snippets/Monitoring.java - :language: java - :dedent: - :start-after: start cluster-listener-impl - :end-before: end cluster-listener-impl - -The following code adds an instance of the ``IsWritable`` class to a -``MongoClient`` object. The code then runs a find operation to test the -``IsWritable`` class. - -.. literalinclude:: /includes/fundamentals/code-snippets/Monitoring.java - :language: java - :dedent: - :start-after: start monitor-cluster-example - :end-before: end monitor-cluster-example - -The preceding code snippet produces output that resembles the following: - -.. code-block:: none - :copyable: false - - Able to write to server - -For more information about the classes and methods mentioned in this section, see -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>`__ -- `MongoClient <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoClient.html>`__ -- `ClusterDescriptionChangedEvent <{+api+}/apidocs/mongodb-driver-core/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 needs to perform with a MongoDB instance, and can help your -application run faster. - -To monitor connection pool events, write a class that implements the -``ConnectionPoolListener`` interface and register an instance of that class with your -``MongoClient`` instance. - -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. - -.. literalinclude:: /includes/fundamentals/code-snippets/Monitoring.java - :language: java - :dedent: - :start-after: start cp-listener-impl - :end-before: end cp-listener-impl - -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. - -.. literalinclude:: /includes/fundamentals/code-snippets/Monitoring.java - :language: java - :dedent: - :start-after: start monitor-cp-example - :end-before: end monitor-cp-example - -The preceding code snippet produces output that resembles the following: - -.. code-block:: none - :copyable: false - - Let me get you the connection with id 21... - -For more information about the classes and methods mentioned in this section, see -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>`__ -- `MongoClient <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoClient.html>`__ -- `ConnectionCheckedOutEvent <{+api+}/apidocs/mongodb-driver-core/com/mongodb/event/ConnectionCheckedOutEvent.html>`__ -- `ConnectionCheckOutFailedEvent <{+api+}/apidocs/mongodb-driver-core/com/mongodb/event/ConnectionCheckOutFailedEvent.html>`__ - -.. _monitoring-jmx: - -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 `__. - -JMX Support -~~~~~~~~~~~ - -To enable JMX connection pool monitoring, add an instance of the -``JMXConnectionPoolListener`` class to your ``MongoClient`` object. - -The ``JMXConnectionPoolListener`` class performs the following actions: - -#. Creates MXBean instances for each ``mongod`` or ``mongos`` process the driver - maintains a connection pool with. -#. Registers these MXBean instances with the platform MBean server. - -MXBeans registered on the platform MBean server have the following properties: - -.. list-table:: - :header-rows: 1 - :widths: 10 20 - - * - Property - - Description - - * - ``clusterId`` - - A client-generated unique identifier. This identifier ensures that - each MXBean the driver makes has a unique name when an application has - multiple ``MongoClient`` instances connected to the same MongoDB deployment. - - * - ``host`` - - The hostname of the machine running the ``mongod`` or ``mongos`` process. - - * - ``port`` - - The port on which the ``mongod`` or ``mongos`` process is listening. - - * - ``minSize`` - - The minimum size of the connection pool, including idle and in-use connections. - - * - ``maxSize`` - - The maximum size of the connection pool, including idle and in-use connections. - - * - ``size`` - - The current size of the connection pool, including idle and in-use connections. - - * - ``checkedOutCount`` - - The current count of connections that are in use. - - -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 -following resources from Oracle: - -- `Platform MBean Server Reference Documentation `__ -- `MXBean Documentation `__ -- `MBean Documentation `__ - -JMX and JConsole Example -~~~~~~~~~~~~~~~~~~~~~~~~ - -This example shows how you can monitor the driver's connection pools using JMX -and **JConsole**. JConsole is a JMX compliant GUI monitoring tool that comes with -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 - the following official Oracle resources: - - - `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. - -.. literalinclude:: /includes/fundamentals/code-snippets/JMXMonitoring.java - :language: java - :dedent: - :start-after: start jmx-example - :end-before: end jmx-example - -The preceding code snippet produces output that resembles the following: - -.. code-block:: none - :copyable: false - - Navigate to JConsole to see your connection pools... - -Once you have started your server, open JConsole in your terminal using the -following command: - -.. code-block:: shell - - jconsole - -Once JConsole is open, perform the following actions in the GUI: - -#. Select the Java process running the preceding example code. -#. Press :guilabel:`Insecure Connection` in the warning dialog box. -#. Click on the :guilabel:`MBeans` tab. -#. Inspect your connection pool events under the ``"org.mongodb.driver"`` domain. - -When you no longer want to inspect your connection pools in JConsole, do the -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 -Oracle: - -- `JConsole Documentation `__. -- `Monitoring and Management Guide `__ - -For more information about the ``JMXConnectionPoolListener`` class, see -the API Documentation for -`JMXConnectionPoolListener <{+api+}/apidocs/mongodb-driver-core/com/mongodb/management/JMXConnectionPoolListener.html>`__. - -Include the Driver in Your Distributed Tracing System ------------------------------------------------------ - -If you use a **distributed tracing system**, you can include event data from the -driver. A distributed tracing system is an application that -tracks requests as they propagate throughout different services in a -service-oriented architecture. - -If you use the driver in a `Spring Cloud `__ -application, use -`Spring Cloud Sleuth `__ to -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 `__ -for your desired distributed tracing system. To see an implementation of such a -listener, see the -:github:`TraceMongoCommandListener -` -class in the Spring Cloud Sleuth source code. - -To learn more about Spring Cloud Sleuth, see -`Getting Started `__ -in the Spring Cloud Sleuth documentation. - -To view a detailed description of a distributed tracing system, see -`Dapper `__ from Google Research. From 4e8ce487f87ae39994ff749bedcde36ddec484ca Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 6 Dec 2024 16:13:13 -0600 Subject: [PATCH 3/6] fixes --- source/fundamentals/monitoring.txt | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/source/fundamentals/monitoring.txt b/source/fundamentals/monitoring.txt index e7a0a785..2a7a74e9 100644 --- a/source/fundamentals/monitoring.txt +++ b/source/fundamentals/monitoring.txt @@ -31,7 +31,7 @@ subscribe to these driver events to monitor your application. .. note:: Event Logging This page explains how to monitor your application in code. To learn how to record - this information to an external log, see :ref:`Logging .` + this information to an external log, see :ref:`Logging. ` .. _csharp-event-types: @@ -42,6 +42,8 @@ The type of event that the driver emits depends on the operation being performed The following table describes the types of events that the driver emits: .. list-table:: + :header-rows: 1 + :widths: 30 70 * - Event Type - Description @@ -55,9 +57,7 @@ The following table describes the types of events that the driver emits: .. important:: Redacted Output 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 `. + protects the sensitive information contained in these command events. * - Server Discovery and Monitoring (SDAM) Events - Events related to changes in the state of the MongoDB instance or cluster. @@ -66,7 +66,7 @@ The following table describes the types of events that the driver emits: - Events related to the connection pool held by the driver. For a complete list of events the driver emits, see the API documentation for the -`MongoDB.Driver.Core.Events <{+new-api-root+/MongoDB.Driver/MongoDB.Driver.Core.Events.html>`__ +`MongoDB.Driver.Core.Events <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Events.html>`__ namespace. .. _csharp-monitor-events: @@ -111,5 +111,5 @@ API Documentation To learn more about the methods and classes used to monitor events in the driver, see the following API documentation: -- `MongoDB.Driver.Core.Events <{+new-api-root+/MongoDB.Driver/MongoDB.Driver.Core.Events.html>`__ -- `Subscribe() <{+new-api-root+/MongoDB.Driver/MongoDB.Driver.Core.Events.ClusterBuilder.Subscribe.html>`__ +- `MongoDB.Driver.Core.Events <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Events.html>`__ +- `Subscribe() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Events.ClusterBuilder.Subscribe.html>`__ From 53e5a4101bbd737af02dca93fb668645b660a74e Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 6 Dec 2024 16:16:50 -0600 Subject: [PATCH 4/6] fix link --- source/fundamentals/monitoring.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/fundamentals/monitoring.txt b/source/fundamentals/monitoring.txt index 2a7a74e9..4b624312 100644 --- a/source/fundamentals/monitoring.txt +++ b/source/fundamentals/monitoring.txt @@ -112,4 +112,4 @@ To learn more about the methods and classes used to monitor events in the driver following API documentation: - `MongoDB.Driver.Core.Events <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Events.html>`__ -- `Subscribe() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Events.ClusterBuilder.Subscribe.html>`__ +- `Subscribe() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Core.Configuration.ClusterBuilder.Subscribe.html>`__ From 5e0c25abb30f9d631967f1ec20d9a1234d5b681d Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 6 Dec 2024 16:21:25 -0600 Subject: [PATCH 5/6] wording --- source/fundamentals/monitoring.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/fundamentals/monitoring.txt b/source/fundamentals/monitoring.txt index 4b624312..bf0a7026 100644 --- a/source/fundamentals/monitoring.txt +++ b/source/fundamentals/monitoring.txt @@ -60,7 +60,7 @@ The following table describes the types of events that the driver emits: protects the sensitive information contained in these command events. * - Server Discovery and Monitoring (SDAM) Events - - Events related to changes in the state of the MongoDB instance or cluster. + - Events related to changes in the state of the MongoDB deployment. * - Connection Pool Events - Events related to the connection pool held by the driver. From 92a697a47738d65391baaac424094d043e4247d0 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Mon, 9 Dec 2024 13:53:47 -0600 Subject: [PATCH 6/6] feedback --- source/fundamentals/monitoring.txt | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/source/fundamentals/monitoring.txt b/source/fundamentals/monitoring.txt index bf0a7026..49eb96f6 100644 --- a/source/fundamentals/monitoring.txt +++ b/source/fundamentals/monitoring.txt @@ -54,10 +54,9 @@ The following table describes the types of events that the driver emits: MongoDB database commands, see :manual:`Database Commands ` in the {+mdb-server+} manual. - .. important:: Redacted Output - - As a security measure, the driver redacts the contents of some command events. This - protects the sensitive information contained in these command events. + As a security measure, the driver redacts the contents of some + command events. This protects the sensitive information contained in these command + events. * - Server Discovery and Monitoring (SDAM) Events - Events related to changes in the state of the MongoDB deployment.