Get ready for a lot of acronyms in this post: “How to create a good XML-based API for MRTG sensor data”.
MRTG (Multi Router Traffic Grapher) is a tool to monitor the traffic load on network-links. It is widely used around the world to generate web pages containing images that provide a live visual representation of this traffic. MRTG is mainly a Swiss open-source product written by Tobias Oetiker from ETH Zurich with some help from others.
When used in its basic form (without RRDTOOL), it generates output like the following:
While MRTG was developed with network devices (routers) in mind, it can be used to show the trend of any numeric value over time. For that, it has a very simple input API: it expects 4 lines of text:
Line 1: current state of the first variable, normally 'incoming bytes count'
Line 2: current state of the second variable, normally 'outgoing bytes count'
Line 3: string (in any human readable format), telling the uptime of the target.
Line 4: string, telling the name of the target.
So there’s maximum 2 variables, which should be the same order of magnitude (or the automatic scaling of the Y-axis will make the smaller one undistinguisable of 0). The uptime and name show up in the “at which time ‘rou-rz-gw.ethz.ch’ had been up for 160 days, 8:02:55.” in the header of the HTML page.
MRTG in XML
In this world of REST, XMLRPC and SOAP interfaces, this seems so limited. Let’s try to make an XML format that allows the following:
- it should minimally contain the four data lines cited above
- it should be possible to add any parameter that influences the MRTG result (HTML and/or image) so that the XML as such is enough to define the whole MRTG configuration
This could be a minimal implementation:
<Sensors name="Second Life activity" date="2007-01-15 22:45:55 GMT" uptime="45 days, 5:55:12" >
<SensorI value="25334" name="# logged-in users " />
<SensorO value="36951" name="# Linden$ bought per hour" />
And this could be a more extended example:
name="Second Life activity"
date="2007-01-15 22:45:55 GMT"
uptime="45 days, 5:55:12"
name="# logged-in users " />
name="# Linden$ bought per hour" />
This would allow a script to generate a fitting
mrtg.conf configuration file from any reading of the data. The response is bigger than the simple 4 text lines, but in these days of cheap bandwidth and lots of CPU, that’s not really an issue. It’s also easy to convert the XML format into the 4 lines, if need be.
Anything I forgot?