Cluster Monitoring

Overview

This guide shows you how to use the MongoDB 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.

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:

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 {
        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 {}
}

Then, use the addSubscriber() method to register MySubscriber with the client, as shown in the following code:

$subscriber = new MySubscriber(STDERR);
$client->addSubscriber($subscriber);

When you run the application, your subscriber records the SDAM event and outputs messages such as the following:

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:

You can find a list of the monitoring subscriber classes and event methods in the 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 Subscribe to Events section:

$client->removeSubscriber($subscriber);

API Documentation

To learn more about any of the classes or methods discussed in this guide, see the following API documentation:

• MongoDB\Client::addSubscriber()

• MongoDB\Client::removeSubscriber()

To learn more about subscriber classes and methods, see the following pages in the PHP manual:

• MongoDB\Driver\Monitoring\SDAMSubscriber

• MongoDB\Driver\Monitoring\ServerOpeningEvent