How to Monitor MongoDB using Nagios check_mongodb Python Plugin

When you are running MongoDB in production environment, it is essential to monitor MongoDB to make sure it is up and running properly.

If you are already using Nagios for your enterprise monitoring, you can monitor MongoDB using plugins.

check_mongodb is a Nagios plugin written in Python to monitor various areas of MongoDB database.

This tutorial explains how to install, configure and monitor MongoDB database using check_mongodb.py Python plugin.

1. Download check_mongodb Nagios Plugin

Download Nagios MongoDB plugin from here. Or, you can use wget to download it directly to your server as shown below.

cd ~
wget --no-check-certificate https://github.com/mzupan/nagios-plugin-mongodb/archive/master.zip
unzip /usr/save/nagios-plugin-mongodb-master.zip

After you unzip the download, it will create the nagios-plugin-mongodb-master directory. Rename this directory to nagios-plugin-mongodb (i.e Remove the “-master” from the directory name).

mv nagios-plugin-mongodb-master nagios-plugin-mongodb

2. Install Plugin in Libexec directory

Move this “nagios-plugin-mongodb” directory to nagios libexec directory where all the plugins are located. If you’ve installed Nagios from source, the location of libexec directory is

mv nagios-plugin-mongodb /usr/local/nagios/libexec

Also, make sure this plugin directory is owned by nagios user and group as shown below.

cd /usr/local/nagios/libexec/

chown -R nagios:nagios nagios-plugin-mongodb/

At this stage, if you test the nagios plugin by executing check_mongodb.py, you might get “No module named pymongo” as shown below.

# cd /usr/local/nagios/libexec/nagios-plugin-mongodb

# ./check_mongodb.py
No module named pymongo

3. Download and Install Mongo Python Driver

In order for check_mongodb plugin to work properly, you should install and configure pymongo module on your server.

Download the MongoDB Python driver from here. Or, use the wget to download it directly to your server as shown below.

cd ~
wget --no-check-certificate https://github.com/mongodb/mongo-python-driver/archive/master.zip
unzip mongo-python-driver-master.zip
cd mongo-python-driver-master

Install pymongo by running the setup.py as shown below.

# python setup.py install
..
..
Adding distribute 0.6.30 to easy-install.pth file
Installing easy_install script to /usr/bin
Installing easy_install-2.4 script to /usr/bin

Installed /usr/lib/python2.4/site-packages/distribute-0.6.30-py2.4.egg
Processing dependencies for distribute==0.6.30
Finished processing dependencies for distribute==0.6.30
Processing pymongo-2.6-py2.4-linux-i686.egg
creating /usr/lib/python2.4/site-packages/pymongo-2.6-py2.4-linux-i686.egg
Extracting pymongo-2.6-py2.4-linux-i686.egg to /usr/lib/python2.4/site-packages
Adding pymongo 2.6 to easy-install.pth file

Installed /usr/lib/python2.4/site-packages/pymongo-2.6-py2.4-linux-i686.egg
Processing dependencies for pymongo==2.6
Finished processing dependencies for pymongo==2.6

4. Test MongoDB Nagios Plugin from Command Line

Now, if you try to execute the check_mongodb.py, you’ll not get the “No module named pymongo” error anymore.

# cd /usr/local/nagios/libexec/nagios-plugin-mongodb

# ./check_mongodb.py
CRITICAL - General MongoDB Error: could not connect to 127.0.0.1:27017: (111, 'Connection refused')

The basic usage of the MongoDB plugin is to test whether it can connect to a mongoDB instance. You can test the connection using any one of the following methods.

In the following example, we are passing only the ip-address of the server where the MongoDB database is running using the -H parameter. This will use the default action “connect”, and default port “27017”

# ./check_mongodb.py -H 192.168.1.2
OK - Connection took 0 seconds

If MongoDB server is running on a different port, you may want to specify it using -P option. You can also specify the “connect” action using -A parameter as shown below.

# ./check_mongodb.py -H 192.168.1.2 -A connect -P 27017

On a related note, if you are not taking a backup of your MongoDB database, make sure you first schedule a MongoDB backup using mongodump as we discussed earlier.

5. Add check_mongodb Command Definition

Append the following to the commands.cfg file. This will setup all the proper check_mongodb command definitons that you can use in your Nagios service definitions.

# vi /usr/local/nagios/etc/objects/commands.cfg
define command {
command_name check_mongodb
command_line $USER1$/nagios-plugin-mongodb/check_mongodb.py -H $HOSTADDRESS$ -A $ARG1$ -P $ARG2$ -W $ARG3$ -C $ARG4$
}

define command {
command_name check_mongodb_database
command_line $USER1$/nagios-plugin-mongodb/check_mongodb.py -H $HOSTADDRESS$ -A $ARG1$ -P $ARG2$ -W $ARG3$ -C $ARG4$ -d $ARG5$
}

define command {
command_name check_mongodb_collection
command_line $USER1$/nagios-plugin-mongodb/check_mongodb.py -H $HOSTADDRESS$ -A $ARG1$ -P $ARG2$ -W $ARG3$ -C $ARG4$ -d $ARG5$ -c $ARG6$
}

define command {
command_name check_mongodb_replicaset
command_line $USER1$/nagios-plugin-mongodb/check_mongodb.py -H $HOSTADDRESS$ -A $ARG1$ -P $ARG2$ -W $ARG3$ -C $ARG4$ -r $ARG5$
}

define command {
command_name check_mongodb_query
command_line $USER1$/nagios-plugin-mongodb/check_mongodb.py -H $HOSTADDRESS$ -A $ARG1$ -P $ARG2$ -W $ARG3$ -C $ARG4$ -q $ARG5$
}

6. Create Nagios Service Definition for MongoDB connect

Once you’ve tested the Nagios MongoDB plugin from the command line, create a service definition like the following and place it under the /usr/local/nagios/etc/servers directory. In the following example, the MongoDB is running on the server called “mongodb-prod-server”

# cat mongodb-prod-server.cfg
define service {
        use                     generic-service
        host_name               mongodb-prod-server
        service_description     MongoDB
        contacts                prodalert
        check_command           check_mongodb!connect!27017!2!4
}

Restart the nagios after the above change. After this, anytime the MongoDB database goes down, Nagios will send an alert to the contacts defined in the “prodalert” object.

7. Check Total Number of MongoDB Connections

You can also monitor the total number of MongoDB connections using the “connections” object.

The following example connects to the MongoDB running at 192.168.1.2 ip-address, authenticates using the username and password provided, and executes the “connections” action. The “-W 60” indicates the warning percentage, and “-C 80” indicates the critical percentage.

# ./check_mongodb.py -H 192.168.1.2 -u adminuser -p mysecretpassword -A connections -W 60 -C 80
OK - 1 percent (66 of 4000 connections) used

Unlike the “connect” action shown in this previous example, this “connections” actions required username and password to execute the “serverStatus” mongoDB command. If you don’t provide the username and password, you’ll get the following error.

# ./check_mongodb.py -H 192.168.1.2 -A connections -W 60 -C 80
CRITICAL - General MongoDB Error: command SON([('serverStatus', 1)]) failed: unauthorized

8. Check MongoDB Memory Usage

You can also check the memory usage of MongoDB using the “memory” action as shown below.

# ./check_mongodb.py -H 192.168.1.2 -u adminuser -p mysecretpassword -P 27017 -A memory -W 80 -C 90
OK - Memory Usage: 0.18GB resident, 17.25GB virtual, 8.47GB mapped, 16.93GB mappedWithJournal

9. Check Total Number of Mongo Databases

You can check the number of databases using the “databases” action as shown below. In this example, the warning limit is set to “-W 5”. Since the total number of databases on that server is 8, this is giving the WARNING message.

# ./check_mongodb.py -H 192.168.1.2 -u adminuser -p mysecretpassword -P 27017 -A databases -W 5 -C 10
WARNING - Number of DBs: 8

10. Check MongoDB Replication

If you’ve setup replication, you can use “replication_state” and “replication_lag” action as shown below. In this example, since this particular instance is not running in replication mode, it gives “OK” message, but it clearly indicates that this instance is not running with MongoDB replica set.

# ./check_mongodb.py -H 192.168.1.2 -u adminuser -p mysecretpassword -P 27017 -A replication_lag -W 80 -C 90
OK - Not running with replSet

# ./check_mongodb.py -H 192.168.1.2 -u adminuser -p mysecretpassword -P 27017 -A replset_state -W 80 -C 90
OK - Not running with replSet

11. All Nagios MongoDB Plugin Actions

The following is the list of all available actions in the check_mongodb.py Nagios plugin. Pass any one of these as an argument to the -A option.

• connect – Default action. Check the connection
• connections – Check the percentage of open database connections
• memory – Check memory usage
• memory_mapped – Check mapped memory usage
• lock – Check lock time percentage
• flushing – Check average flush time (in micro seconds)
• last_flush_time – Check last flush time (in micro seconds)
• index_miss_ratio – Check Index hit to miss ratio
• databases – Check total number of databases
• collections – Check total number of collections
• database_size – Check size of a particular database
• database_indexes – Check index size of a particular database
• collection_indexes – Check index size of a collection
• replication_lag – Check the replication lag (in seconds)
• replication_lag_percent – Check the replication lag (in percentage)
• replset_state – Check replica set status
• replica_primary – Check the primary server of a replica set
• queries_per_second – Check the number of queries per second
• connect_primary – Check connection to the primary server in a group
• collection_state – Check the state of a particular collection in a database