DOCSP-41982: cluster monitoring

source/includes/monitoring/sdam.php

@@ -0,0 +1,44 @@
+<?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
+    {
+        fwrite($this->stream, sprintf(
+            'Server opening on %s:%s%s',
+            $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 {}
+    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 Atlas URI that connects to the sample dataset');
+$client = new MongoDB\Client($uri);
+
+$database = $client->db;
+$collection = $database->my_coll;
+
+// start-add-sub
+$subscriber = new MySubscriber(STDERR);
+$client->addSubscriber($subscriber);
+// end-add-sub
+
+$collection->insertOne(['x' => 100]);

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,136 @@
+.. _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 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.
+
+You might use information about topology events in your
+application to understand cluster changes, assess cluster health, or
+perform capacity planning.
+
+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 of 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.
+
+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 the following SDAM events by implementing the
+corresponding method from the ``SDAMSubscriber`` interface:
+
+.. list-table::
+   :widths: 35 65 
+   :header-rows: 1
+
+   * - Event Name
+     - Description
+
+   * - ``ServerChangedEvent``
+     - Created when an instance state changes, such as from secondary to
+       primary.
+
+   * - ``ServerOpeningEvent``
+     - Created when the server is initialized.
+
+   * - ``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.
+
+   * - ``TopologyOpeningEvent``
+     - Created when the topology is initialized.
+
+   * - ``TopologyClosedEvent``
+     - Created when the topology is closed.
+
+   * - ``ServerHeartbeatStartedEvent``
+     - Created when the heartbeat is started.
+
+   * - ``ServerHeartbeatSucceededEvent``
+     - Created when the heartbeat succeeds.
+
+   * - ``ServerHeartbeatFailedEvent``
+     - Created when the heartbeat fails.
+
+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`
+
+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>`