Monitor your Deployment

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, create 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 Database Commands in the MongoDB Server manual.

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

MongoClientSettings settings = MongoClientSettings.builder()
        .applyConnectionString(URI)
        .addCommandListener(new CommandCounter())
        .build();
try (MongoClient mongoClient = MongoClients.create(settings)) {
    MongoDatabase database = mongoClient.getDatabase(DATABASE);
    MongoCollection<Document> collection = database.getCollection(COLLECTION);
    // Run some commands to test the counter
    FindPublisher<Document> findPublisher1 = collection.find();
    FindPublisher<Document> findPublisher2 = collection.find();
    Flux.from(findPublisher1).blockLast();
    Flux.from(findPublisher2).blockLast();
}

{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 IsWritable 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");
        }
    }
}

MongoClientSettings settings = MongoClientSettings.builder()
        .applyConnectionString(URI)
        .applyToClusterSettings(builder ->
                builder.addClusterListener(new IsWritable()))
        .build();
try (MongoClient mongoClient = MongoClients.create(settings)) {
    MongoDatabase database = mongoClient.getDatabase(DATABASE);
    MongoCollection<Document> collection = database.getCollection(COLLECTION);
    // Run a command to trigger a ClusterDescriptionChangedEvent
    FindPublisher<Document> findPublisher = collection.find();
    Flux.from(findPublisher).blockLast();
}

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 deployment. Connection pools help reduce the number of network handshakes your application needs to perform with a MongoDB deployment, 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.printf("Fetching the connection with id %s...%n",
                event.getConnectionId().getLocalValue());
    }
    @Override
    public void connectionCheckOutFailed(final ConnectionCheckOutFailedEvent event) {
        System.out.println("Something went wrong! Failed to checkout connection.");
    }
}

MongoClientSettings settings = MongoClientSettings.builder()
        .applyConnectionString(URI)
        .applyToClusterSettings(builder ->
                builder.addClusterListener(new IsWritable()))
        .build();
try (MongoClient mongoClient = MongoClients.create(settings)) {
    MongoDatabase database = mongoClient.getDatabase(DATABASE);
    MongoCollection<Document> collection = database.getCollection(COLLECTION);
    // Run a command to trigger a ClusterDescriptionChangedEvent
    FindPublisher<Document> findPublisher = collection.find();
    Flux.from(findPublisher).blockLast();
}

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

The following 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();
try (MongoClient mongoClient = MongoClients.create(URI)) {
    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);
}

Navigate to JConsole to see your connection pools...

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

jconsole

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

1. Select the Java process running the preceding example code.

2. Click 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, perform the following tasks:

1. Exit JConsole by closing the JConsole window.

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