Skip to content

Commit 45b281d

Browse files
rustagirrustagir
committed
DOCSP-41982: cluster monitoring
1 parent a772b6a commit 45b281d

File tree

4 files changed

+200
-0
lines changed

4 files changed

+200
-0
lines changed

‎source/includes/monitoring/sdam.php

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
<?php
2+
3+
require __DIR__ . '/vendor/autoload.php';
4+
5+
// start-mysubscriber
6+
class MySubscriber implements MongoDB\Driver\Monitoring\SDAMSubscriber
7+
{
8+
private $stream;
9+
public function __construct($stream)
10+
{
11+
$this->stream = $stream;
12+
}
13+
public function serverOpening(MongoDB\Driver\Monitoring\ServerOpeningEvent $event): void
14+
{
15+
fwrite($this->stream, sprintf(
16+
'Server opening on %s:%s%s',
17+
$event->getHost(),
18+
$event->getPort(),
19+
PHP_EOL,
20+
));
21+
}
22+
public function serverClosed(MongoDB\Driver\Monitoring\ServerClosedEvent $event): void {}
23+
public function serverChanged(MongoDB\Driver\Monitoring\ServerChangedEvent $event): void {}
24+
public function serverHeartbeatFailed(MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent $event): void {}
25+
public function serverHeartbeatStarted(MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent $event): void {}
26+
public function serverHeartbeatSucceeded(MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent $event): void {}
27+
public function topologyChanged(MongoDB\Driver\Monitoring\TopologyChangedEvent $event): void {}
28+
public function topologyClosed(MongoDB\Driver\Monitoring\TopologyClosedEvent $event): void {}
29+
public function topologyOpening(MongoDB\Driver\Monitoring\TopologyOpeningEvent $event): void {}
30+
}
31+
// end-mysubscriber
32+
33+
$uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your Atlas URI that connects to the sample dataset');
34+
$client = new MongoDB\Client($uri);
35+
36+
$database = $client->db;
37+
$collection = $database->my_coll;
38+
39+
// start-add-sub
40+
$subscriber = new MySubscriber(STDERR);
41+
$client->addSubscriber($subscriber);
42+
// end-add-sub
43+
44+
$collection->insertOne(['x' => 100]);

‎source/index.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ MongoDB PHP Library
1515
/write
1616
/aggregation
1717
/indexes
18+
/monitoring
1819
/security
1920
/tutorial
2021
/upgrade

‎source/monitoring.txt

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
.. _php-monitoring:
2+
3+
========================
4+
Monitor Your Application
5+
========================
6+
7+
.. toctree::
8+
:caption: Monitoring categories
9+
10+
/monitoring/cluster-monitoring
11+
12+
.. /monitoring/command-monitoring
13+
.. /monitoring/connection-monitoring
14+
15+
- :ref:`Cluster Monitoring <php-cluster-monitoring>`: monitor changes
16+
in your cluster configuration
17+
18+
.. TODO - :ref:`Command Monitoring <php-command-monitoring>`: monitor command
19+
.. execution
20+
.. - :ref:`Connection Pool Monitoring <php-connection-monitoring>`:
21+
.. monitor changes in the connection pool

