You should have an up and running Munin system somewhere, with access to added plugins. Due to Munins distributed architecture, there are two possibilities of setting Munin up to gather data. First, you could install an agent on the system Play is running on, and sending the data over to the Munin server. Second, you could query the /@status.json URI of the Play application. This example opts for the second way.

Again we will go through this recipe by using Ubuntu Linux as the monitoring system. Therefore, the paths of configuration files on other Linux distributions and server systems may vary.

You also need some Perl modules installed in order to make this work. In the case of Ubuntu Linux the packages needed are libjson-perl, libdigest-hmac-perl, and libwww-perl.

The first step is to add Play to your Munin node configuration, and append this to the munin-node file, which is placed under /etc/munin/plugin-conf.d/munin-node:

[play]
user munin
env.secret YOURSECRETHERE

Copy the secret from your application.conf file directly into this configuration, as the secret is needed to access the status page from remote.

Now create the check itself. Put it into the directory where all other checks reside or into /etc/munin/plugins/play and make sure it is flagged executable. If this is not the case, do this by entering chmod 755 /etc/munin/plugins/play:

#!/usr/bin/perl

use strict;
use Munin::Plugin;
use LWP::UserAgent;
use Digest::HMAC_SHA1;
use JSON;

my $secret = $ENV{'secret'};

my $hmac = Digest::HMAC_SHA1->new($secret);
$hmac->add('@status'),
my $digest = $hmac->hexdigest;

my $ua = LWP::UserAgent->new;
$ua->timeout(10);
$ua->default_header( 'Authorization' => "$digest" );

my $r = $ua->get('http://192.168.0.2:9000/@status.json'),

my $json = new JSON->decode($r->content);

if ( defined($ARGV[0]) and $ARGV[0] eq "config" ) {

    foreach my $controller(@{$json->{"play.CorePlugin"}->{"monitors"}}) {
        my $name = $controller->{"name"};
        if ($name !~ /()/) {
            next;       
        }       
        $name =~ s/^(.*)().*/$1/;
        my $classMethod = $name;
        $name =~ s/./_/;
                
        print "multigraph runtimes_$name
";
        print "graph_title Play Controller runtimes $classMethod
";
        print "graph_vlabel ms
";
        print "graph_scale no
";
        print "graph_category play
";
        print "graph_info Statistics about min/max/avg controller rates
";
        print "graph_args -l 0
";
                
        print $name."_min.label $name min
";
        print $name."_min.draw LINE2
";
        print $name."_max.label $name max
";
        print $name."_max.draw LINE2
";
        print $name."_avg.label $name avg
";
        print $name."_avg.draw LINE2
";
    }   

} else {

    foreach my $controller(@{$json->{"play.CorePlugin"}->{"monitors"}}) {
        my $name = $controller->{"name"};
        if ($name !~ /()/) {
            next;       
        }       
        $name =~ s/^(.*)().*/$1/;
        $name =~ s/./_/;

        my $avg = $controller->{"avg"};
        my $min = $controller->{"min"};
        my $max = $controller->{"max"};

        print "multigraph runtimes_$name
";
        print $name."_min.value %d
", $min;
        print $name."_max.value %d
", $max;
        print $name."_avg.value %d
", $avg;
    }
}

Restart Munin-node via /etc/init.d/munin-node restart or alternatively use upstart after storing the Perl script.

Before explaining what happens here, you can check whether your configuration is working at all. Use Telnet to connect to your Munin server on port 4949 and check for configuration and returning data:

> telnet localhost 4949
Trying ::1...
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
# munin node at yourServer
config play
multigraph runtimes_Application_index
...

fetch play
multigraph runtimes_Application_index
Application_index_min.value 3
Application_index_max.value 253
Application_index_avg.value 132
...

The bold marked lines are those typed in. The response of entering config play shows the configuration of the Play service, while the response of typing fetch play parses the data specific output of play status and returns it as needed for graphing. If you get similar results, just wait a few minutes for the next updates of your Munin server and you should see a nice graph for each controller, which yields the minimum, maximum, and average response times.

Back to the question—how is this all working? A Munin plugin has to implement two parts. First, a configuration setup needs to be returned if the plugin is called with a config parameter. The other part is to return the data needed to graph. In both cases the plugin code has to connect to the Play application in order to get a list of the currently active controllers. This means you can add or remove controllers, and the plugin will always cope with this. There is no need to add new controller methods somewhere manually in the Munin setup.

If you have read the configuration specific code of the plugin, you will see it uses another feature of Munin called multigraph. Usually one plugin can only emit one graph. However, it does not make too much sense to have all of your controllers packed into one graph. As soon as one controller is way slower than all the others, which might be an event intended in case of a big calculation or PDF creation, all your other graphs will not be readable at all when looking at the Munin GUI. The multigraph plugin allows having an arbitrary amount of graphs for one plugin, exactly what is needed.

I will not explain the Perl code too much. It parses the needed parts of the JSON response, checks whether the monitor name includes () which marks it as a controller and includes it then. It uses some regular expressions to beautify it for human reading. The only unknown part may be the use of the HMAC digest for the secret set in the configuration file. The digest is created by using the Play application secret as key for the message @status. The result is used in the Authorization HTTP header in order to authorize and get all needed data from the Play application. This is exactly how the command play status works as well.

Munin is an incredibly flexible tool and should be used by you or your operations department to find out a great deal about your application. After you have added your monitoring points, as shown earlier in this chapter, this is one of the best ways to visualize such data.