Monitoring

Command Events

A command event is an event related to a MongoDB database command. Some examples of database commands that produce command events are find, insert, delete, and count.

To monitor command events, write a class that implements the CommandListener interface and register an instance of that class with your MongoClient instance.

For more information on MongoDB database commands, see the MongoDB manual entry on database commands.

class CommandCounter : CommandListener {
    private val commands = mutableMapOf<String, Int>()
    @Synchronized
    override fun commandSucceeded(event: CommandSucceededEvent) {
        val commandName = event.commandName
        val count = commands[commandName] ?: 0
        commands[commandName] = count + 1
        println(commands.toString())
    }
    override fun commandFailed(event: CommandFailedEvent) {
        println("Failed execution of command '${event.commandName}' with id ${event.requestId}")
    }
}

val commandCounter = CommandCounter()
val settings = MongoClientSettings.builder()
    .applyConnectionString(URI)
    .addCommandListener(commandCounter)
    .build()
val mongoClient = MongoClient.create(settings)
val database = mongoClient.getDatabase(DATABASE)
val collection = database.getCollection<Document>(COLLECTION)
// Run some commands to test the counter
collection.find().firstOrNull()
collection.find().firstOrNull()

{find=1}
{find=2}
{find=2, endSessions=1}

Server Discovery and Monitoring Events

A server discovery and monitoring (SDAM) event is an event related to a change in the state of the MongoDB instance or cluster you have connected the driver to.

The driver defines nine SDAM events. The driver divides these nine events between three separate listener interfaces which each listen for three of the nine events. Here are the three interfaces and the events they listen for:

• ClusterListener: topology-related events

• ServerListener: events related to mongod or mongos processes

• ServerMonitorListener: heartbeat related events

To monitor a type of SDAM event, write a class that implements one of the three preceding interfaces and register an instance of that class with your MongoClient instance.

For a detailed description of each SDAM event, see the MongoDB SDAM monitoring events specification.

class IsWriteable : ClusterListener {
    private var isWritable = false
    @Synchronized
    override fun clusterDescriptionChanged(event: ClusterDescriptionChangedEvent) {
        if (!isWritable) {
            if (event.newDescription.hasWritableServer()) {
                isWritable = true
                println("Able to write to cluster")
            }
        } else {
            if (!event.newDescription.hasWritableServer()) {
                isWritable = false
                println("Unable to write to cluster")
            }
        }
    }
}

val clusterListener = IsWriteable()
val settings = MongoClientSettings.builder()
    .applyConnectionString(URI)
    .applyToClusterSettings { builder ->
        builder.addClusterListener(clusterListener)
    }
    .build()
val mongoClient = MongoClient.create(settings)
val database = mongoClient.getDatabase(DATABASE)
val collection = database.getCollection<Document>(COLLECTION)
// Run a command to trigger a ClusterDescriptionChangedEvent event
collection.find().firstOrNull()

Able to write to server

Connection Pool Events

A connection pool event is an event related to a connection pool held by the driver. A connection pool is a set of open TCP connections your driver maintains with a MongoDB instance. Connection pools help reduce the number of network handshakes your application needs to perform with a MongoDB instance, and can help your application run faster.

To monitor connection pool events, write a class that implements the ConnectionPoolListener interface and register an instance of that class with your MongoClient instance.

class ConnectionPoolLibrarian : ConnectionPoolListener {
    override fun connectionCheckedOut(event: ConnectionCheckedOutEvent) {
        println("Let me get you the connection with id ${event.connectionId.localValue}...")
    }
    override fun connectionCheckOutFailed(event: ConnectionCheckOutFailedEvent) {
        println("Something went wrong! Failed to checkout connection.")
    }
}

val cpListener = ConnectionPoolLibrarian()
val settings = MongoClientSettings.builder()
    .applyConnectionString(URI)
    .applyToConnectionPoolSettings { builder ->
        builder.addConnectionPoolListener(cpListener)
    }
    .build()
val mongoClient = MongoClient.create(settings)
val database = mongoClient.getDatabase(DATABASE)
val collection = database.getCollection<Document>(COLLECTION)
// Run a command to trigger connection pool events
collection.find().firstOrNull()

Let me get you the connection with id 21...

JMX Support

To enable JMX connection pool monitoring, add an instance of the JMXConnectionPoolListener class to your MongoClient object.

The JMXConnectionPoolListener class performs the following actions:

1. Creates MXBean instances for each mongod or mongos process the driver maintains a connection pool with.

2. Registers these MXBean instances with the platform MBean server.

MXBeans registered on the platform MBean server have the following properties:

All MXBean instances created by the driver are under the domain "org.mongodb.driver".

For more information on the topics discussed in this subsection, see the following resources from Oracle:

• Platform MBean Server Reference Documentation

• MXBean Documentation

• MBean Documentation

JMX and JConsole Example

This example shows how you can monitor the driver's connection pools using JMX and JConsole. JConsole is a JMX compliant GUI monitoring tool that comes with the Java Platform.

The following code snippet adds a JMXConnectionPoolListener to a MongoClient instance. The code then pauses execution so you can navigate to JConsole and inspect your connection pools.

val connectionPoolListener = JMXConnectionPoolListener()
val settings = MongoClientSettings.builder()
    .applyConnectionString(uri)
    .applyToConnectionPoolSettings {
        it.addConnectionPoolListener(connectionPoolListener)
    }
    .build()
val mongoClient: MongoClient = MongoClient.create(settings)
try {
    println("Navigate to JConsole to see your connection pools...")
    Thread.sleep(Long.MAX_VALUE)
} catch (e: Exception) {
    e.printStackTrace()
}

Navigate to JConsole to see your connection pools...

Once you have started your server, open JConsole in your terminal using the following command:

jconsole

Once JConsole is open, perform the following actions in the GUI:

1. Select the process running the preceding example code.

2. Press Insecure Connection in the warning dialog box.

3. Click on the MBeans tab.

4. Inspect your connection pool events under the "org.mongodb.driver" domain.

When you no longer want to inspect your connection pools in JConsole, do the following:

• Exit JConsole by closing the JConsole window

• Stop the program running the preceding code snippet

For more information on JMX and JConsole, see the following resources from Oracle:

• JConsole Documentation.

• Monitoring and Management Guide

For more information on the JMXConnectionPoolListener class, see the API Documentation for JMXConnectionPoolListener.