‎source/monitoring/cluster-monitoring.txt

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
.. _php-cluster-monitoring:
2+
3+
==================
4+
Cluster Monitoring
5+
==================
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: code example, server, topology
13+
14+
.. contents:: On this page
15+
:local:
16+
:backlinks: none
17+
:depth: 2
18+
:class: singlecols
19+
20+
Overview
21+
--------
22+
23+
This guide shows you how to use the {+php-library+} to monitor topology
24+
events in a MongoDB instance, replica set, or sharded cluster. The
25+
driver creates topology events, also known as Server Discovery and
26+
Monitoring (**SDAM**) events, when there are any changes in the state of the
27+
MongoDB instance or cluster that you are connected to.
28+
29+
You might use information about topology events in your
30+
application to understand cluster changes, assess cluster health, or
31+
perform capacity planning.
32+
33+
Subscribe to Events
34+
-------------------
35+
36+
You can access details about SDAM events by subscribing to them
37+
in your application. To subscribe to any event, create a class that
38+
implements the ``MongoDB\Driver\Monitoring\SDAMSubscriber`` interface,
39+
then use the ``MongoDB\Client::addSubscriber()`` method to register the
40+
event subscriber with your ``MongoDB\Client`` instance.
41+
42+
The following code creates the ``MySubscriber`` class that implements
43+
``SDAMSubscriber`` to output a message when a ``ServerOpeningEvent`` is
44+
generated by the server:
45+
46+
.. literalinclude:: /includes/monitoring/sdam.php
47+
:start-after: start-mysubscriber
48+
:end-before: end-mysubscriber
49+
:language: php
50+
:copyable:
51+
:dedent:
52+
53+
.. note::
54+
55+
As shown in the preceding code, you must implement all of the methods
56+
of ``SDAMSubscriber``, even for events you are not subscribing to.
57+
You can implement these methods with empty bodies so that the library
58+
does not generate any messages for these events.
59+
60+
Then, the following code uses the ``addSubscriber()`` method to register
61+
``MySubscriber`` with the client:
62+
63+
.. literalinclude:: /includes/monitoring/sdam.php
64+
:start-after: start-add-sub
65+
:end-before: end-add-sub
66+
:language: php
67+
:copyable:
68+
:dedent:
69+
70+
When you run the application, your subscriber records the SDAM event and
71+
outputs messages such as the following:
72+
73+
.. code-block:: none
74+
75+
Server opening on ac-rmuag0v-shard-00-00.gh0qg50.mongodb.net:27017
76+
Server opening on ac-rmuag0v-shard-00-01.gh0qg50.mongodb.net:27017
77+
Server opening on ac-rmuag0v-shard-00-02.gh0qg50.mongodb.net:27017
78+
79+
Event Descriptions
80+
------------------
81+
82+
You can subscribe to the following SDAM events by implementing the
83+
corresponding method from the ``SDAMSubscriber`` interface:
84+
85+
.. list-table::
86+
:widths: 35 65
87+
:header-rows: 1
88+
89+
* - Event Name
90+
- Description
91+
92+
* - ``ServerChangedEvent``
93+
- Created when an instance state changes, such as from secondary to
94+
primary.
95+
96+
* - ``ServerOpeningEvent``
97+
- Created when the server is initialized.
98+
99+
* - ``ServerClosedEvent``
100+
- Created when the server is closed.
101+
102+
* - ``TopologyChangedEvent``
103+
- Created when the topology changes, such as an election of a new
104+
primary or disconnection of a ``mongos`` proxy.
105+
106+
* - ``TopologyOpeningEvent``
107+
- Created when the topology is initialized.
108+
109+
* - ``TopologyClosedEvent``
110+
- Created when the topology is closed.
111+
112+
* - ``ServerHeartbeatStartedEvent``
113+
- Created when the heartbeat is started.
114+
115+
* - ``ServerHeartbeatSucceededEvent``
116+
- Created when the heartbeat succeeds.
117+
118+
* - ``ServerHeartbeatFailedEvent``
119+
- Created when the heartbeat fails.
120+
121+
API Documentation
122+
-----------------
123+
124+
To learn more about any of the classes or methods discussed in this guide, see the
125+
following API documentation:
126+
127+
- :phpmethod:`MongoDB\Client::addSubscriber()`
128+
- :phpclass:`MongoDB\Client`
129+
130+
To learn more about subscriber classes and methods, see the following
131+
pages in the PHP manual:
132+
133+
- :php:`mongodb-driver-monitoring-sdamsubscriber`
134+
- :php:`mongodb-driver-monitoring-serveropeningevent`

0 commit comments

Comments
 (0)