DOCSP-41982: cluster monitoring

source/includes/monitoring/sdam.php

@@ -0,0 +1,49 @@
+<?php
+
+require __DIR__ . '/vendor/autoload.php';
+
+// start-mysubscriber
+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 {
+        fprintf(
+            $this->stream,
+            'Server opening on %s:%s\n',
+            $event->getHost(),
+            $event->getPort(),
+        );
+    }
+
+    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 {}
+    public function serverHeartbeatStarted(MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent $event): void {}
+    public function serverHeartbeatSucceeded(MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent $event): void {}
+    public function topologyChanged(MongoDB\Driver\Monitoring\TopologyChangedEvent $event): void {}
+    public function topologyClosed(MongoDB\Driver\Monitoring\TopologyClosedEvent $event): void {}
+    public function topologyOpening(MongoDB\Driver\Monitoring\TopologyOpeningEvent $event): void {}
+}
+// end-mysubscriber
+
+$uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your connection URI');
+$client = new MongoDB\Client($uri);
+
+$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/index.txt

@@ -16,6 +16,7 @@ MongoDB PHP Library
    /write
    /aggregation
    /indexes
+   /monitoring
    /security
    /tutorial
    /upgrade

source/monitoring.txt

@@ -0,0 +1,21 @@
+.. _php-monitoring:
+
+========================
+Monitor Your Application
+========================
+
+.. toctree::
+   :caption: Monitoring categories
+
+   /monitoring/cluster-monitoring
+
+.. /monitoring/command-monitoring
+.. /monitoring/connection-monitoring
+
+- :ref:`Cluster Monitoring <php-cluster-monitoring>`: Monitor changes
+  in your cluster configuration
+
+.. TODO - :ref:`Command Monitoring <php-command-monitoring>`: monitor command
+..   execution
+.. - :ref:`Connection Pool Monitoring <php-connection-monitoring>`:
+..   monitor changes in the connection pool

source/monitoring/cluster-monitoring.txt

@@ -0,0 +1,164 @@
+.. _php-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
+--------
+
+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 SDAM events in your application to
+understand cluster changes, assess cluster health, or perform capacity
+planning.
+
+.. _php-subscribe-sdam:
+
+Subscribe to Events
+-------------------
+
+You can access details about SDAM events by subscribing to them
+in your application. To subscribe to an event, create a class that
+implements the ``MongoDB\Driver\Monitoring\SDAMSubscriber`` interface,
+then use the ``MongoDB\Client::addSubscriber()`` method to register the
+event subscriber with your ``MongoDB\Client`` instance.
+
+The following code creates the ``MySubscriber`` class, which implements
+the ``SDAMSubscriber`` interface. The class is defined with a method to
+output a message when a ``ServerOpeningEvent`` is generated by the
+server:
+
+.. literalinclude:: /includes/monitoring/sdam.php
+   :start-after: start-mysubscriber
+   :end-before: end-mysubscriber
+   :language: php
+   :copyable:
+   :dedent:
+
+.. note::
+
+   As shown in the preceding code, you must implement all the methods
+   of the ``SDAMSubscriber`` interface, even for events you are not subscribing to.
+   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:
+
+.. literalinclude:: /includes/monitoring/sdam.php
+   :start-after: start-add-sub
+   :end-before: end-add-sub
+   :language: php
+   :copyable:
+   :dedent:
+
+When you run the application, your subscriber records the SDAM event and
+outputs messages such as the following:
+
+.. code-block:: none
+   :copyable: false
+
+   Server opening on ac-rmuag0v-shard-00-00.gh0qg50.mongodb.net:27017
+   Server opening on ac-rmuag0v-shard-00-01.gh0qg50.mongodb.net:27017
+   Server opening on ac-rmuag0v-shard-00-02.gh0qg50.mongodb.net:27017
+
+Event Descriptions
+------------------
+
+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 Type
+     - Description
+
+   * - :php:`ServerChangedEvent <mongodb-driver-monitoring-serverchangedevent>`
+     - Created when the server description changes, such as the server's type
+       changing from secondary to primary.
+
+   * - :php:`ServerOpeningEvent <mongodb-driver-monitoring-serveropeningevent>`
+     - Created when the server description is instantiated with its
+       defaults.
+
+   * - :php:`ServerClosedEvent <mongodb-driver-monitoring-serverclosedevent>`
+     - Created when the server is closed.
+
+   * - :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.
+
+   * - :php:`TopologyOpeningEvent <mongodb-driver-monitoring-topologyopeningevent>`
+     - Created when the topology description is initialized.
+
+   * - :php:`TopologyClosedEvent <mongodb-driver-monitoring-topologyclosedevent>`
+     - Created when the topology is closed.
+
+   * - :php:`ServerHeartbeatStartedEvent <mongodb-driver-monitoring-serverheartbeatstartedevent>`
+     - Created when the server monitor sends a ``hello`` call to the server.
+       This action is called a heartbeat.
+
+   * - :php:`ServerHeartbeatSucceededEvent <mongodb-driver-monitoring-serverheartbeatsucceededevent>`
+     - Created when the heartbeat succeeds.
+
+   * - :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()`
+- :phpmethod:`MongoDB\Client::removeSubscriber()`
+
+To learn more about subscriber classes and methods, see the following
+pages in the PHP manual:
+
+- :php:`MongoDB\Driver\Monitoring\SDAMSubscriber <mongodb-driver-monitoring-sdamsubscriber>`
+- :php:`MongoDB\Driver\Monitoring\ServerOpeningEvent <mongodb-driver-monitoring-serveropeningevent>`