Skip to content

Commit e2cc75b

Browse files
rustagirrustagir
authored
Merge pull request #144 from rustagir/DOCSP-41982-cluster-monitoring
DOCSP-41982: cluster monitoring
2 parents 5812fdf + 4a39d20 commit e2cc75b

File tree

5 files changed

+234
-13
lines changed

5 files changed

+234
-13
lines changed

‎.github/workflows/check-autobuilder.yml

Lines changed: 0 additions & 13 deletions
This file was deleted.

‎source/includes/monitoring/sdam.php

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
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+
10+
public function __construct($stream)
11+
{
12+
$this->stream = $stream;
13+
}
14+
15+
public function serverOpening(MongoDB\Driver\Monitoring\ServerOpeningEvent $event): void {
16+
fprintf(
17+
$this->stream,
18+
'Server opening on %s:%s\n',
19+
$event->getHost(),
20+
$event->getPort(),
21+
);
22+
}
23+
24+
public function serverClosed(MongoDB\Driver\Monitoring\ServerClosedEvent $event): void {}
25+
public function serverChanged(MongoDB\Driver\Monitoring\ServerChangedEvent $event): void {}
26+
public function serverHeartbeatFailed(MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent $event): void {}
27+
public function serverHeartbeatStarted(MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent $event): void {}
28+
public function serverHeartbeatSucceeded(MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent $event): void {}
29+
public function topologyChanged(MongoDB\Driver\Monitoring\TopologyChangedEvent $event): void {}
30+
public function topologyClosed(MongoDB\Driver\Monitoring\TopologyClosedEvent $event): void {}
31+
public function topologyOpening(MongoDB\Driver\Monitoring\TopologyOpeningEvent $event): void {}
32+
}
33+
// end-mysubscriber
34+
35+
$uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your connection URI');
36+
$client = new MongoDB\Client($uri);
37+
38+
$collection = $client->db->my_coll;
39+
40+
// start-add-sub
41+
$subscriber = new MySubscriber(STDERR);
42+
$client->addSubscriber($subscriber);
43+
// end-add-sub
44+
45+
$collection->insertOne(['x' => 100]);
46+
47+
// start-remove-sub
48+
$client->removeSubscriber($subscriber);
49+
// end-remove-sub

