M2DB FAQ

Everything You Always Wanted to Know About M2DB But Were Afraid to Ask.
M2DB stands for My MongoDB dashboard and gives You a fast and easy to understand overview of MongoDB's activities and status:

Sections: Introduction, Statistics, Collector, Installation and Configuration, Customization, Know bugs and limitations, License.

What is M2DB?

M2DB dashboard displays useful performance statistics for MongoDB. M2DB displays data based on MongoDB commands and on system, local and config collections.

M2DB does not modify any configuration or data in MongoDB. It can be used only to monitor systems, obtain performance data, collect statistics, ... To performe administrative tasks is strongly suggested to use the mongo shell.

M2DB is a web application and can be easly accessed with a browser:

  https://myhost.mydomain/M2DB/

Which is the architecture?

M2DB is a web application and requires a web server (eg. Apache) that can connect to MongoDB.
M2DB is written in PHP and requires PHP 5 (or newer) with the MongoDB PHP extension (MongoClient). M2DB uses Google Chart API and requires an Internet connection to download them.

M2DB shows both live data from MongoDB and collected data from a repository.
Data collection is performed by PHP file that can be periodically executed by crontab.

M2DB vs MongoDB compatibility

M2DB can connect to any version of MongoDB.

M2DB uses many internal MongoDB documents. db.serverStatus() metrics document has been added in version 2.4, the cursor document has been added in version 2.6, wiredTiger statistics section has been added in version 3.0, the balancer section in sharding status has been added in version 3.0...
M2DB uses all the available information and shows them in useful performance graphs.

For best results it is suggested to use MongoDB 3.0 or later.

Statistics

M2DB is very easy to use. The user inferface is the same in each page.
The Buttons allows to change the page. The Graphs show the informations. The Database info section shows informations about current connections. The Change database sections allows to choose between the configured database. M2DB release is displayed in the bottom.

There are four main pages:

• Dasboard: contains some of the most useful statistics for DBAs
• Status: reports current connection to the database
• Performance: shows performance statistics and in-depth view of most demanding commands
• Statistics: this page allows the DBA to display all the statistics, to change the time reference, ...

Graphical User Interface

The user inferface is the same in each page. The buttons, Database Info, Change Database and Release sections are reported in each page.
Current page button is grayed. Live data in Database Info section is displayed in italics while configuration data has no alterations. M2DB release can change between pages since they are indipendent.
If some part of the page are empty the reason is that M2DB can not get the information required to fill them. It can be a fault, a misconfiguration or these parts need a specific MongoDB version or a specific feature enabled.

Dashboard

The graphs in the Dashboard Page present both live data from MongoDB and historical use. The operations pie is collected when the page is loaded and can change if the page is reloaded.

Status

The tables shown in the Status Page give detail on operations, locks and replications occurring in MongoDB.

Performance

The Performance Page contains several graphs related to performance indicators for MongoDB.

Statistics

The Statistics Page allows to choose between different MongoDB metrics collected and shows them in a time based graph.
The last day (24 hours) of collected statistics is shown , to change the time frame set the Time shift (hours) parameter. For instance with 48 M2DB will show the day before yesterday statistics; with 24*60 M2DB will show the last two months statistic (useful with daily statistics as space usage).

From the statistics page a Groups Page can be reached. The Groups Page shows graphs from different MongoDB servers as they are configured in the config.inc.php file.

Statistics Collector

M2DB uses a collector to collect database statistics: the collect2repo.php PHP script.
The collector uses a MySQL Repository to store all the statistics.

The collector is executed every 10 minutes. Some slow changing data is collected only once a day.

Installation and configuration

Pre requisites

M2DB require a web server (eg. Apache) with PHP and a MongoDB driver configured. Admin privileges on a MySQL database are required for the Repository configuration. After the installation a normal MySQL user with few privileges is required.

To get all the information from MongoDB M2DB needs a user with the following privileges on each configured database:

• viewUser, viewRole
• inprog, cpuProfiler, storageDetails
• replSetGetStatus
• getShardMap, getShardVersion, listShards, shardingState
• getParameter, hostInfo
• collStats, dbStats, getLog, listDatabases, listCollections, listIndexes, serverStatus, top

Admin roles have all the required prerequisities.

Download

Download the distribution kit from the official download page.

Extract files

Untar or unzip the distribution (be sure to unzip the subdirectories):

unzip m2db.zip

in your web server's document root (e.g., /var/www/). If you don't have direct access to your document root or don't have shell access, put the files in a directory on your local machine and transfer the directory on your web server using, for example, FTP.
Ensure that all the scripts have the appropriate owner (if PHP is running in safe mode, having some scripts with an owner different from the owner of other scripts will be a problem).
To add the MongoClient interface to PHP the following directive should be added to the php.ini configuration file:

extension=mongo.so

M2DB Configuration

Now you must configure your installation.
There is a config.inc.php.sample file that can be copied/renamed to config.inc.php. While there are many parameters the only ones that need to be configured are the access string (host:port, username ad password) to connect to Your MongoDB database.

M2DB and its repository can manage different MongoDB databases.

Collector Configuration

Several M2DB pages are based on collected statistics.
The repository used by the collector is installed running the m2db.sql script as root on a MySQL database.
In a default installation the statistics are collected every 10 minutes and have a 60 days retention. This requires about 30MB.

To have the collector executed every 10 minutes can be easly done with the following crontab:

*/10 * * * * php /inst_path/collect2repo.php >> /tmp/m2db.log
5 0 * * *    php /inst_path/collect2repo.php DAILY >> /tmp/m2db.log

Can I change/customize the statistics?

Statistics can be customized with the custom.php file. There are already twenty custom statistics provided in distributed file. You can modify the existing ones or add Your own statistics. Please hold a copy of Your custom file in case of M2DB software upgrade.
You can use any of the more than one hundred variables collected by M2DB on MongoDB and the details about all available databases (an average of ten additional variables multiplied by number of databases).

There is an other file with statistics: common.php. But this file should not be changed since it is used by the M2DB dashboard.

Known bugs and limitations

None. It's not true of course!

• Showing different statistics together can be useful
• Statistics should be grouped by nodes partecipating to replication and/or sharding.

Can I use, distribute, modify M2DB?

Yes!

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses.

Title: M2DB FAQ
Date: 1st August 2014
Version: 0.0.1 (Alpha) - 1st September 2015
Authors: meo [AT] xenialab.it christian.disclafani [AT] xenialab.it