Cluster Monitoring

Overview

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

The Scala driver defines nine SDAM events and provides the following listener interfaces, which listen for three SDAM events each:

• ClusterListener: Listens for events related to topology changes, or changes in the state and structure of the cluster

• ServerListener: Listens for events related to individual server changes

• ServerMonitorListener: Listens for heartbeat-related events, or reports on the status of communication between replica set members

You can 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 ClusterListener, ServerListener, or ServerMonitorListener interface. Then, add the listener to your client by configuring an instance of MongoClientSettings and passing it to the MongoClient constructor.

The following code creates the TestClusterListener class, which implements the ClusterListener interface. The class contains the following methods to handle topology-related events:

• clusterOpening(): Prints a message when the driver first connects to a cluster

• clusterClosed(): Prints a message when the driver disconnects from a cluster

• clusterDescriptionChanged(): Prints a message about changes to the read and write availability of the cluster

case class TestClusterListener(readPreference: ReadPreference) extends ClusterListener {
  var isWritable: Boolean = false
  var isReadable: Boolean = false
  override def clusterOpening(event: ClusterOpeningEvent): Unit =
      println(s"Cluster with ID ${event.getClusterId} opening")
  override def clusterClosed(event: ClusterClosedEvent): Unit =
      println(s"Cluster with ID ${event.getClusterId} closed")
  override def clusterDescriptionChanged(event: ClusterDescriptionChangedEvent): Unit = {
      if (!isWritable) {
          if (event.getNewDescription.hasWritableServer) {
              isWritable = true
              println("Writable server available")
          }
      } else {
          if (!event.getNewDescription.hasWritableServer) {
              isWritable = false
              println("No writable server available")
          }
      }
      if (!isReadable) {
          if (event.getNewDescription.hasReadableServer(readPreference)) {
              isReadable = true
              println("Readable server available")
          }
      } else {
          if (!event.getNewDescription.hasReadableServer(readPreference)) {
              isReadable = false
              println("No readable server available")
          }
      }
  }
}

Then, subscribe to the TestClusterListener class by configuring settings for your MongoClient instance, as shown in the following code:

val uri: ConnectionString = ConnectionString("<connection string>")
val settings: MongoClientSettings = MongoClientSettings
    .builder()
    .applyToClusterSettings((builder: ClusterSettings.Builder) =>
            builder.addClusterListener(TestClusterListener(ReadPreference.secondary())))
    .applyConnectionString(uri)
    .build()
val client: MongoClient = MongoClient(settings)

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

Cluster with ID ClusterId{value='...', description='...'} opening
Writable server available
Readable server available
Cluster with ID ClusterId{value='...', description='...'} closed

Event Descriptions

You can subscribe to SDAM events by defining a class that implements the event's corresponding listener interface and includes a method to process the event. The following table provides the name of each SDAM event, the listener interface that handles the event, and a description of when the event is published:

To see a full list of event monitoring classes, see the event package in the Java API documentation.

API Documentation

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

• clusterOpening()

• clusterClosed()

• clusterDescriptionChanged()