M3 (Monitis Monitor Manager) framework usage and examples were outlined in a few previous articles:
M3 – introduction
Planning your vacation / HTTP extraction
However we’ve never explained the bits and bytes behind it and what was the initial motivation for implementing it.
This article will outline the motivation, design, implementation and perhaps also the future road map for M3.
Rereading my previous articles I realized that I generated a somewhat steep learning curve for using M3 with the complex examples provided, just because M3 can handle these complex scenarios.
However M3 was created in order to simplify things. I’m going to use an extremely simple example in the following article to explain the way M3 works this time, I promise!
When I was first introduced to Monitis almost four months ago I was amazed by the API. Monitis is a vast, flexible and powerful hosted monitoring platform – however with the great flexibility comes also some complexity.
The API outlined over here is massive, covering almost every aspect of Monitis. However after implementing some use cases for interaction with Monitis I realized that a shortcut could be made for most use cases – and this is why M3 came to life.
99% of interactions with monitoring systems look like:
Run a command -> Parse output -> Send it to the monitoring platform
After discovering that a really good Perl implementation existed – I decided to implement M3 in Perl as well and use that edge.
M3′s – or Monitis Monitor Manager – purpose is to provide a simple integration for end users who wish to use Monitis on their servers without the hassle of understanding SOAP/REST calls which happen in the background.
As outlined before, the execution of M3 is as follows:
Run -> Parse -> Send
Lets examine the following XML sample and understand what’s behind it.
I’ve colored the “Run”, “Parse” and “Send” and the appropriate parts in the XML which correspond to them.
<?xml version="1.0"?> <config> <apicredentials apikey="XXX" secretkey="XXX"/> <agent name="Sample Agent" interval="5"> <monitor name="Sample Monitor"> <exectemplate>COMMAND_TO_RUN</exectemplate> <metric name="Read Requests per Second %HOSTNAME%"> <type>TYPE_OF_DATA</type> <uom>UNIT_OF_MEASUREMENT</uom> <regex>REGEX/XPATH/JSON</regex> </metric> </monitor> </agent> </config>
The “Run” part is relatively simple – M3 will simply run the command, be it a simple ‘ls’ or a longer pipeline such as ‘grep “:/bin/bash$” /etc/passwd | grep “:/home” | wc -l’.
M3 should handle most of these and please let me know if it doesn’t.
For the sake of this example, we’ll monitor the number of files in the /etc directory:
# find /etc -maxdepth 1 -type f | wc -l
This will conclude our “Run” part.
The “Parse” part of M3 was recently extended to include JSON and XPath paths, together with regular expressions. For the sake of this example lets stick to regular expressions. Examples of using XPath and JSON are in this article.
If you are unfamiliar with regular expressions – you should familiarize yourself with them. Although I do admit there is a bit of a learning curve. It’s worth it though.
The regular expression for this example is going to be relatively easy, as we’re going to take all of the output and use it:
# find /etc -maxdepth 1 -type f | wc -l 135
Mmm… 135 files in my /etc directory. Alright.
The regular expression we’ll use is ‘(.*)’ – which means – take all of the output!
The “Send” part is actually the easiest. Before integrating with Monitis you should have your API key and password. These could be easily obtained after logging into Monitis under “Tools -> API -> API Key”.
Together with that, the API requires us to specify the “Unit of measurement”, the “Type of data” and obviously the monitor and counter name. These can be easily filled in our case, given that we count files, so the UOM (Unit of measurement) will be integer.
API and and secret keys are omitted in this specific example for obvious reasons.
This phase is mainly handled by the Monitis Perl SDK with SOAP calls done in the background.
M3 takes its configuration as an XML. Forming the XML for the above example is simple:
<?xml version="1.0"?> <config> <apicredentials apikey="XXX" secretkey="XXX"/> <agent name="File Agent" interval="5"> <monitor name="ETC File Monitor"> <exectemplate>find /etc -maxdepth 1 -type f | wc -l</exectemplate> <metric name="Number of files in ETC"> <type>integer</type> <uom>number</uom> <regex>(.*)</regex> </metric> </monitor> </agent> </config>
Simple and elegant – with all the phases colored.
While implementing M3 I’ve decided to implement it as a flexible Perl module rather than an executable with heaps of command line parameters.
It does require the advanced user to know Perl, however the average user can get by because since the flexibility exists – we just provided some more executables to do everything without you having to touch any code.
All of these take the XML configuration file as a single parameter:
AddMonitors.pl – Will add all the monitors onto Monitis, so later on data can be inserted into their counters. It is mandatory to run this before you go into the “Run -> Parse -> Send” cycle.
Run.pl – Executes the “Run -> Parse -> Send” cycle, sending real actual monitoring data to Monitis.
DryRun.pl – Same as Run.pl, however does only the “Run -> Parse” cycle, omitting the “Send” phase. This is solely for debugging purposes, until you get your parsing right. Try it with a sample XML – it’s totally harmless!
Simple enough. Lets check out the sources:
# mkdir -p /usr/share/monitisexchange && cd /usr/share/monitisexchange # git clone git://github.com/monitisexchange/Monitis-Linux-Scripts.git # cd Monitis-Linux-Scripts/M3
The mentioned example is provided in this file.
Lets add the monitors:
# ./AddMonitors.pl etc_file_monitor.xml
If the monitors were added, lets perform a dry run:
# ./DryRun.pl etc_file_monitor.xml
And an actual run:
# ./Run.pl etc_file_monitor.xml
In order to periodically run M3, we’ll use crond, depending on your Linux distribution it might differ a bit. I assume that you are using a recent Fedora release:
# crontab -e
An editor will open, most likely vim. Add the line:
0 * * * * cd /usr/share/monitisexchange/Monitis-Linux-Scripts/M3 && ./Run.pl etc_file_monitor.xml
This will run the /etc file monitor every hour.
Login into Monitis and rock.
Psyched? Want to know what’s next?
Generally speaking we’re looking to extend M3 to provide most of the monitoring capabilities a Monitis user would require.
Right now M3 is able to obtain from a command line executable or a URL (yes, retrieving a URL).
The parsing modules that currently exists are for:
In a previous article we’ve introduced how to integrate MySQL with Monitis. The design and implementation of the MySQL unit resemble too much similarity to M3 that it might be a crime not to unify their functionality. So you should look forward for the integration of M3 with the MySQL (DBI) unit.
If we’ll delve even further into the design and implementation, the intention is to actually separate the retrieval and parsing of elements into modules, easing the way of adding new retrieval and parsing methods and encouraging users of M3 to contribute their own pieces of code.
Some of you might have noticed probably in the agent definition line we have the parameter “interval”:
<agent name="File Agent" interval="5">
On the road map we have the intention to add timers and triggers to M3 – eliminating the need to integrate M3 with crond – running M3 as a daemon by itself.
However the old functionality of a “one-time-run” will obviously stay.
Apart for that, we at Monitis believe that M3 provides you with much flexibility and control. However if you do not share this belief with us please let us know what can be done better – M3 is work in progress and we are more than happy to hear about new and innovative ideas.