An Easy Munin PHP Plugin


I've been playing sysadmin lately, which is not my favorite thing in the world. Anyway, while trying to read up a bit on monitoring, I came across Munin - one of those apps I've heard of but never really gotten around to investigating properly. Well, it is pretty darn cool - and you can write your own plugins - and I love writing plugins.

I suppose it may be a bit more complicated, but from my perspective, it collects stats every 5 minutes and makes pretty graphs with rrdtool. In the simplest configuration, one computer is both the client (a munin-node, which collects its own stats) and the server (munin, which aggregates stats for all the clients). Then you leave it running for a few days, weeks or years and you'll have a good idea of what your system should look like when things are running smoothly and when they are not. Hopefully this will allow you to anticipate and avoid problems, or at least understand what happened afterwards.

So that's neat. Here's a graph: (the empty area is where a server was rebooted and munin-node wasn't set to restart automatically)

So every 5 minutes, munin-node activates itself and runs all plugins you've got setup. Each plugin outputs a label and a number (or multiple labels and numbers), which the server collects and uses to make graphs. So writing your own plugin is super easy. Here is one in PHP that graphs the number of registered users in a Wordpress database.


// these are setup in the plugin config, or you could hardcode them
$db = getenv('DB');
$host = getenv('HOST');
$user = getenv('USER');
$pass = getenv('PASS');
$prefix = getenv('PREFIX');

// this is for munin's configuration tool
// could do something more complicated here
if(count($argv) == 2 && $arv[1] == 'authconf') {
// this is for rrdtool to know how to label the graph
if(count($argv) == 2 && $argv[1] == 'config') {
    echo("graph_title Users\n");
    echo("graph_vlabel count\n");
    echo("graph_category Wordpress\n");
    echo("wordpress_users.label Registered Users\n");
    echo("wordpress_users.type COUNTER\n"); 

// this is the usual case, generating a label and value
mysql_connect($host, $user, $pass);
$rs = mysql_query("SELECT COUNT(*) FROM {$prefix}users");
$rows = mysql_fetch_array($rs);
echo("wordpress_users.value {$rows[0]}\n");

Obviously you'll need to have a command-line PHP available at /usr/bin/php.

To install it, put the file in the available plugins directory and symlink it to the active plugins directory:

cp /path/to/plugin /usr/share/munin/plugins/your_plugin_name
ln -s /usr/share/munin/plugins/your_plugin_name /etc/munin/plugins/your_plugin_name

So that's pretty easy. There is also the plugin configuration where you setup the environment variables. This is particularly handy, as you could use multiple configurations of the same plugin to provide stats about different databases.

In this case, I just edited /etc/munin/plugin-conf.d/munin-node and created a new section matching my plugin's name, but I think there are other ways to do it for more complex configurations:

env.DB db_name_here
env.HOST localhost
env.USER db_user_here
env.PASS db_pass_here
env.PREFIX table_prefix_here

And finally, finally, you can test it to make sure it is working using munin-run. This is important because simply running it by self will not setup the environment variables. It wasn't on my path, but ended up in /usr/sbin:

/usr/sbin/munin-run your_plugin_name
wordpress_users.value 210

Oh yeah. When you're done testing and want to add your plugin for real, you need to restart munin-node:

/etc/init.d/munin-node restart

So I think it's a pretty cool and easy way to monitor just about anything. As always, there may be errors or inaccuracies, so munin experts, please offer corrections if you see a problem.

References: My PHP plugin was based heavily on: