diff --git a/.github/workflows/check-autobuilder.yml b/.github/workflows/check-autobuilder.yml deleted file mode 100644 index 8495db96..00000000 --- a/.github/workflows/check-autobuilder.yml +++ /dev/null @@ -1,13 +0,0 @@ -name: Check Autobuilder for Errors - -on: - pull_request: - paths: - - "source/**" - -jobs: - check: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - uses: cbush/snooty-autobuilder-check@main diff --git a/source/includes/monitoring/sdam.php b/source/includes/monitoring/sdam.php new file mode 100644 index 00000000..1647f9d9 --- /dev/null +++ b/source/includes/monitoring/sdam.php @@ -0,0 +1,49 @@ +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 \ No newline at end of file diff --git a/source/index.txt b/source/index.txt index 95e744a0..042021d3 100644 --- a/source/index.txt +++ b/source/index.txt @@ -16,6 +16,7 @@ MongoDB PHP Library /write /aggregation /indexes + /monitoring /security /tutorial /upgrade diff --git a/source/monitoring.txt b/source/monitoring.txt new file mode 100644 index 00000000..5322004f --- /dev/null +++ b/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 `: Monitor changes + in your cluster configuration + +.. TODO - :ref:`Command Monitoring `: monitor command +.. execution +.. - :ref:`Connection Pool Monitoring `: +.. monitor changes in the connection pool \ 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..d9d9901e --- /dev/null +++ b/source/monitoring/cluster-monitoring.txt @@ -0,0 +1,163 @@ +.. _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 ` + - Created when the server description changes, such as the server's + type changing from secondary to primary. + + * - :php:`ServerOpeningEvent ` + - Created when a server connection is established. + + * - :php:`ServerClosedEvent ` + - Created when a server connection is closed. + + * - :php:`TopologyChangedEvent ` + - Created when the topology description changes, such as when there + is an election of a new primary. + + * - :php:`TopologyOpeningEvent ` + - Created when the driver first connects to the cluster. + + * - :php:`TopologyClosedEvent ` + - Created when the driver disconnects from the cluster. + + * - :php:`ServerHeartbeatStartedEvent ` + - Created when the server monitor sends a ``hello`` command to the server. + This action is called a heartbeat. + + * - :php:`ServerHeartbeatSucceededEvent ` + - Created when the heartbeat succeeds. + + * - :php:`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 +` 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 ` +- :php:`MongoDB\Driver\Monitoring\ServerOpeningEvent `