‎source/index.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ MongoDB PHP Library
1616
/write
1717
/aggregation
1818
/indexes
19+
/monitoring
1920
/security
2021
/tutorial
2122
/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: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
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 server
24+
discovery and monitoring (SDAM) events in a MongoDB instance, replica
25+
set, or sharded cluster. These events occur when there are any changes
26+
in the state of the MongoDB instance or cluster that you are connected
27+
to.
28+
29+
You might use information about SDAM events in your application to
30+
understand cluster changes, assess cluster health, or perform capacity
31+
planning.
32+
33+
.. _php-subscribe-sdam:
34+
35+
Subscribe to Events
36+
-------------------
37+
38+
You can access details about SDAM events by subscribing to them
39+
in your application. To subscribe to an event, create a class that
40+
implements the ``MongoDB\Driver\Monitoring\SDAMSubscriber`` interface,
41+
then use the ``MongoDB\Client::addSubscriber()`` method to register the
42+
event subscriber with your ``MongoDB\Client`` instance.
43+
44+
The following code creates the ``MySubscriber`` class, which implements
45+
the ``SDAMSubscriber`` interface. The class is defined with a method to
46+
output a message when a ``ServerOpeningEvent`` is generated by the
47+
server:
48+
49+
.. literalinclude:: /includes/monitoring/sdam.php
50+
:start-after: start-mysubscriber
51+
:end-before: end-mysubscriber
52+
:language: php
53+
:copyable:
54+
:dedent:
55+
56+
.. note::
57+
58+
As shown in the preceding code, you must implement all the methods
59+
of the ``SDAMSubscriber`` interface, even for events you are not subscribing to.
60+
The example defines the extra methods as empty so that the
61+
application does not output any messages for those events.
62+
63+
Then, use the ``addSubscriber()`` method to register ``MySubscriber``
64+
with the client, as shown in the following code:
65+
66+
.. literalinclude:: /includes/monitoring/sdam.php
67+
:start-after: start-add-sub
68+
:end-before: end-add-sub
69+
:language: php
70+
:copyable:
71+
:dedent:
72+
73+
When you run the application, your subscriber records the SDAM event and
74+
outputs messages such as the following:
75+
76+
.. code-block:: none
77+
:copyable: false
78+
79+
Server opening on ac-rmuag0v-shard-00-00.gh0qg50.mongodb.net:27017
80+
Server opening on ac-rmuag0v-shard-00-01.gh0qg50.mongodb.net:27017
81+
Server opening on ac-rmuag0v-shard-00-02.gh0qg50.mongodb.net:27017
82+
83+
Event Descriptions
84+
------------------
85+
86+
You can subscribe to SDAM events by implementing the corresponding
87+
method from the ``SDAMSubscriber`` interface. The following table
88+
provides the name of each SDAM event, linked to the class's API
89+
documentation, and a description of when the event is published:
90+
91+
.. list-table::
92+
:widths: 35 65
93+
:header-rows: 1
94+
95+
* - Event Type
96+
- Description
97+
98+
* - :php:`ServerChangedEvent <mongodb-driver-monitoring-serverchangedevent>`
99+
- Created when the server description changes, such as the server's
100+
type changing from secondary to primary.
101+
102+
* - :php:`ServerOpeningEvent <mongodb-driver-monitoring-serveropeningevent>`
103+
- Created when a server connection is established.
104+
105+
* - :php:`ServerClosedEvent <mongodb-driver-monitoring-serverclosedevent>`
106+
- Created when a server connection is closed.
107+
108+
* - :php:`TopologyChangedEvent <mongodb-driver-monitoring-topologychangedevent>`
109+
- Created when the topology description changes, such as when there
110+
is an election of a new primary.
111+
112+
* - :php:`TopologyOpeningEvent <mongodb-driver-monitoring-topologyopeningevent>`
113+
- Created when the driver first connects to the cluster.
114+
115+
* - :php:`TopologyClosedEvent <mongodb-driver-monitoring-topologyclosedevent>`
116+
- Created when the driver disconnects from the cluster.
117+
118+
* - :php:`ServerHeartbeatStartedEvent <mongodb-driver-monitoring-serverheartbeatstartedevent>`
119+
- Created when the server monitor sends a ``hello`` command to the server.
120+
This action is called a heartbeat.
121+
122+
* - :php:`ServerHeartbeatSucceededEvent <mongodb-driver-monitoring-serverheartbeatsucceededevent>`
123+
- Created when the heartbeat succeeds.
124+
125+
* - :php:`ServerHeartbeatFailedEvent <mongodb-driver-monitoring-serverheartbeatfailedevent>`
126+
- Created when the heartbeat fails.
127+
128+
You can find a list of the monitoring subscriber classes and event
129+
methods in the :php:`Monitoring classes and subscriber functions
130+
<mongodb.monitoring>` section of the PHP manual.
131+
132+
Remove a Subscriber
133+
-------------------
134+
135+
Later in your application, you might not want to subscribe to
136+
SDAM events. To unregister a subscriber from your client, use the
137+
``MongoDB\Client::removeSubscriber()`` method. If you attempt to remove
138+
a nonexistent subscriber, the method doesn't perform any action.
139+
140+
The following code shows how to remove the subscriber that you
141+
registered in the :ref:`php-subscribe-sdam` section:
142+
143+
.. literalinclude:: /includes/monitoring/sdam.php
144+
:start-after: start-remove-sub
145+
:end-before: end-remove-sub
146+
:language: php
147+
:copyable:
148+
:dedent:
149+
150+
API Documentation
151+
-----------------
152+
153+
To learn more about any of the classes or methods discussed in this guide, see the
154+
following API documentation:
155+
156+
- :phpmethod:`MongoDB\Client::addSubscriber()`
157+
- :phpmethod:`MongoDB\Client::removeSubscriber()`
158+
159+
To learn more about subscriber classes and methods, see the following
160+
pages in the PHP manual:
161+
162+
- :php:`MongoDB\Driver\Monitoring\SDAMSubscriber <mongodb-driver-monitoring-sdamsubscriber>`
163+
- :php:`MongoDB\Driver\Monitoring\ServerOpeningEvent <mongodb-driver-monitoring-serveropeningevent>`

0 commit comments

Comments
 (0)