From 6baf059b7e23abb8d813251c87dc1cee5c1abd35 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Fri, 17 Jan 2025 17:53:28 -0500 Subject: [PATCH 01/10] DOCSP-45201 Cluster monitoring --- source/index.txt | 1 + source/monitoring.txt | 11 ++++++ source/monitoring/cluster-monitoring.txt | 48 ++++++++++++++++++++++++ 3 files changed, 60 insertions(+) create mode 100644 source/monitoring.txt create mode 100644 source/monitoring/cluster-monitoring.txt diff --git a/source/index.txt b/source/index.txt index fc871556..4862a033 100644 --- a/source/index.txt +++ b/source/index.txt @@ -17,6 +17,7 @@ Write Data Read Data Indexes + Monitor Your Application View the Source API Documentation <{+api-root+}> What's New diff --git a/source/monitoring.txt b/source/monitoring.txt new file mode 100644 index 00000000..d13920e9 --- /dev/null +++ b/source/monitoring.txt @@ -0,0 +1,11 @@ +.. _ruby-monitoring: + +======================== +Monitor Your Application +======================== + +.. toctree:: + :caption: Monitoring categories + + Cluster Monitoring + \ No newline at end of file diff --git a/source/monitoring/cluster-monitoring.txt b/source/monitoring/cluster-monitoring.txt new file mode 100644 index 00000000..894973d8 --- /dev/null +++ b/source/monitoring/cluster-monitoring.txt @@ -0,0 +1,48 @@ +.. _ruby-cluster-monitoring: + +================== +Cluster Monitoring +================== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, server, topology + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecols + +Overview +-------- + +The driver allows the application to be notified when certain events happen. These +events are organized into the following categories: + +- Command Monitoring + +- Server Discovery and Monitoring (SDAM) + +- Connection Pools and Connections + +Command Monitoring +------------------ + +SDAM +---- + +SDAM Event Descriptions +~~~~~~~~~~~~~~~~~~~~~~~ + +Connection Pools and Connections +-------------------------------- + +Excluded and Redacted Events +---------------------------- + + + From cdcf665b8ca0fc3fdc672bba302b0c6119e7b829 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 22 Jan 2025 16:21:31 -0500 Subject: [PATCH 02/10] first draft --- source/includes/monitoring/monitoring.rb | 225 +++++++++++++++++++++++ source/monitoring/cluster-monitoring.txt | 177 +++++++++++++++++- 2 files changed, 400 insertions(+), 2 deletions(-) create mode 100644 source/includes/monitoring/monitoring.rb diff --git a/source/includes/monitoring/monitoring.rb b/source/includes/monitoring/monitoring.rb new file mode 100644 index 00000000..adf1a560 --- /dev/null +++ b/source/includes/monitoring/monitoring.rb @@ -0,0 +1,225 @@ +# Command monitoring + +# start-command-logging +class CommandLogSubscriber + include Mongo::Loggable + + def started(event) + # The default inspection of a command which is a BSON document gets + # truncated in the middle. To get the full rendering of the command, the + # ``to_json`` method can be called on the document. + log_debug("#{prefix(event)} | STARTED | #{format_command(event.command.to_json)}") + end + + def succeeded(event) + log_debug("#{prefix(event)} | SUCCEEDED | #{event.duration}s") + end + + def failed(event) + log_debug("#{prefix(event)} | FAILED | #{event.message} | #{event.duration}s") + end + + private + + def logger + Mongo::Logger.logger + end + + def format_command(args) + begin + args.inspect + rescue Exception + '' + end + end + + def format_message(message) + format("COMMAND | %s".freeze, message) + end + + def prefix(event) + "#{event.address.to_s} | #{event.database_name}.#{event.command_name}" + end + end +# end-command-logging + +# start-command-subscriber +subscriber = CommandLogSubscriber.new + +Mongo::Monitoring::Global.subscribe(Mongo::Monitoring::COMMAND, subscriber) + +client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'test' ) +client.subscribe( Mongo::Monitoring::COMMAND, subscriber ) +# end-command-subscriber + +# start-sdam +class SDAMLogSubscriber + include Mongo::Loggable + + def succeeded(event) + log_debug(format_event(event)) + end + + private + + def logger + Mongo::Logger.logger + end + + def format_message(message) + format("SDAM | %s".freeze, message) + end + end + + class TopologyOpeningLogSubscriber < SDAMLogSubscriber + private + + def format_event(event) + "Topology type '#{event.topology.display_name}' initializing." + end + end + + class ServerOpeningLogSubscriber < SDAMLogSubscriber + private + + def format_event(event) + "Server #{event.address} initializing." + end + end + + class ServerDescriptionChangedLogSubscriber < SDAMLogSubscriber + private + + def format_event(event) + "Server description for #{event.address} changed from " + + "'#{event.previous_description.server_type}' to '#{event.new_description.server_type}'." + end + end + + class TopologyChangedLogSubscriber < SDAMLogSubscriber + private + + def format_event(event) + if event.previous_topology != event.new_topology + "Topology type '#{event.previous_topology.display_name}' changed to " + + "type '#{event.new_topology.display_name}'." + else + "There was a change in the members of the '#{event.new_topology.display_name}' " + + "topology." + end + end + end + + class ServerClosedLogSubscriber < SDAMLogSubscriber + private + + def format_event(event) + "Server #{event.address} connection closed." + end + end + + class TopologyClosedLogSubscriber < SDAMLogSubscriber + private + + def format_event(event) + "Topology type '#{event.topology.display_name}' closed." + end + end +#end-sdam + +# start-sdam-subscriber-global +topology_opening_subscriber = TopologyOpeningLogSubscriber.new +server_opening_subscriber = ServerOpeningLogSubscriber.new +server_description_changed_subscriber = ServerDescriptionChangedLogSubscriber.new +topology_changed_subscriber = TopologyChangedLogSubscriber.new +server_closed_subscriber = ServerClosedLogSubscriber.new +topology_closed_subscriber = TopologyClosedLogSubscriber.new + +Mongo::Monitoring::Global.subscribe(Mongo::Monitoring::TOPOLOGY_OPENING, + topology_opening_subscriber) +Mongo::Monitoring::Global.subscribe(Mongo::Monitoring::SERVER_OPENING, + server_opening_subscriber) +Mongo::Monitoring::Global.subscribe(Mongo::Monitoring::SERVER_DESCRIPTION_CHANGED, + server_description_changed_subscriber) +Mongo::Monitoring::Global.subscribe(Mongo::Monitoring::TOPOLOGY_CHANGED, + topology_changed_subscriber) +Mongo::Monitoring::Global.subscribe(Mongo::Monitoring::SERVER_CLOSED, + server_closed_subscriber) +Mongo::Monitoring::Global.subscribe(Mongo::Monitoring::TOPOLOGY_CLOSED, + topology_closed_subscriber) +# end-sdam-subscriber-global + +# start-sdam-subscriber-client +topology_opening_subscriber = TopologyOpeningLogSubscriber.new +server_opening_subscriber = ServerOpeningLogSubscriber.new +server_description_changed_subscriber = ServerDescriptionChangedLogSubscriber.new +topology_changed_subscriber = TopologyChangedLogSubscriber.new +server_closed_subscriber = ServerClosedLogSubscriber.new +topology_closed_subscriber = TopologyClosedLogSubscriber.new + +sdam_proc = Proc.new do |client| + client.subscribe(Mongo::Monitoring::TOPOLOGY_OPENING, + topology_opening_subscriber) + client.subscribe(Mongo::Monitoring::SERVER_OPENING, + server_opening_subscriber) + client.subscribe(Mongo::Monitoring::SERVER_DESCRIPTION_CHANGED, + server_description_changed_subscriber) + client.subscribe(Mongo::Monitoring::TOPOLOGY_CHANGED, + topology_changed_subscriber) + client.subscribe(Mongo::Monitoring::SERVER_CLOSED, + server_closed_subscriber) + client.subscribe(Mongo::Monitoring::TOPOLOGY_CLOSED, + topology_closed_subscriber) +end + +client = Mongo::Client.new(['127.0.0.1:27017'], database: 'test', + sdam_proc: sdam_proc) +# end-sdam-subscriber-client + +# start-heartbeat +class HeartbeatLogSubscriber + include Mongo::Loggable + + def started(event) + log_debug("#{event.address} | STARTED") + end + + def succeeded(event) + log_debug("#{event.address} | SUCCEEDED | #{event.duration}s") + end + + def failed(event) + log_debug("#{event.address} | FAILED | #{event.error.class}: #{event.error.message} | #{event.duration}s") + end + + private + + def logger + Mongo::Logger.logger + end + + def format_message(message) + format("HEARTBEAT | %s".freeze, message) + end + end +# end-heartbeat + +# start-heartbeat-subscribe +subscriber = HeartbeatLogSubscriber.new + +Mongo::Monitoring::Global.subscribe(Mongo::Monitoring::SERVER_HEARTBEAT, subscriber) + +client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'test' ) +client.subscribe( Mongo::Monitoring::SERVER_HEARTBEAT, subscriber ) +# end-heartbeat-subscribe + +# Connection Pool +# start-pool-subscriber +Mongo::Monitoring::Global.subscribe( + Mongo::Monitoring::CONNECTION_POOL, + Mongo::Monitoring::CmapLogSubscriber.new) + +client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'test' ) +subscriber = Mongo::Monitoring::CmapLogSubscriber.new +client.subscribe( Mongo::Monitoring::CONNECTION_POOL, subscriber ) +# end-pool-subscriber diff --git a/source/monitoring/cluster-monitoring.txt b/source/monitoring/cluster-monitoring.txt index 894973d8..33e94d09 100644 --- a/source/monitoring/cluster-monitoring.txt +++ b/source/monitoring/cluster-monitoring.txt @@ -32,17 +32,190 @@ events are organized into the following categories: Command Monitoring ------------------ +All user-initiated commands that are sent to the server publish event +information. You can subscribe to these commands to read event information. + +A subscriber must implement the following three methods: + +- ``started`` +- ``succeeded`` +- ``failed``, each which takes a single parameter for the event. + +The following is an example logging subscriber based on a logging subscriber +used internally by the driver: + +.. literalinclude:: /includes/monitoring/monitoring.rb + :start-after: start-command-logging + :end-before: end-command-logging + :language: ruby + :copyable: + :dedent: + +To register a custom subscriber, you can do so globally for all clients or +on a per-client basis: + +.. literalinclude:: /includes/monitoring/monitoring.rb + :start-after: start-command-subscriber + :end-before: end-command-subscriber + :language: ruby + :copyable: + :dedent: + +Sample output: + +.. code-block:: none + + D, [2018-09-23T13:47:31.258020 #4692] DEBUG -- : COMMAND | 127.0.0.1:27027 | test.hello | STARTED | {"hello"=>1, "$readPreference"=>{"mode"=>"primary"}, "lsid"=>{"id"=>}} + D, [2018-09-23T13:47:31.259145 #4692] DEBUG -- : COMMAND | 127.0.0.1:27027 | test.hello | SUCCEEDED | 0.000791175s + SDAM ---- +The Ruby driver implements `Server Discovery And Monitoring (SDAM) specification +`_. +and makes the following events available to the application: + +- Topology opening +- Server opening +- Server description changed +- Topology changed +- Server closed +- Topology closed +- Heartbeat events (covered below in a separate section) + +For all events other than the heartbeat events, the ``succeeded`` method +will be called on each event subscriber with the event as the sole argument. +Available data for events varies, therefore to log the events a separate +class is needed for each event type. A simple SDAM logging subscriber +can look like the following: + +.. literalinclude:: /includes/monitoring/monitoring.rb + :start-after: start-sdam + :end-before: end-sdam + :language: ruby + :copyable: + :dedent: + +To subscribe to SDAM events globally: + +.. literalinclude:: /includes/monitoring/monitoring.rb + :start-after: start-sdam-subscriber-global + :end-before: end-sdam-subscriber-global + :language: ruby + :copyable: + :dedent: + +To subscribe to SDAM events for a single client by using the ``sdam-proc`` client option: + +.. literalinclude:: /includes/monitoring/monitoring.rb + :start-after: start-sdam-subscriber-client + :end-before: end-sdam-subscriber-client + :language: ruby + :copyable: + :dedent: + +Sample output: + +.. code-block:: none + + D, [2018-10-09T13:58:03.489461 #22079] DEBUG -- : SDAM | Topology type 'Unknown' initializing. + D, [2018-10-09T13:58:03.489699 #22079] DEBUG -- : SDAM | Server 127.0.0.1:27100 initializing. + D, [2018-10-09T13:58:03.491384 #22079] DEBUG -- : SDAM | Server description for 127.0.0.1:27100 changed from 'unknown' to 'unknown'. + D, [2018-10-09T13:58:03.491642 #22079] DEBUG -- : SDAM | Server localhost:27100 initializing. + D, [2018-10-09T13:58:03.493199 #22079] DEBUG -- : SDAM | Server description for localhost:27100 changed from 'unknown' to 'primary'. + D, [2018-10-09T13:58:03.493473 #22079] DEBUG -- : SDAM | Server localhost:27101 initializing. + D, [2018-10-09T13:58:03.494874 #22079] DEBUG -- : SDAM | Server description for localhost:27101 changed from 'unknown' to 'secondary'. + D, [2018-10-09T13:58:03.495139 #22079] DEBUG -- : SDAM | Server localhost:27102 initializing. + D, [2018-10-09T13:58:03.496504 #22079] DEBUG -- : SDAM | Server description for localhost:27102 changed from 'unknown' to 'secondary'. + D, [2018-10-09T13:58:03.496777 #22079] DEBUG -- : SDAM | Topology type 'Unknown' changed to type 'ReplicaSetNoPrimary'. + D, [2018-10-09T13:58:03.497306 #22079] DEBUG -- : SDAM | Server 127.0.0.1:27100 connection closed. + D, [2018-10-09T13:58:03.497606 #22079] DEBUG -- : SDAM | Topology type 'ReplicaSetNoPrimary' changed to type 'ReplicaSetWithPrimary'. + + # client.close + + D, [2018-10-09T13:58:05.342057 #22079] DEBUG -- : SDAM | Server localhost:27100 connection closed. + D, [2018-10-09T13:58:05.342299 #22079] DEBUG -- : SDAM | Server localhost:27101 connection closed. + D, [2018-10-09T13:58:05.342565 #22079] DEBUG -- : SDAM | Server localhost:27102 connection closed. + D, [2018-10-09T13:58:05.342693 #22079] DEBUG -- : SDAM | Topology type 'ReplicaSetWithPrimary' closed. + +.. note:: + + ``:sdam_proc`` client option applies only to the client during whose + construction it is given. When certain client options are changed via the + ``Client#with`` call, a new cluster may be created by the driver with + a default set of event subscribers. If this happens, the provided + ``:sdam_proc`` is not called and the application may miss events. + SDAM Event Descriptions ~~~~~~~~~~~~~~~~~~~~~~~ Connection Pools and Connections -------------------------------- -Excluded and Redacted Events ----------------------------- +Each client maintains a connection pool for each server in the deployment that +it is aware of, and publishes events for both connection pools and individual +connections. To subscribe to these events, define a subscriber class implementing +the method ``pubished`` which takes a single parameter for the event that +is being published. Note that future versions of the driver may introduce +additional events published through this mechanism. + +The following events are currently implemented by the driver, following +the `CMAP specification `_: + +- PoolCreated +- PoolCleared +- PoolClosed +- ConnectionCreated +- ConnectionReady +- ConnectionClosed +- ConnectionCheckOutStarted +- ConnectionCheckOutFailed +- ConnectionCheckOutSucceeded +- ConnectionCheckedIn + +The driver provides a logging subscriber which may be used to log all +connection pool and connection-related events. This subscriber is not enabled +by default because it will create log entries for each operation performed +by the application. To enable this subscriber globally or per client: + +.. code-block:: ruby + + Mongo::Monitoring::Global.subscribe( + Mongo::Monitoring::CONNECTION_POOL, + Mongo::Monitoring::CmapLogSubscriber.new) + + client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'test' ) + subscriber = Mongo::Monitoring::CmapLogSubscriber.new + client.subscribe( Mongo::Monitoring::CONNECTION_POOL, subscriber ) + +Sample output: + +.. code-block:: none + + D, [2019-05-06T17:23:21.595412 #8576] DEBUG -- : MONGODB | EVENT: # + D, [2019-05-06T17:23:21.595584 #8576] DEBUG -- : MONGODB | EVENT: # + D, [2019-05-06T17:23:21.603549 #8576] DEBUG -- : MONGODB | EVENT: # + D, [2019-05-06T17:23:21.603616 #8576] DEBUG -- : MONGODB | EVENT: # + D, [2019-05-06T17:23:21.603684 #8576] DEBUG -- : MONGODB | EVENT: # + D, [2019-05-06T17:23:21.604079 #8576] DEBUG -- : MONGODB | EVENT: # + D, [2019-05-06T17:23:21.605759 #8576] DEBUG -- : MONGODB | EVENT: # + D, [2019-05-06T17:23:21.605784 #8576] DEBUG -- : MONGODB | EVENT: # + D, [2019-05-06T17:23:21.605817 #8576] DEBUG -- : MONGODB | EVENT: # + D, [2019-05-06T17:23:21.605852 #8576] DEBUG -- : MONGODB | EVENT: # + +Disabling Monitoring +-------------------- + +To turn off monitoring, set the client monitoring option to ``false``: + +.. code-block:: ruby + + client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'test', :monitoring => false ) + + + + + From 7a109c8ea0ea9523a0d223f21b7b56227b921544 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 22 Jan 2025 23:38:04 -0500 Subject: [PATCH 03/10] remove eevrything not about cluster monitoring: --- source/includes/monitoring/monitoring.rb | 7 + source/monitoring/cluster-monitoring.txt | 192 ++++++++++++----------- 2 files changed, 111 insertions(+), 88 deletions(-) diff --git a/source/includes/monitoring/monitoring.rb b/source/includes/monitoring/monitoring.rb index adf1a560..455d94ef 100644 --- a/source/includes/monitoring/monitoring.rb +++ b/source/includes/monitoring/monitoring.rb @@ -1,5 +1,12 @@ # Command monitoring +# start-available-subscriber +Mongo::Monitoring::Global.subscribe(Mongo::Monitoring::COMMAND, subscriber) +client = Mongo::Client.new(['127.0.0.1:27017']) + +client.subscribe( Mongo::Monitoring::COMMAND, subscriber ) +# end-available-subscriber + # start-command-logging class CommandLogSubscriber include Mongo::Loggable diff --git a/source/monitoring/cluster-monitoring.txt b/source/monitoring/cluster-monitoring.txt index 33e94d09..38536ea6 100644 --- a/source/monitoring/cluster-monitoring.txt +++ b/source/monitoring/cluster-monitoring.txt @@ -20,29 +20,82 @@ Cluster Monitoring Overview -------- -The driver allows the application to be notified when certain events happen. These -events are organized into the following categories: +This guide shows you how to use the {+driver-short+} to monitor server discovery +and monitoring (SDAM) events events in a MongoDB instance, replica set, or sharded +cluster by using custom subscribers or available subscriber methods. These events +occur when there are any changes in the state of the MongoDB instance or cluster +that you are connected to. -- Command Monitoring +You can use information about SDAM events in your application to understand +cluster changes, assess cluster health, or perform capacity planning. -- Server Discovery and Monitoring (SDAM) +Available SDAM Subscribers +-------------------------- -- Connection Pools and Connections +You can use the {+driver-short+}'s ``subscribe`` method to subscribe to events. +The ``subscribe`` method requires you to specify a monitoring ``topic`` +(the event type) and a subscriber object. -Command Monitoring ------------------- +The following code uses the ``CommandLogSubscriber`` to monitor command events: + +.. literalinclude:: /includes/monitoring/monitoring.rb + :start-after: start-available-subscriber + :end-before: end-available-subscriber + :language: ruby + :copyable: + :dedent: + +The following table provides available subscribers and their event types: + +.. list-table:: + :header-rows: 1 + :widths: 20 20 60 + + * - Method Name + - Monitoring Topic + - Description + + * - SDAMLogSubscriber + - + - Subscribes to SDAM events and logs them. + + * - ServerClosedLogSubscriber + - ``SERVER_CLOSED`` + - Subscribes to Server Closed events and logs them. + + * - ServerDescriptionChangedLogSubscriber + - ``SERVER_DESCRIPTION_CHANGED`` + - Subscribes to Server Description Changed events and logs them. + + * - ServerOpeningLogSubscriber + - ``SERVER_OPENING`` + - Subscribes to Server Opening events and logs them. -All user-initiated commands that are sent to the server publish event -information. You can subscribe to these commands to read event information. + * - TopologyChangedLogSubscriber + - ``TOPOLOGY_CHANGED`` + - Subscribes to Topology Changed events and logs them. + + * - TopologyClosedLogSubscriber + - ``TOPOLOGY_CLOSED`` + - Subscribes to Topology Closed events and logs them. + + * - TopologyOpeningLogSubscriber + - ``TOPOLOGY_OPENING`` + - Subscribes to Topology Opening events and logs them. + +Custom Command Monitoring +------------------------- + +You can create a custom command subscriber to access details about server +and topology events. A subscriber must implement the following three methods: -- ``started`` -- ``succeeded`` -- ``failed``, each which takes a single parameter for the event. +- ``started``: Response when you initiate the command +- ``succeeded``: Response when the command succeeds +- ``failed``: Response when the command fails -The following is an example logging subscriber based on a logging subscriber -used internally by the driver: +The following is an example command logging subscriber: .. literalinclude:: /includes/monitoring/monitoring.rb :start-after: start-command-logging @@ -61,30 +114,26 @@ on a per-client basis: :copyable: :dedent: -Sample output: +When you run the application, your subscriber records the commands' event information +and outputs logs such as the following: .. code-block:: none D, [2018-09-23T13:47:31.258020 #4692] DEBUG -- : COMMAND | 127.0.0.1:27027 | test.hello | STARTED | {"hello"=>1, "$readPreference"=>{"mode"=>"primary"}, "lsid"=>{"id"=>}} D, [2018-09-23T13:47:31.259145 #4692] DEBUG -- : COMMAND | 127.0.0.1:27027 | test.hello | SUCCEEDED | 0.000791175s -SDAM ----- +Custom SDAM Monitoring +---------------------- -The Ruby driver implements `Server Discovery And Monitoring (SDAM) specification -`_. -and makes the following events available to the application: +You can create a custom command subscriber to access details about server +and topology events. -- Topology opening -- Server opening -- Server description changed -- Topology changed -- Server closed -- Topology closed -- Heartbeat events (covered below in a separate section) +A subscriber must implement the following three methods: + +- ``started``: Response when you initiate the command +- ``succeeded``: Response when the command succeeds +- ``failed``: Response when the command fails -For all events other than the heartbeat events, the ``succeeded`` method -will be called on each event subscriber with the event as the sole argument. Available data for events varies, therefore to log the events a separate class is needed for each event type. A simple SDAM logging subscriber can look like the following: @@ -146,76 +195,43 @@ Sample output: a default set of event subscribers. If this happens, the provided ``:sdam_proc`` is not called and the application may miss events. -SDAM Event Descriptions -~~~~~~~~~~~~~~~~~~~~~~~ - -Connection Pools and Connections --------------------------------- - -Each client maintains a connection pool for each server in the deployment that -it is aware of, and publishes events for both connection pools and individual -connections. To subscribe to these events, define a subscriber class implementing -the method ``pubished`` which takes a single parameter for the event that -is being published. Note that future versions of the driver may introduce -additional events published through this mechanism. - -The following events are currently implemented by the driver, following -the `CMAP specification `_: - -- PoolCreated -- PoolCleared -- PoolClosed -- ConnectionCreated -- ConnectionReady -- ConnectionClosed -- ConnectionCheckOutStarted -- ConnectionCheckOutFailed -- ConnectionCheckOutSucceeded -- ConnectionCheckedIn - -The driver provides a logging subscriber which may be used to log all -connection pool and connection-related events. This subscriber is not enabled -by default because it will create log entries for each operation performed -by the application. To enable this subscriber globally or per client: - -.. code-block:: ruby - - Mongo::Monitoring::Global.subscribe( - Mongo::Monitoring::CONNECTION_POOL, - Mongo::Monitoring::CmapLogSubscriber.new) - - client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'test' ) - subscriber = Mongo::Monitoring::CmapLogSubscriber.new - client.subscribe( Mongo::Monitoring::CONNECTION_POOL, subscriber ) - -Sample output: +Event Descriptions +------------------ -.. code-block:: none +.. figure out what to do with this - D, [2019-05-06T17:23:21.595412 #8576] DEBUG -- : MONGODB | EVENT: # - D, [2019-05-06T17:23:21.595584 #8576] DEBUG -- : MONGODB | EVENT: # - D, [2019-05-06T17:23:21.603549 #8576] DEBUG -- : MONGODB | EVENT: # - D, [2019-05-06T17:23:21.603616 #8576] DEBUG -- : MONGODB | EVENT: # - D, [2019-05-06T17:23:21.603684 #8576] DEBUG -- : MONGODB | EVENT: # - D, [2019-05-06T17:23:21.604079 #8576] DEBUG -- : MONGODB | EVENT: # - D, [2019-05-06T17:23:21.605759 #8576] DEBUG -- : MONGODB | EVENT: # - D, [2019-05-06T17:23:21.605784 #8576] DEBUG -- : MONGODB | EVENT: # - D, [2019-05-06T17:23:21.605817 #8576] DEBUG -- : MONGODB | EVENT: # - D, [2019-05-06T17:23:21.605852 #8576] DEBUG -- : MONGODB | EVENT: # +The Ruby driver implements `Server Discovery And Monitoring (SDAM) specification +`_. +and makes the following events available to the application: -Disabling Monitoring --------------------- +- Topology opening +- Server opening +- Server description changed +- Topology changed +- Server closed +- Topology closed +- Heartbeat events (covered below in a separate section) -To turn off monitoring, set the client monitoring option to ``false``: +You can monitor the following SDAM events: -.. code-block:: ruby +.. list-table:: + :header-rows: 1 + :widths: 40 60 - client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'test', :monitoring => false ) + * - Event Type + - Description + * - + - +API Documentation +----------------- +To learn more about any of the methods discussed in this guide, see the following API documentation: +- `Mongo::Monitoring::Event <{+api-root+}/Mongo/Monitoring/Event.html>`__ +.. event descriptions table, reread for active voice, api doc section, remove unnecessary code From b7edbee9630a2e7a8f05519b8cf96a978ae2883d Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Thu, 23 Jan 2025 12:08:22 -0500 Subject: [PATCH 04/10] table changes --- source/monitoring/cluster-monitoring.txt | 39 ++++++++++++++++++------ 1 file changed, 30 insertions(+), 9 deletions(-) diff --git a/source/monitoring/cluster-monitoring.txt b/source/monitoring/cluster-monitoring.txt index 38536ea6..d21bb37b 100644 --- a/source/monitoring/cluster-monitoring.txt +++ b/source/monitoring/cluster-monitoring.txt @@ -55,31 +55,31 @@ The following table provides available subscribers and their event types: - Monitoring Topic - Description - * - SDAMLogSubscriber + * - `SDAMLogSubscriber <{+api-root+}/Mongo/Monitoring/SDAMLogSubscriber.html>`__ - - Subscribes to SDAM events and logs them. - * - ServerClosedLogSubscriber + * - `ServerClosedLogSubscriber <{+api-root+}/Mongo/Monitoring/ServerClosedLogSubscriber.html>`__ - ``SERVER_CLOSED`` - Subscribes to Server Closed events and logs them. - * - ServerDescriptionChangedLogSubscriber + * - `ServerDescriptionChangedLogSubscriber <{+api-root+}/Mongo/Monitoring/ServerDescriptionChangedLogSubscriber.html>`__ - ``SERVER_DESCRIPTION_CHANGED`` - Subscribes to Server Description Changed events and logs them. - * - ServerOpeningLogSubscriber + * - `ServerOpeningLogSubscriber <{+api-root+}/Mongo/Monitoring/ServerOpeningLogSubscriber.html>`__ - ``SERVER_OPENING`` - Subscribes to Server Opening events and logs them. - * - TopologyChangedLogSubscriber + * - `TopologyChangedLogSubscriber <{+api-root+}/Mongo/Monitoring/TopologyChangedLogSubscriber.html>`__ - ``TOPOLOGY_CHANGED`` - Subscribes to Topology Changed events and logs them. - * - TopologyClosedLogSubscriber + * - `TopologyClosedLogSubscriber <{+api-root+}/Mongo/Monitoring/TopologyClosedLogSubscriber.html>`__ - ``TOPOLOGY_CLOSED`` - Subscribes to Topology Closed events and logs them. - * - TopologyOpeningLogSubscriber + * - `TopologyOpeningLogSubscriber <{+api-root+}/Mongo/Monitoring/TopologyOpeningLogSubscriber.html>`__ - ``TOPOLOGY_OPENING`` - Subscribes to Topology Opening events and logs them. @@ -221,11 +221,32 @@ You can monitor the following SDAM events: * - Event Type - Description - * - - - + * - `ServerClosed <{+api-root+}/Mongo/Monitoring/Event/ServerClosed.html>`__ + - Event fired when the server is closed. + + * - `ServerDescriptionChanged <{+api-root+}/Mongo/Monitoring/Event/ServerDescriptionChanged.html>`__ + - Event fired when a server's description changes. + + * - `ServerHeartbeatFailed <{+api-root+}/Mongo/Monitoring/Event/ServerHeartbeatFailed.html>`__ + - Event fired when a server heartbeat fails. + + * - `ServerHeartbeatStarted <{+api-root+}/Mongo/Monitoring/Event/ServerHeartbeatStarted.html>`__ + - Event fired when a server heartbeat is dispatched. + + * - `ServerHeartbeatSucceeded <{+api-root+}/Mongo/Monitoring/Event/ServerHeartbeatSucceeded.html>`__ + - Event fired when a server heartbeat successfully returns. + + * - `ServerOpening <{+api-root+}/Mongo/Monitoring/Event/ServerOpening.html>`__ + - Event fired when the driver connects to the server. + * - `TopologyChanged <{+api-root+}/Mongo/Monitoring/Event/TopologyChanged.html>`__ + - Event fired when the topology changes. + * - `TopologyClosed <{+api-root+}/Mongo/Monitoring/Event/TopologyClosed.html>`__ + - Event fired when all instance connections in the topology close. + * - `TopologyOpening <{+api-root+}/Mongo/Monitoring/Event/TopologyOpening.html>`__ + - Event fired before the driver attempts to connect to an instance. API Documentation ----------------- From 9bda124d1a5ce57144c81fcf21ca3186e59f202f Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Thu, 23 Jan 2025 13:09:09 -0500 Subject: [PATCH 05/10] review --- source/includes/monitoring/monitoring.rb | 75 ++--------- source/monitoring/cluster-monitoring.txt | 153 +++++++++++------------ 2 files changed, 79 insertions(+), 149 deletions(-) diff --git a/source/includes/monitoring/monitoring.rb b/source/includes/monitoring/monitoring.rb index 455d94ef..0193fe6a 100644 --- a/source/includes/monitoring/monitoring.rb +++ b/source/includes/monitoring/monitoring.rb @@ -1,64 +1,14 @@ -# Command monitoring - # start-available-subscriber -Mongo::Monitoring::Global.subscribe(Mongo::Monitoring::COMMAND, subscriber) +subscriber = Mongo::Monitoring::ServerOpeningLogSubscriber.new + +# Globally subscribes to Server Opening events +Mongo::Monitoring::Global.subscribe(Mongo::Monitoring::SERVER_OPENING, subscriber) client = Mongo::Client.new(['127.0.0.1:27017']) -client.subscribe( Mongo::Monitoring::COMMAND, subscriber ) +# Subscribes to Server Opening events at the client level +client.subscribe( Mongo::Monitoring::SERVER_OPENING, subscriber ) # end-available-subscriber -# start-command-logging -class CommandLogSubscriber - include Mongo::Loggable - - def started(event) - # The default inspection of a command which is a BSON document gets - # truncated in the middle. To get the full rendering of the command, the - # ``to_json`` method can be called on the document. - log_debug("#{prefix(event)} | STARTED | #{format_command(event.command.to_json)}") - end - - def succeeded(event) - log_debug("#{prefix(event)} | SUCCEEDED | #{event.duration}s") - end - - def failed(event) - log_debug("#{prefix(event)} | FAILED | #{event.message} | #{event.duration}s") - end - - private - - def logger - Mongo::Logger.logger - end - - def format_command(args) - begin - args.inspect - rescue Exception - '' - end - end - - def format_message(message) - format("COMMAND | %s".freeze, message) - end - - def prefix(event) - "#{event.address.to_s} | #{event.database_name}.#{event.command_name}" - end - end -# end-command-logging - -# start-command-subscriber -subscriber = CommandLogSubscriber.new - -Mongo::Monitoring::Global.subscribe(Mongo::Monitoring::COMMAND, subscriber) - -client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'test' ) -client.subscribe( Mongo::Monitoring::COMMAND, subscriber ) -# end-command-subscriber - # start-sdam class SDAMLogSubscriber include Mongo::Loggable @@ -214,19 +164,10 @@ def format_message(message) # start-heartbeat-subscribe subscriber = HeartbeatLogSubscriber.new +# Globally subscribes to Server Opening events Mongo::Monitoring::Global.subscribe(Mongo::Monitoring::SERVER_HEARTBEAT, subscriber) +# Subscribes to Server Opening events at the client level client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'test' ) client.subscribe( Mongo::Monitoring::SERVER_HEARTBEAT, subscriber ) # end-heartbeat-subscribe - -# Connection Pool -# start-pool-subscriber -Mongo::Monitoring::Global.subscribe( - Mongo::Monitoring::CONNECTION_POOL, - Mongo::Monitoring::CmapLogSubscriber.new) - -client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'test' ) -subscriber = Mongo::Monitoring::CmapLogSubscriber.new -client.subscribe( Mongo::Monitoring::CONNECTION_POOL, subscriber ) -# end-pool-subscriber diff --git a/source/monitoring/cluster-monitoring.txt b/source/monitoring/cluster-monitoring.txt index d21bb37b..395b6531 100644 --- a/source/monitoring/cluster-monitoring.txt +++ b/source/monitoring/cluster-monitoring.txt @@ -29,14 +29,15 @@ that you are connected to. You can use information about SDAM events in your application to understand cluster changes, assess cluster health, or perform capacity planning. -Available SDAM Subscribers --------------------------- +SDAM Subscribers +---------------- You can use the {+driver-short+}'s ``subscribe`` method to subscribe to events. The ``subscribe`` method requires you to specify a monitoring ``topic`` -(the event type) and a subscriber object. +(the monitored event type) and a subscriber object. -The following code uses the ``CommandLogSubscriber`` to monitor command events: +The following code uses the ``ServerOpeningLogSubscriber`` to monitor a connection +to a server instance. You can subscribe to events at a global or client level: .. literalinclude:: /includes/monitoring/monitoring.rb :start-after: start-available-subscriber @@ -45,7 +46,7 @@ The following code uses the ``CommandLogSubscriber`` to monitor command events: :copyable: :dedent: -The following table provides available subscribers and their event types: +The following table provides available subscribers and their monitoring ``topic``: .. list-table:: :header-rows: 1 @@ -61,82 +62,41 @@ The following table provides available subscribers and their event types: * - `ServerClosedLogSubscriber <{+api-root+}/Mongo/Monitoring/ServerClosedLogSubscriber.html>`__ - ``SERVER_CLOSED`` - - Subscribes to Server Closed events and logs them. + - Subscribes to ``ServerClosed`` events and logs them. * - `ServerDescriptionChangedLogSubscriber <{+api-root+}/Mongo/Monitoring/ServerDescriptionChangedLogSubscriber.html>`__ - ``SERVER_DESCRIPTION_CHANGED`` - - Subscribes to Server Description Changed events and logs them. + - Subscribes to ``ServerDescriptionChanged`` events and logs them. * - `ServerOpeningLogSubscriber <{+api-root+}/Mongo/Monitoring/ServerOpeningLogSubscriber.html>`__ - ``SERVER_OPENING`` - - Subscribes to Server Opening events and logs them. + - Subscribes to ``ServerOpening`` events and logs them. * - `TopologyChangedLogSubscriber <{+api-root+}/Mongo/Monitoring/TopologyChangedLogSubscriber.html>`__ - ``TOPOLOGY_CHANGED`` - - Subscribes to Topology Changed events and logs them. + - Subscribes to ``TopologyChanged`` events and logs them. * - `TopologyClosedLogSubscriber <{+api-root+}/Mongo/Monitoring/TopologyClosedLogSubscriber.html>`__ - ``TOPOLOGY_CLOSED`` - - Subscribes to Topology Closed events and logs them. + - Subscribes to ``TopologyClosed`` events and logs them. * - `TopologyOpeningLogSubscriber <{+api-root+}/Mongo/Monitoring/TopologyOpeningLogSubscriber.html>`__ - ``TOPOLOGY_OPENING`` - - Subscribes to Topology Opening events and logs them. + - Subscribes to ``TopologyOpening`` events and logs them. -Custom Command Monitoring -------------------------- - -You can create a custom command subscriber to access details about server -and topology events. - -A subscriber must implement the following three methods: - -- ``started``: Response when you initiate the command -- ``succeeded``: Response when the command succeeds -- ``failed``: Response when the command fails - -The following is an example command logging subscriber: - -.. literalinclude:: /includes/monitoring/monitoring.rb - :start-after: start-command-logging - :end-before: end-command-logging - :language: ruby - :copyable: - :dedent: - -To register a custom subscriber, you can do so globally for all clients or -on a per-client basis: - -.. literalinclude:: /includes/monitoring/monitoring.rb - :start-after: start-command-subscriber - :end-before: end-command-subscriber - :language: ruby - :copyable: - :dedent: - -When you run the application, your subscriber records the commands' event information -and outputs logs such as the following: - -.. code-block:: none - - D, [2018-09-23T13:47:31.258020 #4692] DEBUG -- : COMMAND | 127.0.0.1:27027 | test.hello | STARTED | {"hello"=>1, "$readPreference"=>{"mode"=>"primary"}, "lsid"=>{"id"=>}} - D, [2018-09-23T13:47:31.259145 #4692] DEBUG -- : COMMAND | 127.0.0.1:27027 | test.hello | SUCCEEDED | 0.000791175s +You can find a table of SDAM event descriptions in the :ref:`Event Descriptions ` +section on this page. Custom SDAM Monitoring ---------------------- You can create a custom command subscriber to access details about server -and topology events. - -A subscriber must implement the following three methods: +and topology events. Create a separate class for each event type, as available +data for each event varies. -- ``started``: Response when you initiate the command -- ``succeeded``: Response when the command succeeds -- ``failed``: Response when the command fails - -Available data for events varies, therefore to log the events a separate -class is needed for each event type. A simple SDAM logging subscriber -can look like the following: +For all events, the ``succeeded`` method is called on each event subscriber with +the event as the sole argument. A simple SDAM logging subscriber can look +like the following: .. literalinclude:: /includes/monitoring/monitoring.rb :start-after: start-sdam @@ -145,7 +105,7 @@ can look like the following: :copyable: :dedent: -To subscribe to SDAM events globally: +The following code shows how to subscribe to SDAM events globally: .. literalinclude:: /includes/monitoring/monitoring.rb :start-after: start-sdam-subscriber-global @@ -154,7 +114,8 @@ To subscribe to SDAM events globally: :copyable: :dedent: -To subscribe to SDAM events for a single client by using the ``sdam-proc`` client option: +The following code shows how to subscribe to SDAM events for a single client +by using the ``sdam-proc`` client option: .. literalinclude:: /includes/monitoring/monitoring.rb :start-after: start-sdam-subscriber-client @@ -163,7 +124,8 @@ To subscribe to SDAM events for a single client by using the ``sdam-proc`` clien :copyable: :dedent: -Sample output: +When you run the application, your subscriber records the SDAM event and +outputs messages such as the following: .. code-block:: none @@ -195,24 +157,50 @@ Sample output: a default set of event subscribers. If this happens, the provided ``:sdam_proc`` is not called and the application may miss events. -Event Descriptions ------------------- +Server Heartbeats +~~~~~~~~~~~~~~~~~ + +You can also create a custom subscriber to monitor server heartbeats. + +Custom server heartbeat subscribers differ from other SDAM subscribers, +as they must implement the following three methods: + +- ``started``: Invoked when the listener receives the heartbeat +- ``succeeded``: Response for a successful heartbeat outcome +- ``failed``: Response for a failed heartbeat outcome + +The following code is an example logging heartbeat event subscriber: + +.. literalinclude:: /includes/monitoring/monitoring.rb + :start-after: start-heartbeat + :end-before: end-heartbeat + :language: ruby + :copyable: + :dedent: + +You can subscribe to heartbeat events globally or for a specific client: -.. figure out what to do with this +.. literalinclude:: /includes/monitoring/monitoring.rb + :start-after: start-heartbeat-subscribe + :end-before: end-heartbeat-subscribe + :language: ruby + :copyable: + :dedent: + +When you run the application, your subscriber records the heartbeat event and +outputs messages such as the following: -The Ruby driver implements `Server Discovery And Monitoring (SDAM) specification -`_. -and makes the following events available to the application: +.. code-block:: none -- Topology opening -- Server opening -- Server description changed -- Topology changed -- Server closed -- Topology closed -- Heartbeat events (covered below in a separate section) + D, [2018-09-23T13:44:10.707018 #1739] DEBUG -- : HEARTBEAT | 127.0.0.1:27027 | STARTED + D, [2018-09-23T13:44:10.707778 #1739] DEBUG -- : HEARTBEAT | 127.0.0.1:27027 | SUCCEEDED | 0.000772381s -You can monitor the following SDAM events: +.. _SDAM-event-descriptions: + +Event Descriptions +------------------ + +The following table provides the name and description of each SDAM event: .. list-table:: :header-rows: 1 @@ -222,7 +210,7 @@ You can monitor the following SDAM events: - Description * - `ServerClosed <{+api-root+}/Mongo/Monitoring/Event/ServerClosed.html>`__ - - Event fired when the server is closed. + - Event fired when the server instance is closed. * - `ServerDescriptionChanged <{+api-root+}/Mongo/Monitoring/Event/ServerDescriptionChanged.html>`__ - Event fired when a server's description changes. @@ -231,10 +219,10 @@ You can monitor the following SDAM events: - Event fired when a server heartbeat fails. * - `ServerHeartbeatStarted <{+api-root+}/Mongo/Monitoring/Event/ServerHeartbeatStarted.html>`__ - - Event fired when a server heartbeat is dispatched. + - Event fired when a server heartbeat is received by the listener. * - `ServerHeartbeatSucceeded <{+api-root+}/Mongo/Monitoring/Event/ServerHeartbeatSucceeded.html>`__ - - Event fired when a server heartbeat successfully returns. + - Event fired when a server heartbeat succeeds. * - `ServerOpening <{+api-root+}/Mongo/Monitoring/Event/ServerOpening.html>`__ - Event fired when the driver connects to the server. @@ -251,8 +239,9 @@ You can monitor the following SDAM events: API Documentation ----------------- -To learn more about any of the methods discussed in this guide, see the following API documentation: +To learn more about any of the classes or methods discussed in this guide, see the +following API documentation: +- `Mongo::Monitoring <{+api-root+}/Mongo/Monitoring.html>`__ - `Mongo::Monitoring::Event <{+api-root+}/Mongo/Monitoring/Event.html>`__ - -.. event descriptions table, reread for active voice, api doc section, remove unnecessary code +- `subscribe <{+api-root+}/Mongo/Monitoring/Subscribable.html#subscribe-instance_method>`__ From 67cb01f2a40bf52b18a0fe6b5ececbdd7a7595dc Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Thu, 23 Jan 2025 13:32:26 -0500 Subject: [PATCH 06/10] final few changes --- source/includes/monitoring/monitoring.rb | 4 ++-- source/monitoring/cluster-monitoring.txt | 16 +++++++++------- 2 files changed, 11 insertions(+), 9 deletions(-) diff --git a/source/includes/monitoring/monitoring.rb b/source/includes/monitoring/monitoring.rb index 0193fe6a..4aa17dc6 100644 --- a/source/includes/monitoring/monitoring.rb +++ b/source/includes/monitoring/monitoring.rb @@ -1,11 +1,11 @@ # start-available-subscriber subscriber = Mongo::Monitoring::ServerOpeningLogSubscriber.new -# Globally subscribes to Server Opening events +# Globally subscribes to ServerOpening events by using the SERVER_OPENING monitoring topic Mongo::Monitoring::Global.subscribe(Mongo::Monitoring::SERVER_OPENING, subscriber) client = Mongo::Client.new(['127.0.0.1:27017']) -# Subscribes to Server Opening events at the client level +# Subscribes to ServerOpening events at the client level by using the SERVER_OPENING monitoring topic client.subscribe( Mongo::Monitoring::SERVER_OPENING, subscriber ) # end-available-subscriber diff --git a/source/monitoring/cluster-monitoring.txt b/source/monitoring/cluster-monitoring.txt index 395b6531..913eb25a 100644 --- a/source/monitoring/cluster-monitoring.txt +++ b/source/monitoring/cluster-monitoring.txt @@ -50,7 +50,7 @@ The following table provides available subscribers and their monitoring ``topic` .. list-table:: :header-rows: 1 - :widths: 20 20 60 + :widths: 35 20 45 * - Method Name - Monitoring Topic @@ -90,7 +90,7 @@ section on this page. Custom SDAM Monitoring ---------------------- -You can create a custom command subscriber to access details about server +You can create a custom SDAM subscriber to access details about server and topology events. Create a separate class for each event type, as available data for each event varies. @@ -105,7 +105,9 @@ like the following: :copyable: :dedent: -The following code shows how to subscribe to SDAM events globally: +To subscribe to events, you need to create the appropriate subscriber and +subscribe to the correct monitoring ``topic``. The following code shows how +to subscribe to SDAM events globally: .. literalinclude:: /includes/monitoring/monitoring.rb :start-after: start-sdam-subscriber-global @@ -151,11 +153,11 @@ outputs messages such as the following: .. note:: - ``:sdam_proc`` client option applies only to the client during whose - construction it is given. When certain client options are changed via the + The ``:sdam_proc`` client option applies only to the given client. + When certain client options are changed via the ``Client#with`` call, a new cluster may be created by the driver with a default set of event subscribers. If this happens, the provided - ``:sdam_proc`` is not called and the application may miss events. + ``:sdam_proc`` is not called, and the application may miss events. Server Heartbeats ~~~~~~~~~~~~~~~~~ @@ -169,7 +171,7 @@ as they must implement the following three methods: - ``succeeded``: Response for a successful heartbeat outcome - ``failed``: Response for a failed heartbeat outcome -The following code is an example logging heartbeat event subscriber: +The following code is an example heartbeat event subscriber: .. literalinclude:: /includes/monitoring/monitoring.rb :start-after: start-heartbeat From c59755a68c63d87a83699d486eb3495fe0bba68f Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Mon, 27 Jan 2025 16:12:27 -0500 Subject: [PATCH 07/10] NR review comments --- source/monitoring/cluster-monitoring.txt | 42 +++++++++++++----------- 1 file changed, 23 insertions(+), 19 deletions(-) diff --git a/source/monitoring/cluster-monitoring.txt b/source/monitoring/cluster-monitoring.txt index 913eb25a..157ade04 100644 --- a/source/monitoring/cluster-monitoring.txt +++ b/source/monitoring/cluster-monitoring.txt @@ -33,11 +33,12 @@ SDAM Subscribers ---------------- You can use the {+driver-short+}'s ``subscribe`` method to subscribe to events. -The ``subscribe`` method requires you to specify a monitoring ``topic`` -(the monitored event type) and a subscriber object. +Pass a monitoring topic, which defines the monitoring event type, and a subscriber +object as arguments to the ``subscribe`` method. The following code uses the ``ServerOpeningLogSubscriber`` to monitor a connection -to a server instance. You can subscribe to events at a global or client level: +to a server instance. You can subscribe to events at a global level, for all the clients +of a cluster, or at the client level: .. literalinclude:: /includes/monitoring/monitoring.rb :start-after: start-available-subscriber @@ -94,8 +95,8 @@ You can create a custom SDAM subscriber to access details about server and topology events. Create a separate class for each event type, as available data for each event varies. -For all events, the ``succeeded`` method is called on each event subscriber with -the event as the sole argument. A simple SDAM logging subscriber can look +For all events, the subscriber calls the ``succeeded`` method and passes the event +as an argument. A simple SDAM logging subscriber can look like the following: .. literalinclude:: /includes/monitoring/monitoring.rb @@ -105,8 +106,8 @@ like the following: :copyable: :dedent: -To subscribe to events, you need to create the appropriate subscriber and -subscribe to the correct monitoring ``topic``. The following code shows how +To subscribe to events, create the appropriate subscriber and +subscribe to the correct monitoring topic. The following code shows how to subscribe to SDAM events globally: .. literalinclude:: /includes/monitoring/monitoring.rb @@ -130,6 +131,7 @@ When you run the application, your subscriber records the SDAM event and outputs messages such as the following: .. code-block:: none + :copyable: false D, [2018-10-09T13:58:03.489461 #22079] DEBUG -- : SDAM | Topology type 'Unknown' initializing. D, [2018-10-09T13:58:03.489699 #22079] DEBUG -- : SDAM | Server 127.0.0.1:27100 initializing. @@ -154,7 +156,7 @@ outputs messages such as the following: .. note:: The ``:sdam_proc`` client option applies only to the given client. - When certain client options are changed via the + When certain client options are changed by using the ``Client#with`` call, a new cluster may be created by the driver with a default set of event subscribers. If this happens, the provided ``:sdam_proc`` is not called, and the application may miss events. @@ -171,7 +173,7 @@ as they must implement the following three methods: - ``succeeded``: Response for a successful heartbeat outcome - ``failed``: Response for a failed heartbeat outcome -The following code is an example heartbeat event subscriber: +The following example shows a heartbeat event subscriber: .. literalinclude:: /includes/monitoring/monitoring.rb :start-after: start-heartbeat @@ -180,7 +182,8 @@ The following code is an example heartbeat event subscriber: :copyable: :dedent: -You can subscribe to heartbeat events globally or for a specific client: +You can subscribe to heartbeat events globally or for a specific client, +as shown in the following example: .. literalinclude:: /includes/monitoring/monitoring.rb :start-after: start-heartbeat-subscribe @@ -193,6 +196,7 @@ When you run the application, your subscriber records the heartbeat event and outputs messages such as the following: .. code-block:: none + :copyable: false D, [2018-09-23T13:44:10.707018 #1739] DEBUG -- : HEARTBEAT | 127.0.0.1:27027 | STARTED D, [2018-09-23T13:44:10.707778 #1739] DEBUG -- : HEARTBEAT | 127.0.0.1:27027 | SUCCEEDED | 0.000772381s @@ -212,31 +216,31 @@ The following table provides the name and description of each SDAM event: - Description * - `ServerClosed <{+api-root+}/Mongo/Monitoring/Event/ServerClosed.html>`__ - - Event fired when the server instance is closed. + - Event created when the server instance is closed. * - `ServerDescriptionChanged <{+api-root+}/Mongo/Monitoring/Event/ServerDescriptionChanged.html>`__ - - Event fired when a server's description changes. + - Event created when a server's description changes. * - `ServerHeartbeatFailed <{+api-root+}/Mongo/Monitoring/Event/ServerHeartbeatFailed.html>`__ - - Event fired when a server heartbeat fails. + - Event created when a server heartbeat fails. * - `ServerHeartbeatStarted <{+api-root+}/Mongo/Monitoring/Event/ServerHeartbeatStarted.html>`__ - - Event fired when a server heartbeat is received by the listener. + - Event created when a server heartbeat is received by the listener. * - `ServerHeartbeatSucceeded <{+api-root+}/Mongo/Monitoring/Event/ServerHeartbeatSucceeded.html>`__ - - Event fired when a server heartbeat succeeds. + - Event created when a server heartbeat succeeds. * - `ServerOpening <{+api-root+}/Mongo/Monitoring/Event/ServerOpening.html>`__ - - Event fired when the driver connects to the server. + - Event created when the driver connects to the server. * - `TopologyChanged <{+api-root+}/Mongo/Monitoring/Event/TopologyChanged.html>`__ - - Event fired when the topology changes. + - Event created when the topology changes. * - `TopologyClosed <{+api-root+}/Mongo/Monitoring/Event/TopologyClosed.html>`__ - - Event fired when all instance connections in the topology close. + - Event created when all instance connections in the topology close. * - `TopologyOpening <{+api-root+}/Mongo/Monitoring/Event/TopologyOpening.html>`__ - - Event fired before the driver attempts to connect to an instance. + - Event created before the driver attempts to connect to an instance. API Documentation ----------------- From c4158cdd5ff283fe581837aba9caf9b07b477b6b Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Tue, 28 Jan 2025 12:04:43 -0500 Subject: [PATCH 08/10] NR comments --- source/monitoring/cluster-monitoring.txt | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/source/monitoring/cluster-monitoring.txt b/source/monitoring/cluster-monitoring.txt index 157ade04..625d7983 100644 --- a/source/monitoring/cluster-monitoring.txt +++ b/source/monitoring/cluster-monitoring.txt @@ -21,7 +21,7 @@ Overview -------- This guide shows you how to use the {+driver-short+} to monitor server discovery -and monitoring (SDAM) events events in a MongoDB instance, replica set, or sharded +and monitoring (SDAM) events in a MongoDB instance, replica set, or sharded cluster by using custom subscribers or available subscriber methods. These events occur when there are any changes in the state of the MongoDB instance or cluster that you are connected to. @@ -36,9 +36,9 @@ You can use the {+driver-short+}'s ``subscribe`` method to subscribe to events. Pass a monitoring topic, which defines the monitoring event type, and a subscriber object as arguments to the ``subscribe`` method. -The following code uses the ``ServerOpeningLogSubscriber`` to monitor a connection -to a server instance. You can subscribe to events at a global level, for all the clients -of a cluster, or at the client level: +The following code uses the ``ServerOpeningLogSubscriber`` subscriber to monitor a connection +to a server instance. You can subscribe to events at a global level, which monitors +all clients of a cluster, or at the client level: .. literalinclude:: /includes/monitoring/monitoring.rb :start-after: start-available-subscriber @@ -47,13 +47,13 @@ of a cluster, or at the client level: :copyable: :dedent: -The following table provides available subscribers and their monitoring ``topic``: +The following table provides available subscribers and their monitoring topic: .. list-table:: :header-rows: 1 :widths: 35 20 45 - * - Method Name + * - Subscriber Name - Monitoring Topic - Description @@ -97,7 +97,7 @@ data for each event varies. For all events, the subscriber calls the ``succeeded`` method and passes the event as an argument. A simple SDAM logging subscriber can look -like the following: +like the following code: .. literalinclude:: /includes/monitoring/monitoring.rb :start-after: start-sdam @@ -157,14 +157,15 @@ outputs messages such as the following: The ``:sdam_proc`` client option applies only to the given client. When certain client options are changed by using the - ``Client#with`` call, a new cluster may be created by the driver with + ``Client#with`` call, the driver may create a new cluster with a default set of event subscribers. If this happens, the provided ``:sdam_proc`` is not called, and the application may miss events. Server Heartbeats ~~~~~~~~~~~~~~~~~ -You can also create a custom subscriber to monitor server heartbeats. +You can also create a custom subscriber to monitor server heartbeats, which occur +when the server monitor sends a ``hello`` command to the server. Custom server heartbeat subscribers differ from other SDAM subscribers, as they must implement the following three methods: From 7ca895b9a13482abcf9495a608df45db3f07a16c Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Tue, 28 Jan 2025 12:10:53 -0500 Subject: [PATCH 09/10] look through --- source/monitoring/cluster-monitoring.txt | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/source/monitoring/cluster-monitoring.txt b/source/monitoring/cluster-monitoring.txt index 625d7983..da979913 100644 --- a/source/monitoring/cluster-monitoring.txt +++ b/source/monitoring/cluster-monitoring.txt @@ -23,7 +23,7 @@ Overview This guide shows you how to use the {+driver-short+} to monitor server discovery and monitoring (SDAM) events in a MongoDB instance, replica set, or sharded cluster by using custom subscribers or available subscriber methods. These events -occur when there are any changes in the state of the MongoDB instance or cluster +occur when there are changes in the state of the MongoDB instance or cluster that you are connected to. You can use information about SDAM events in your application to understand @@ -127,6 +127,14 @@ by using the ``sdam-proc`` client option: :copyable: :dedent: +.. note:: + + The ``:sdam_proc`` client option applies only to the given client. + When certain client options are changed by using the + ``Client#with`` call, the driver may create a new cluster with + a default set of event subscribers. If this happens, the provided + ``:sdam_proc`` is not called, and the application may miss events. + When you run the application, your subscriber records the SDAM event and outputs messages such as the following: @@ -153,14 +161,6 @@ outputs messages such as the following: D, [2018-10-09T13:58:05.342565 #22079] DEBUG -- : SDAM | Server localhost:27102 connection closed. D, [2018-10-09T13:58:05.342693 #22079] DEBUG -- : SDAM | Topology type 'ReplicaSetWithPrimary' closed. -.. note:: - - The ``:sdam_proc`` client option applies only to the given client. - When certain client options are changed by using the - ``Client#with`` call, the driver may create a new cluster with - a default set of event subscribers. If this happens, the provided - ``:sdam_proc`` is not called, and the application may miss events. - Server Heartbeats ~~~~~~~~~~~~~~~~~ From 263143fa15bfceb8f685e7a056f6ea8a34251f76 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 29 Jan 2025 15:02:14 -0500 Subject: [PATCH 10/10] tech review comments --- source/includes/monitoring/monitoring.rb | 172 +++++++++++------------ source/monitoring/cluster-monitoring.txt | 4 - 2 files changed, 86 insertions(+), 90 deletions(-) diff --git a/source/includes/monitoring/monitoring.rb b/source/includes/monitoring/monitoring.rb index 4aa17dc6..444b11e0 100644 --- a/source/includes/monitoring/monitoring.rb +++ b/source/includes/monitoring/monitoring.rb @@ -11,77 +11,77 @@ # start-sdam class SDAMLogSubscriber - include Mongo::Loggable - - def succeeded(event) - log_debug(format_event(event)) - end - - private - - def logger - Mongo::Logger.logger - end - - def format_message(message) - format("SDAM | %s".freeze, message) - end + include Mongo::Loggable + + def succeeded(event) + log_debug(format_event(event)) end - - class TopologyOpeningLogSubscriber < SDAMLogSubscriber - private - - def format_event(event) - "Topology type '#{event.topology.display_name}' initializing." - end + + private + + def logger + Mongo::Logger.logger end - - class ServerOpeningLogSubscriber < SDAMLogSubscriber - private - - def format_event(event) - "Server #{event.address} initializing." - end + + def format_message(message) + format("SDAM | %s", message) end +end - class ServerDescriptionChangedLogSubscriber < SDAMLogSubscriber - private - - def format_event(event) - "Server description for #{event.address} changed from " + - "'#{event.previous_description.server_type}' to '#{event.new_description.server_type}'." - end +class TopologyOpeningLogSubscriber < SDAMLogSubscriber + private + + def format_event(event) + "Topology type '#{event.topology.display_name}' initializing." end - - class TopologyChangedLogSubscriber < SDAMLogSubscriber - private - - def format_event(event) - if event.previous_topology != event.new_topology - "Topology type '#{event.previous_topology.display_name}' changed to " + - "type '#{event.new_topology.display_name}'." - else - "There was a change in the members of the '#{event.new_topology.display_name}' " + - "topology." - end - end +end + +class ServerOpeningLogSubscriber < SDAMLogSubscriber + private + + def format_event(event) + "Server #{event.address} initializing." end - - class ServerClosedLogSubscriber < SDAMLogSubscriber - private - - def format_event(event) - "Server #{event.address} connection closed." - end +end + +class ServerDescriptionChangedLogSubscriber < SDAMLogSubscriber + private + + def format_event(event) + "Server description for #{event.address} changed from " + + "'#{event.previous_description.server_type}' to '#{event.new_description.server_type}'." end - - class TopologyClosedLogSubscriber < SDAMLogSubscriber - private - - def format_event(event) - "Topology type '#{event.topology.display_name}' closed." +end + +class TopologyChangedLogSubscriber < SDAMLogSubscriber + private + + def format_event(event) + if event.previous_topology != event.new_topology + "Topology type '#{event.previous_topology.display_name}' changed to " + + "type '#{event.new_topology.display_name}'." + else + "There was a change in the members of the '#{event.new_topology.display_name}' " + + "topology." end end +end + +class ServerClosedLogSubscriber < SDAMLogSubscriber + private + + def format_event(event) + "Server #{event.address} connection closed." + end +end + +class TopologyClosedLogSubscriber < SDAMLogSubscriber + private + + def format_event(event) + "Topology type '#{event.topology.display_name}' closed." + end +end #end-sdam # start-sdam-subscriber-global @@ -135,30 +135,30 @@ def format_event(event) # start-heartbeat class HeartbeatLogSubscriber - include Mongo::Loggable - - def started(event) - log_debug("#{event.address} | STARTED") - end - - def succeeded(event) - log_debug("#{event.address} | SUCCEEDED | #{event.duration}s") - end - - def failed(event) - log_debug("#{event.address} | FAILED | #{event.error.class}: #{event.error.message} | #{event.duration}s") - end - - private - - def logger - Mongo::Logger.logger - end - - def format_message(message) - format("HEARTBEAT | %s".freeze, message) - end + include Mongo::Loggable + + def started(event) + log_debug("#{event.address} | STARTED") + end + + def succeeded(event) + log_debug("#{event.address} | SUCCEEDED | #{event.duration}s") end + + def failed(event) + log_debug("#{event.address} | FAILED | #{event.error.class}: #{event.error.message} | #{event.duration}s") + end + + private + + def logger + Mongo::Logger.logger + end + + def format_message(message) + format("HEARTBEAT | %s", message) + end +end # end-heartbeat # start-heartbeat-subscribe @@ -168,6 +168,6 @@ def format_message(message) Mongo::Monitoring::Global.subscribe(Mongo::Monitoring::SERVER_HEARTBEAT, subscriber) # Subscribes to Server Opening events at the client level -client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'test' ) +client = Mongo::Client.new([ '127.0.0.1:27017' ], database: 'test' ) client.subscribe( Mongo::Monitoring::SERVER_HEARTBEAT, subscriber ) # end-heartbeat-subscribe diff --git a/source/monitoring/cluster-monitoring.txt b/source/monitoring/cluster-monitoring.txt index da979913..41b16d7a 100644 --- a/source/monitoring/cluster-monitoring.txt +++ b/source/monitoring/cluster-monitoring.txt @@ -57,10 +57,6 @@ The following table provides available subscribers and their monitoring topic: - Monitoring Topic - Description - * - `SDAMLogSubscriber <{+api-root+}/Mongo/Monitoring/SDAMLogSubscriber.html>`__ - - - - Subscribes to SDAM events and logs them. - * - `ServerClosedLogSubscriber <{+api-root+}/Mongo/Monitoring/ServerClosedLogSubscriber.html>`__ - ``SERVER_CLOSED`` - Subscribes to ``ServerClosed`` events and logs them.