DOCSP-41982: cluster monitoring

source/includes/monitoring/sdam.php

@@ -6,19 +6,21 @@
 class MySubscriber implements MongoDB\Driver\Monitoring\SDAMSubscriber
 {
     private $stream;
+
     public function __construct($stream)
     {
         $this->stream = $stream;
     }
-    public function serverOpening(MongoDB\Driver\Monitoring\ServerOpeningEvent $event): void
-    {
-        fwrite($this->stream, sprintf(
-            'Server opening on %s:%s%s',
+
+    public function serverOpening(MongoDB\Driver\Monitoring\ServerOpeningEvent $event): void {
+        fprintf(
+            $this->stream,
+            'Server opening on %s:%s\n',
             $event->getHost(),
             $event->getPort(),
-            PHP_EOL,
-        ));
+        );
     }
+
     public function serverClosed(MongoDB\Driver\Monitoring\ServerClosedEvent $event): void {}
     public function serverChanged(MongoDB\Driver\Monitoring\ServerChangedEvent $event): void {}
     public function serverHeartbeatFailed(MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent $event): void {}
@@ -30,15 +32,18 @@ public function topologyOpening(MongoDB\Driver\Monitoring\TopologyOpeningEvent $
 }
 // end-mysubscriber
 
-$uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your Atlas URI that connects to the sample dataset');
+$uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your connection URI');
 $client = new MongoDB\Client($uri);
 
-$database = $client->db;
-$collection = $database->my_coll;
+$collection = $client->db->my_coll;
 
 // start-add-sub
 $subscriber = new MySubscriber(STDERR);
 $client->addSubscriber($subscriber);
 // end-add-sub
 
 $collection->insertOne(['x' => 100]);
+
+// start-remove-sub
+$client->removeSubscriber($subscriber);
+// end-remove-sub

source/monitoring/cluster-monitoring.txt

@@ -20,15 +20,17 @@ Cluster Monitoring
 Overview
 --------
 
-This guide shows you how to use the {+php-library+} to monitor topology
-events in a MongoDB instance, replica set, or sharded cluster. The
-driver creates topology events, also known as Server Discovery and
-Monitoring (SDAM) events, when there are any changes in the state of the
-MongoDB instance or cluster that you are connected to.
+This guide shows you how to use the {+php-library+} to monitor server
+discovery and monitoring (SDAM) events in a MongoDB instance, replica
+set, or sharded cluster. These events occur when there
+are any changes in the state of the MongoDB instance or cluster that you
+are connected to.
 
-You might use information about topology events in your
-application to understand cluster changes, assess cluster health, or
-perform capacity planning.
+You might use information about SDAM events in your application to
+understand cluster changes, assess cluster health, or perform capacity
+planning.
+
+.. _php-subscribe-sdam:
 
 Subscribe to Events
 -------------------
@@ -53,10 +55,10 @@ server:
 
 .. note::
 
-   As shown in the preceding code, you must implement all of the methods
+   As shown in the preceding code, you must implement all the methods
    of the ``SDAMSubscriber`` interface, even for events you are not subscribing to.
-   You can implement these methods with empty bodies so that the library
-   does not generate any messages for these events.
+   The example defines the extra methods as empty so that the
+   application does not output any messages for those events.
 
 Then, use the ``addSubscriber()`` method to register ``MySubscriber``
 with the client, as shown in the following code:
@@ -81,53 +83,79 @@ outputs messages such as the following:
 Event Descriptions
 ------------------
 
-You can subscribe to the following SDAM events by implementing the
-corresponding method from the ``SDAMSubscriber`` interface:
+You can subscribe to SDAM events by implementing the corresponding
+method from the ``SDAMSubscriber`` interface. The following table
+provides the name of each SDAM event, linked to the class's API
+documentation, and a description of when the event is published:
 
 .. list-table::
    :widths: 35 65 
    :header-rows: 1
 
-   * - Event Name
+   * - Event Type
      - Description
 
-   * - ``ServerChangedEvent``
-     - Created when an instance state changes, such as from secondary to
-       primary.
+   * - :php:`ServerChangedEvent <mongodb-driver-monitoring-serverchangedevent>`
+     - Created when the server description changes, such as the server's type
+       changing from secondary to primary.
 
-   * - ``ServerOpeningEvent``
-     - Created when the server is initialized.
+   * - :php:`ServerOpeningEvent <mongodb-driver-monitoring-serveropeningevent>`
+     - Created when the server description is instantiated with its
+       defaults.
 
-   * - ``ServerClosedEvent``
+   * - :php:`ServerClosedEvent <mongodb-driver-monitoring-serverclosedevent>`
      - Created when the server is closed.
 
-   * - ``TopologyChangedEvent``
-     - Created when the topology changes, such as an election of a new
-       primary or disconnection of a ``mongos`` proxy.
+   * - :php:`TopologyChangedEvent <mongodb-driver-monitoring-topologychangedevent>`
+     - Created when the topology description changes, such when there is
+       an election of a new primary or disconnection of a ``mongos`` proxy.
 
-   * - ``TopologyOpeningEvent``
-     - Created when the topology is initialized.
+   * - :php:`TopologyOpeningEvent <mongodb-driver-monitoring-topologyopeningevent>`
+     - Created when the topology description is initialized.
 
-   * - ``TopologyClosedEvent``
+   * - :php:`TopologyClosedEvent <mongodb-driver-monitoring-topologyclosedevent>`
      - Created when the topology is closed.
 
-   * - ``ServerHeartbeatStartedEvent``
-     - Created when the heartbeat is started.
+   * - :php:`ServerHeartbeatStartedEvent <mongodb-driver-monitoring-serverheartbeatstartedevent>`
+     - Created when the server monitor sends a ``hello`` call to the server.
+       This action is called a heartbeat.
 
-   * - ``ServerHeartbeatSucceededEvent``
+   * - :php:`ServerHeartbeatSucceededEvent <mongodb-driver-monitoring-serverheartbeatsucceededevent>`
      - Created when the heartbeat succeeds.
 
-   * - ``ServerHeartbeatFailedEvent``
+   * - :php:`ServerHeartbeatFailedEvent <mongodb-driver-monitoring-serverheartbeatfailedevent>`
      - Created when the heartbeat fails.
 
+You can find a list of the monitoring subscriber classes and event
+methods in the :php:`Monitoring classes and subscriber functions
+<mongodb.monitoring>` section of the PHP manual.
+
+Remove a Subscriber
+-------------------
+
+Later in your application, you might not want to subscribe to
+SDAM events. To unregister a subscriber from your client, use the
+``MongoDB\Client::removeSubscriber()`` method. If you attempt to remove
+a nonexistent subscriber, the method doesn't perform any action.
+
+The following code shows how to remove the subscriber that you
+registered in the :ref:`php-subscribe-sdam` section:
+
+.. literalinclude:: /includes/monitoring/sdam.php
+   :start-after: start-remove-sub
+   :end-before: end-remove-sub
+   :language: php
+   :copyable:
+   :dedent:
+
 API Documentation
 -----------------
 
 To learn more about any of the classes or methods discussed in this guide, see the
 following API documentation:
 
 - :phpmethod:`MongoDB\Client::addSubscriber()`
-- :phpclass:`MongoDB\Client`
+- :phpmethod:`MongoDB\Client::removeSubscriber()`
 
 To learn more about subscriber classes and methods, see the following
 pages in the PHP manual: