This document describes the installation and configuration of the MongoDB Monitoring Service (MMS). The guide also provides troubleshooting advice.
If you already have jira account you may sign in with your JIRA credentials. When you sign into MMS for the first time, the system prompts you to create a new “group” for your deployment.
This section outlines MMS’s prerequisite requirements and provides basic instructions for fulfilling them. If you are installing the MMS agent on a Windows host, skip to the window instructions section.
You must have Python 2.4 or greater.
The MMS Agent does not provide support the PyPy implementation of Python.
The MMS Agent does not support the Python 3.x series of Python.
You’ll need Python’s setuptools.
Most operating systems (i.e. distributions) package setuptools. For example, Debian and Ubuntu users can use the following command to install the package:
sudo apt-get install python-setuptools
For Red Hat Enterprise Linux (RHEL) CentOS, or Fedora users, the the following command will install the package:
sudo yum install python-setuptools
If your system is running Python 2.4, you will need to install the following Python modules:
Issue the following command:
sudo easy_install hmac hashlib
The latest version of the agent includes no other Python module dependencies. If you’re installing version 1.4 of the agent (legacy) you will also need to install the simplejson module.
For users of Python 2.4, you will need to install simplejson version 2.1.0. Install this module with the following command:
sudo easy_install simplejson==2.1.0
For users of Python 2.5, you will need to install the simplejson with the following command:
sudo easy_install simplejson
Do not use pip to install modules when using Python 2.4 or 2.5, as there are some compatibility issues. Some users have reported problems installing hmac, if easy_install produces an error or you suspect a problem with these libraries see instructions for installing hmac manually.
All users must install PyMongo, the Python driver for MongoDB. While the C extensions are not required, they significantly improve performance. To install these extensions, make sure you have a C compiler (e.g. gcc) and Python header files installed on your system. Debian and Ubuntu users should issue the following command:
sudo apt-get install build-essential python-dev
Red Hat, CentOS, and Fedora Users should issue the following command:
sudo yum install gcc python-devel
Use the latest possible version of PyMongo for the best possible speed and stability. The agent is not compatible with versions of PyMongo before 1.9. If you have not installed pymongo issue the following command to install the latest version:
sudo easy_install pymongo
To upgrade to the latest version of the driver, use the following command:
sudo easy_install -U pymongo
For more information concerning PyMongo installation, see the the PyMongo documentation.
Consider the README file distributed with the agent for more information. When all dependencies are successfully installed, you may proceed to installing the agent.
If you have not downloaded the MMS agent already, click the “download agent” link immediately after you sign into MMS (e.g. <http://mms.10gen.com> to download an agent specifically configured for your account. See the “Deploying the MMS Agent” document for more information regarding the agent itself.
You can run the agent on any system that can connect to the MongoDB instances you want to monitor. As long as it can connect to each instance, you can use a single agent to do all the monitoring. Do be sure that the agent can make outgoing connections via HTTPS on port 443.
Unzip the archive and run the agent with the following command:
This starts two processes: a parent to monitor the agent daemon and perform automatic upgrades and a child process to collect data.
If your MongoDB instance has thousands of databases or collections, you will want to disable database statistics collection. See “Database and Collection statistics” for more information.
“Automated Installation” to see how you can download a copy of the agent without the automatic configuration and then install and manually configure the MMS agent.
The above command is sufficient for testing the MMS agent. For production deployments, you will want to daemonize the process and ensure that it restarts following a system restart. Your operating system likely has a preferred method for managing daemon processes.
As a temporary measure, the following command will start the agent process detached from the current terminal session:
nohup python agent.py > /[LOG-DIRECTORY]/agent.log 2>&1 &
Replace “[LOG-DIRECTORY] with the path to your MongoDB logs.
This command allows the agent survive the current terminal session and writes all messages to the agent.log file. You may include this command in your MongoDB control script or use your system’s /etc/rc.local equivalent; however, avoid running the agent as root.
See the “Deploying the MMS Agent” document for more information on strategies for deploying the agent and your monitoring architecture. If your datacenter requires that you route outbound https connections via a proxy, export the “https_proxy” environment variable (or “HTTPS_PROXY” on Windows.) Issue the following command before running the agent:
Replace “http://proxyserver.example.net” with the name or IP address of the proxy server and “port with the TCP port that the proxy service runs on. You may choose to export this variable inside of your control script.
Once the agent is running, you can return to the web interface to begin configuring MMS for your deployment.
The MMS agent distribution includes a WINDOWS.txt file with instructions for using the agent on Windows platforms. Consider the following special requirements:
If you do not have a 2.x-series Python installation on your system, install the latest version of Python 2.7.x. If your system supports 64-bit executable, use the 64-bit version.
Use the Windows installer to install PyMongo from PyPi. Ensure that you install the correct PyMongo build for your Python installation both in terms of version number (e.g .2.6, 2.7, etc.) and system architecture (e.g. 32 or 64-bit.)
If you do not have Windows PowerShell version 2.0 to install, install it now. PowerShell is available as part of the Windows Management Framework.
Check your installed version of PowerShell by starting a PowerShell command window and issuing the following command:
Install the correct version if your version number is lower than 2.0.
Enable script execution in PowerShell. After installing the correct version, right click the PowerShell icon in the “Start Menu,” and run PowerShell as administrator. Issue the following command:
This returns the current execution policy. Save this value for future use. If the policy is “Unrestricted” you can proceed to the next step. If the policy is not “Unrestricted” issue the following command:
Set-ExecutionPolicy -ExecutionPolicy Unrestricted
Confirm the policy change when prompted.
Start an administrator command window. Change to the folder containing the MMS agent files. Run mongommsinstall.bat. If this succeeds, the MMS agent will be running and will start on system boot.
Now you can start and stop the Windows service to control the MMS agent. Consult the WINDOWS.txt file for more information.
If you have changed the execution policy, after the installation has completed successfully set it back to its original value using the following command:
Set-ExecutionPolicy -ExecutionPolicy <original value>
Replace “<original value>” with the value that you recorded above.
The C extensions for PyMongo are strongly recommended for use with the MMS agent because they provide the agent with greater performance and reduced resource requirements.
If you installed PyMongo with the C extensions (i.e. on a system with a C compiler, or using the Windows installer) then you can disregard this section. Otherwise use the following procedure to reinstall your agent with C extensions.
Install gcc, a C compiler, and the necessary development packages:
Debian and Ubuntu users should issue the following command:
sudo apt-get install build-essential python-dev
Red Hat, CentOS, and Fedora Users should issue the following command:
sudo yum install gcc python-devel
Install the pip utility so that you can uninstall the existing instance of PyMongo, by issuing the following command:
sudo easy_install pip
Remove the existing copy of PyMongo with the following command:
sudo pip uninstall pymongo
Now re-install PyMongo with the following command:
sudo pip install pymongo
After upgrading PyMongo, you will need to restart your MMS agent to receive the full effect of the improvement.
When you restart your agent there is a 5 minute timeout before the agent will begin sending data to MMS again.
The agent automatically updates itself following release of versions of the agent.
Auto-updating requires that agent run as a user which is capable of writing files to the directory that contains the agent. To manually update the agent, stop both agent processes, download the latest agent from the “Settings” page of the MMS console, and start the agent again.
The MMS agent automatically discovers MongoDB processes based on existing cluster configuration. You’ll have to manually “seed” at least one of these hosts from the MMS console.
To add a host to MMS, click the “plus” (+) button next to the word “Hosts,” at the top-center of the Hosts page. This raises a query element for the hostname, port, and optionally an admin DB username and password. Provide the necessary information and select “Add.”
Once it has a seed host, the agent will discover any other nodes from associated clusters. These clusters, and their respective seed hosts, include:
Once you add these seed nodes, the MMS agent will fetch this information from the MMS servers. Thus, when configuring the monitoring environment, you may need to wait for several update cycles (e.g. 5-10 minutes) to complete the auto-discovery process and host identification. During this period, you may see duplicate hosts in the MMS web console. This is normal.
The agent fetches configuration and reports to MMS every minute, so, again, there may be a delay of several minutes before data and host information propagate to the MMS console.
You can find immediate evidence of a working installation in the agent output or logs. For more information, check the MMS console’s “Hosts,” section in the “Agent Log” and “Pings” tabs. Once MMS has data, you can view and begin using the statistics.
If the agent cannot collect information about a host for 24 hours, the MMS system deactivates the instance in the MMS agent and console. Deactivated hosts must be manually reactivated from the MMS console if you wish to collect data from these hosts.
MMS provides support for collecting and charting hardware statistics collected with Munin. You must install the munin-node package on each the host system that you wish to monitor.
munin-node, and hardware monitoring is only available for MongoDB instances running on Linux hosts.
On Debian and Ubuntu systems, use the “sudo apt-get install munin-node” command. Red Hat, CentOS and Fedora users should issue the “sudo yum install munin-node” command. Ensure that munin-node:
is running. Use the command, “ps -ef | grep "munin"” to confirm. If the process is not running, issue the command “/etc/init.d/munin-node start”.
will start following the next system reboot. This is the default behavior on most Debian-based systems. Red Hat and related distributions should use the “chkconfig” command, to configure this behavior (i.e. “chkconfig munin-node on”)
is accessible from the system running the agent. munin-node uses port 4949, which needs to be open on the monitored system, so the agent can access this data source. Use the following procedure to test access:
telnet [HOSTNAME] 4949 fetch iostat fetch iostat_ios fetch cpu
Replace [HOSTNAME] with the hostname of the monitored system. Run these commands from the system where the MMS Agent is running. If these “fetch” commands return data, then munin-node is running and accessible by MMS agent.
If munin-node is running but inaccessible, make sure that you have access granted for the system running the MMS agent and that no firewalls block the port between munin-node and the agent. You may find the munin-node configuration at “/etc/munin-node/munin-node.conf” or “/etc/munin-node.conf”, depending on your distribution.
If you have numbered disk devices (e.g. /dev/sda1 and /dev/sda2) then you will need to configure support for numbered disk in the munin iostat plugin. Find the configuration file at /etc/munin/plugin-conf.d/munin-node or a similar path, and add the following value:
[iostat] env.SHOW_NUMBERED 1
If you have Munin enabled and do not have iostat ios data in your Munin charts, your munin-node may not have write access to required state files in its munin/plugin-state/ directory. See the munin-node plugin log (i.e. /var/log/munin/munin-node.log or similar depending on your distribution) for more information.
The full path of this state directory directory depends on the system, but is typically /var/lib/munin/plugin-state/. Run the following command sequence to correct this issue:
touch /var/lib/munin/plugin-state/iostat-ios.state chown -R [username]:[group] /var/lib/munin/plugin-state/ chmod -R 660 /var/lib/munin/plugin-state/
Replace [username] and [group] with the username and group that the munin-node process runs with.
If you encounter any other problems, check the log files for munin-node to ensure that there are no errors with Munin. munin-node writes logs files in the /var/log/ directory on the monitored system.
MMS can monitor MongoDB instances running with SSL. To use SSL with mongod and mongos, you must enable it at compile time, or use one of the subscriber builds. MongoDB added SSL support in version 2.0.
To monitor a host with SSL enabled, you can either:
Edit the settings.py file in your agent installation, so that the useSslForAllConnections value is True, as follows:
useSslForAllConnections = True
Then restart the agent. After restarting the agent you may observe a five minute delay before MMS receives data from the agent.
Enable support on a per-host basis in the MMS console, by clicking on the edit (i.e. “Pencil”) button on the right hand-side of the “Hosts” page. In the dialogue that pops up, click the check-box on the SSL tab.
If you enable SSL support globally you will not be able to override this setting on a per-host basis.
Consider the following issues if you encounter difficulty installing the MMS agent.
Make sure that the system running the agent has pymongo installed. If your system runs a 2.4.x series Python, verify the installation of other requirements.
Ensure that the system running the agent can resolve and connect to the MongoDB instances. To confirm, log into the system where the agent is running and issue a command in the following form:
Replace [hostname] with the hostname and [port] with the port that the database is listening on.
Verify that the agent can connect on TCP port 443 (outbound) to the MMS server (i.e. “mms.10gen.com”.)
Allow the agent to run for 5-10 minutes to allow host discovery and initial data collection.
If your MongoDB instances run with authentication enabled, ensure that MMS has these credentials. Supply these credentials on the “Add Host Interface,” for every host that has authentication enabled, when adding a host. You may also click on the “Edit” host button (i.e. the pencil) on the Hosts page in the MMS console to provide credentials.
If you continue to encounter problems, check the agent’s output or logs for errors.