Monitor Application Events

Overview

In this guide, you can learn how to set up and configure monitoring in the MongoDB 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 MongoDB 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.

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:

Event Type	Description
Command events	Events related to MongoDB database commands, such as `find`, `insert`, `delete`, and `count`. To learn how to use the PHP library to run a database command, see Run a Database Command. For more information about MongoDB database commands, see Database Commands in the MongoDB 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:

Create an Event Subscriber: Create a class that implements the command or SDAM event subscriber
Register an Event Subscriber: Register a monitoring event subscriber with your MongoDB\Client

Tip

To view a list of monitoring events to which you can subscribe, see the Monitoring classes and subscriber functions section of the PHP manual.

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

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:

Method	Command Event	Description
commandFailed()	CommandFailedEvent	Called when a command does not succeed
commandStarted()	CommandStartedEvent	Called when a command is sent to the server
commandSucceeded()	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:

class MyCommandSubscriber implements MongoDB\Driver\Monitoring\CommandSubscriber
{
    public function __construct(private $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 {}
}

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:

Method	SDAM Event	Description
serverChanged()	ServerChangedEvent	Called when a server's description changes
serverClosed()	ServerClosedEvent	Called when a server is removed from the topology
serverHeartbeatFailed()	ServerHeartbeatFailedEvent	Called when a server heartbeat is unsuccessful
serverHeartbeatStarted()	ServerHeartbeatStartedEvent	Called when the server receives a heartbeat
serverHeartbeatSucceeded()	ServerHeartbeatSucceededEvent	Called when a server heartbeat succeeds
serverOpening()	ServerOpeningEvent	Called when a new server is added to the topology
topologyChanged()	TopologyChangedEvent	Called when the topology description changes
topologyClosed()	TopologyClosedEvent	Called when the topology is closed
topologyOpening()	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:

class MySDAMSubscriber implements MongoDB\Driver\Monitoring\SDAMSubscriber
{
    public function __construct(private $stream) {}
    public function serverOpening(MongoDB\Driver\Monitoring\ServerOpeningEvent $event): void {
        fprintf(
            $this->stream,
            'Server opening on %s:%s\n',
            $event->getHost(),
            $event->getPort(),
            PHP_EOL,
        );
    }
    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
    {
    }
}

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 Create an Event Subscriber section of this page with a MongoDB\Client:

$commandSub = new MyCommandSubscriber(STDERR);
$sdamSub = new MySDAMSubscriber(STDERR);
$client->addSubscriber($commandSub);
$client->addSubscriber($sdamSub);

When you start the application and run an insert command, your subscribers record the events and output messages that resemble 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
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 Command Event Subscriber Example section of this page:

$client->removeSubscriber($commandSub);

API Documentation

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

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

Back

Monitoring and Logging

Change Streams