Docs Menu
Docs Home
/
Languages
/
PHP
/
PHP Library Manual
/
Monitor Your Application

Cluster Monitoring

On this page

  • Overview
  • Subscribe to Events
  • Event Descriptions
  • Remove a Subscriber
  • API Documentation

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

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:

$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:

Event Type
Description
ServerChangedEvent
Created when the server description changes, such as the server's type changing from secondary to primary.
Created when a new server is added to the topology.
Created when an existing server is removed from the topology.
Created when the topology description changes, such as when there is an election of a new primary.
Created when the driver first connects to the cluster.
Created when the driver disconnects from the cluster.
Created when the server monitor sends a hello command to the server. This action is called a heartbeat.
Created when the heartbeat succeeds.
Created when the heartbeat fails.

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:

Back

Monitor Your Application