diff --git a/config/redirects b/config/redirects index 62e3c9df..3ca604de 100644 --- a/config/redirects +++ b/config/redirects @@ -25,7 +25,7 @@ raw: ${prefix}/stable -> ${base}/current/ # redirects in standardized docs [v1.20-*]: ${prefix}/${version}/tutorial/install-php-library/ -> ${base}/${version}/get-started/ [v1.20-*]: ${prefix}/${version}/tutorial/connecting/ -> ${base}/${version}/connect/ -[v1.20-*]: ${prefix}/${version}/tutorial/server-selection/ -> ${base}/${version}/monitoring/cluster-monitoring/ +[v1.20-*]: ${prefix}/${version}/tutorial/server-selection/ -> ${base}/${version}/monitoring-logging/monitoring/ [v1.20-*]: ${prefix}/${version}/tutorial/crud/ -> ${base}/${version}/read/ [v1.20-*]: ${prefix}/${version}/tutorial/codecs/ -> ${base}/${version}/data-formats/codecs/ [v1.20-*]: ${prefix}/${version}/tutorial/collation/ -> ${base}/${version}/ @@ -45,7 +45,7 @@ raw: ${prefix}/stable -> ${base}/current/ # note: this mapping does not account for all of the new pages [*-v1.19]: ${prefix}/${version}/tutorial/install-php-library/ -> ${base}/v1.x/get-started/ [*-v1.19]: ${prefix}/${version}/tutorial/connecting/ -> ${base}/v1.x/connect/ -[*-v1.19]: ${prefix}/${version}/tutorial/server-selection/ -> ${base}/v1.x/monitoring/cluster-monitoring/ +[*-v1.19]: ${prefix}/${version}/tutorial/server-selection/ -> ${base}/v1.x/monitoring-logging/monitoring/ [*-v1.19]: ${prefix}/${version}/tutorial/crud/ -> ${base}/v1.x/read/ [*-v1.19]: ${prefix}/${version}/tutorial/codecs/ -> ${base}/v1.x/data-formats/codecs/ [*-v1.19]: ${prefix}/${version}/tutorial/collation/ -> ${base}/v1.x/ @@ -84,7 +84,7 @@ raw: ${prefix}/stable -> ${base}/current/ [*-master]: ${prefix}/${version}/data-formats/codecs/ -> ${base}/${version}/data-formats/custom-types/codecs/ [*-master]: ${prefix}/${version}/databases-collections/time-series/ -> ${base}/${version}/data-formats/time-series/ [*-master]: ${prefix}/${version}/read/change-streams/ -> ${base}/${version}/monitoring-logging/change-streams/ -[*-master]: ${prefix}/${version}/monitoring/cluster-monitoring/ -> ${base}/${version}/monitoring-logging/cluster-monitoring/ +[*-master]: ${prefix}/${version}/monitoring/cluster-monitoring/ -> ${base}/${version}/monitoring-logging/monitoring/ [*-master]: ${prefix}/${version}/compatibility/ -> ${base}/${version}/references/compatibility/ [*-master]: ${prefix}/${version}/whats-new/ -> ${base}/${version}/references/release-notes/ [*-master]: ${prefix}/${version}/upgrade/ -> ${base}/${version}/references/upgrade/ diff --git a/source/includes/monitoring/sdam.php b/source/includes/monitoring/monitor.php similarity index 55% rename from source/includes/monitoring/sdam.php rename to source/includes/monitoring/monitor.php index 1647f9d9..d091edca 100644 --- a/source/includes/monitoring/sdam.php +++ b/source/includes/monitoring/monitor.php @@ -2,8 +2,34 @@ require __DIR__ . '/vendor/autoload.php'; -// start-mysubscriber -class MySubscriber implements MongoDB\Driver\Monitoring\SDAMSubscriber +// start-command-subscriber +class MyCommandSubscriber implements MongoDB\Driver\Monitoring\CommandSubscriber +{ + private $stream; + + public function __construct($stream) + { + $this->stream = $stream; + } + + public function commandStarted(MongoDB\Driver\Monitoring\CommandStartedEvent $event): void + { + fwrite($this->stream, sprintf( + 'Started command #%d "%s": %s%s', + $event->getRequestId(), + $event->getCommandName(), + MongoDB\BSON\Document::fromPHP($event->getCommand())->toCanonicalExtendedJSON(), + PHP_EOL, + )); + } + + public function commandSucceeded(MongoDB\Driver\Monitoring\CommandSucceededEvent $event): void {} + public function commandFailed(MongoDB\Driver\Monitoring\CommandFailedEvent $event): void {} +} +// end-command-subscriber + +// start-sdam-subscriber +class MySDAMSubscriber implements MongoDB\Driver\Monitoring\SDAMSubscriber { private $stream; @@ -18,6 +44,7 @@ public function serverOpening(MongoDB\Driver\Monitoring\ServerOpeningEvent $even 'Server opening on %s:%s\n', $event->getHost(), $event->getPort(), + PHP_EOL, ); } @@ -30,20 +57,23 @@ public function topologyChanged(MongoDB\Driver\Monitoring\TopologyChangedEvent $ public function topologyClosed(MongoDB\Driver\Monitoring\TopologyClosedEvent $event): void {} public function topologyOpening(MongoDB\Driver\Monitoring\TopologyOpeningEvent $event): void {} } -// end-mysubscriber +// end-sdam-subscriber $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 +// start-add-subs +$commandSub = new MyCommandSubscriber(STDERR); +$sdamSub = new MySDAMSubscriber(STDERR); + +$client->addSubscriber($commandSub); +$client->addSubscriber($sdamSub); +// end-add-subs $collection->insertOne(['x' => 100]); // start-remove-sub -$client->removeSubscriber($subscriber); +$client->removeSubscriber($commandSub); // end-remove-sub \ No newline at end of file diff --git a/source/monitoring-logging.txt b/source/monitoring-logging.txt index 5f5fc7b2..ff902d8a 100644 --- a/source/monitoring-logging.txt +++ b/source/monitoring-logging.txt @@ -8,11 +8,11 @@ Monitoring and Logging .. toctree:: :caption: Monitoring categories - Cluster Monitoring + Monitoring Change Streams .. /monitoring/command-monitoring .. /monitoring/connection-monitoring -- :ref:`Cluster Monitoring `: Monitor changes - in your cluster configuration \ No newline at end of file +- :ref:`Monitor Application Events `: Monitor changes + in your application \ No newline at end of file diff --git a/source/monitoring-logging/cluster-monitoring.txt b/source/monitoring-logging/cluster-monitoring.txt deleted file mode 100644 index 0093aa47..00000000 --- a/source/monitoring-logging/cluster-monitoring.txt +++ /dev/null @@ -1,163 +0,0 @@ -.. _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 new server is added to the topology. - - * - :php:`ServerClosedEvent ` - - Created when an existing server is removed from the topology. - - * - :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 ` diff --git a/source/monitoring-logging/monitoring.txt b/source/monitoring-logging/monitoring.txt new file mode 100644 index 00000000..3a3ade51 --- /dev/null +++ b/source/monitoring-logging/monitoring.txt @@ -0,0 +1,266 @@ +.. _php-cluster-monitoring: +.. _php-monitoring: + +========================== +Monitor Application Events +========================== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, server, topology + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecols + +Overview +-------- + +In this guide, you can learn how to set up and configure **monitoring** +in the {+php-library+}. + +Monitoring is the process of gathering information about your application's +behavior as it runs. This information can help you make informed decisions when +designing and debugging your application. You can also use information from monitoring +events to track your application's performance and resource use. + +The {+php-library+} emits command events and Server Discovery and Monitoring (SDAM) +events that provide application information. You can listen for these events to +monitor your application. + +.. TODO: This page explains how to monitor your application in code. To learn how to + record this information to an external log, see the :ref:`php-logging` guide. + +Event Types +----------- + +The type of event that the driver emits depends on the operation being performed. +The following table describes the types of events that the driver emits: + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Event Type + - Description + + * - Command events + - Events related to MongoDB database commands, such as ``find``, ``insert``, + ``delete``, and ``count``. To learn how to use the {+library-short+} to run a + database command, see :ref:``. For more information about + MongoDB database commands, see :manual:`Database Commands ` + in the {+mdb-server+} manual. + + * - Server Discovery and Monitoring (SDAM) events + - Events related to changes in the state of the MongoDB deployment. + +Monitor Events +-------------- + +To monitor events, you must perform the following actions: + +1. :ref:`php-subscribe`: Create a class that implements the command or + SDAM event subscriber +#. :ref:`php-register`: Register a monitoring event subscriber with your + ``MongoDB\Client`` + +.. tip:: + + To view a list of monitoring events to which you can subscribe, see the + :php:`Monitoring classes and subscriber functions ` + section of the PHP manual. + +.. _php-subscribe: + +Create an Event Subscriber +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To subscribe to a monitoring event, create a class that implements the +event subscriber interface. You can implement the following interfaces: + +- ``MongoDB\Driver\Monitoring\CommandSubscriber``, which subscribes to + command events +- ``MongoDB\Driver\Monitoring\SDAMSubscriber``, which subscribes to + SDAM events + +.. _php-subscribe-command: + +Command Event Subscriber Example +```````````````````````````````` + +To subscribe to an SDAM event, create a class that implements the +``MongoDB\Driver\Monitoring\CommandSubscriber`` interface. In your +class, define each of the ``CommandSubscriber`` methods. The following +table describes these methods and the command events they receive notifications +for: + +.. list-table:: + :header-rows: 1 + :widths: 30 20 50 + + * - Method + - Command Event + - Description + + * - :php:`commandFailed() ` + - :php:`CommandFailedEvent ` + - Called when a command does not succeed + + * - :php:`commandStarted() ` + - :php:`CommandStartedEvent ` + - Called when a command is sent to the server + + * - :php:`commandSucceeded() ` + - :php:`CommandSucceededEvent ` + - Called when a command succeeds + +The following code creates the ``MyCommandSubscriber`` class, which implements +the ``CommandSubscriber`` interface. The class defines each ``CommandSubscriber`` method +and includes custom logic for the ``commandStarted()`` method, which prints details +about each new command that the server receives: + +.. literalinclude:: /includes/monitoring/monitor.php + :start-after: start-command-subscriber + :end-before: end-command-subscriber + :language: php + :copyable: + :dedent: + +.. _php-subscribe-sdam: + +SDAM Event Subscriber Example +````````````````````````````` + +To subscribe to an SDAM event, create a class that implements the +``MongoDB\Driver\Monitoring\SDAMSubscriber`` interface. In your +class, define each ``SDAMSubscriber`` method. The following +table describes these methods and the command events they receive +notifications for: + +.. list-table:: + :header-rows: 1 + :widths: 30 20 50 + + * - Method + - SDAM Event + - Description + + * - :php:`serverChanged() ` + - :php:`ServerChangedEvent ` + - Called when a server's description changes + + * - :php:`serverClosed() ` + - :php:`ServerClosedEvent ` + - Called when a server is removed from the topology + + * - :php:`serverHeartbeatFailed() ` + - :php:`ServerHeartbeatFailedEvent ` + - Called when a server heartbeat is unsuccessful + + * - :php:`serverHeartbeatStarted() ` + - :php:`ServerHeartbeatStartedEvent ` + - Called when the server receives a heartbeat + + * - :php:`serverHeartbeatSucceeded() ` + - :php:`ServerHeartbeatSucceededEvent ` + - Called when a server heartbeat succeeds + + * - :php:`serverOpening() ` + - :php:`ServerOpeningEvent ` + - Called when a new server is added to the topology + + * - :php:`topologyChanged() ` + - :php:`TopologyChangedEvent ` + - Called when the topology description changes + + * - :php:`topologyClosed() ` + - :php:`TopologyClosedEvent ` + - Called when the topology is closed + + * - :php:`topologyOpening() ` + - :php:`TopologyOpeningEvent ` + - Called when the topology is opened + +The following code creates the ``MySDAMSubscriber`` class, which implements +the ``SDAMSubscriber`` interface. The class defines each ``SDAMSubscriber`` method +and includes custom logic for the ``serverOpening()`` method, which prints details +about servers added to the topology: + +.. literalinclude:: /includes/monitoring/monitor.php + :start-after: start-sdam-subscriber + :end-before: end-sdam-subscriber + :language: php + :copyable: + :dedent: + +.. _php-register: + +Register an Event Subscriber +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +After creating a class that implements your subscriber interface, +you must register this class with a ``MongoDB\Client`` to receive +event notifications for your client. To register a subscriber, call the +``MongoDB\Client::addSubscriber()`` method and pass an instance +of your subscriber class as a parameter. + +Example +``````` + +The following code registers the command and SDAM event subscribers +created in the :ref:`php-subscribe` section of this page with a +``MongoDB\Client``: + +.. literalinclude:: /includes/monitoring/monitor.php + :start-after: start-add-subs + :end-before: end-add-subs + :language: php + :copyable: + :dedent: + +When you start the application and run an insert command, your subscribers +record the events and output messages that resemble 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 + Started command #3 "insert": { "insert" : ... } + +Remove a Subscriber +------------------- + +To unregister a subscriber from your client, use the +``MongoDB\Client::removeSubscriber()`` method. + +The following code shows how to remove the subscriber created in +the :ref:`php-subscribe-command` section of this page: + +.. literalinclude:: /includes/monitoring/monitor.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\CommandSubscriber ` +- :php:`MongoDB\Driver\Monitoring\SDAMSubscriber `