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 about MongoDB database commands, see the MongoDB manual entry on database commands.

class CommandCounter implements CommandListener {
    private Map<String, Integer> commands = new HashMap<String, Integer>();
    @Override
    public synchronized void commandSucceeded(final CommandSucceededEvent event) {
        String commandName = event.getCommandName();
        int count = commands.containsKey(commandName) ? commands.get(commandName) : 0;
        commands.put(commandName, count + 1);
        System.out.println(commands.toString());
    }
    @Override
    public void commandFailed(final CommandFailedEvent event) {
        System.out.println(String.format("Failed execution of command '%s' with id %s",
                event.getCommandName(),
                event.getRequestId()));
    }
}

MongoClientSettings settings =
        MongoClientSettings.builder()
                .applyConnectionString(URI)
                .addCommandListener(new CommandCounter())
                .build();
MongoClient mongoClient = MongoClients.create(settings);
MongoDatabase database = mongoClient.getDatabase(DATABASE);
MongoCollection<Document> collection = database.getCollection(COLLECTION);
// Run some commands to test the timer
collection.find().first();
collection.find().first();
mongoClient.close();

{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 in the driver, see the MongoDB SDAM Logging and Monitoring Specification.

class IsWriteable implements ClusterListener {
    private boolean isWritable;
    @Override
    public synchronized void clusterDescriptionChanged(final ClusterDescriptionChangedEvent event) {
        if (!isWritable) {
            if (event.getNewDescription().hasWritableServer()) {
                isWritable = true;
                System.out.println("Able to write to server");
            }
        } else {
            if (!event.getNewDescription().hasWritableServer()) {
                isWritable = false;
                System.out.println("Unable to write to server");
            }
        }
    }
}

IsWriteable clusterListener = new IsWriteable();
MongoClientSettings settings =
        MongoClientSettings.builder()
                .applyConnectionString(URI)
                .applyToClusterSettings(builder ->
                        builder.addClusterListener(clusterListener))
                .build();
MongoClient mongoClient = MongoClients.create(settings);
MongoDatabase database = mongoClient.getDatabase(DATABASE);
MongoCollection<Document> collection = database.getCollection(COLLECTION);
// Run a command to trigger a ClusterDescriptionChangedEvent event
collection.find().first();

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 implements ConnectionPoolListener {
    @Override
    public void connectionCheckedOut(final ConnectionCheckedOutEvent event) {
        System.out.println(String.format("Let me get you the connection with id %s...",
                event.getConnectionId().getLocalValue()));
    }
    @Override
    public void connectionCheckOutFailed(final ConnectionCheckOutFailedEvent event) {
        System.out.println("Something went wrong! Failed to checkout connection.");
    }
}

ConnectionPoolLibrarian cpListener = new ConnectionPoolLibrarian();
MongoClientSettings settings =
        MongoClientSettings.builder()
                .applyConnectionString(URI)
                .applyToConnectionPoolSettings(builder ->
                        builder.addConnectionPoolListener(cpListener))
                .build();
MongoClient mongoClient = MongoClients.create(settings);
MongoDatabase database = mongoClient.getDatabase(DATABASE);
MongoCollection<Document> collection = database.getCollection(COLLECTION);
// Run a command to trigger connection pool events
collection.find().first();

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 about 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.

JMXConnectionPoolListener connectionPoolListener = new JMXConnectionPoolListener();
MongoClientSettings settings =
        MongoClientSettings.builder()
                .applyConnectionString(URI)
                .applyToConnectionPoolSettings(builder -> builder.addConnectionPoolListener(connectionPoolListener))
                .build();
// Creates a MongoClient instance that enables connection pool event monitoring with the JMX tool
MongoClient mongoClient = MongoClients.create(settings);
try {
    System.out.println("Navigate to JConsole to see your connection pools...");
    // Pauses the code execution so you can navigate to JConsole and inspect your connection pools
    Thread.sleep(Long.MAX_VALUE);
// Prints exception details if any exceptions occur during the code execution
} catch (Exception e) {
    e.printStackTrace();
}

The preceding code snippet produces output that resembles the following:

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 Java 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 Java program running the preceding code snippet

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

• JConsole Documentation.

• Monitoring and Management Guide

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