Skip to content

By rei in EN, Munin

Version Fran├žaise
I write this post to add informations about the way to write a Munin plugin. I think that the actual official page isn’t enough detailed.
Actual How To Write a Plugin on Munin official website.

A Munin external plugin is launched by the munin-node every time the server call it, by default every 5 minutes, but already when the node reload or restart. The most important point is the way to answer, depends of the parameter send by the node.
The plugin must right answer to node in each parameters: name, config, and no parameter.

See here for official informations: protocol config

When it’s called with the config parameter, the answer must contains:

graph_title The Graph Title

But I think that these informations are required too:

graph_args
graph_vlabel
graph_category
graph_order

graph_args contains the parameter wich will be sent to the rrd-tool when creating graph, you can see here for all possibilities.
I use these parameters:

graph_args -l LowerLimitValue -u UpperLimitValue

graph_vlabel contains the graph vertical label (Mo, Go, Ko/s, Mb/s, number of X, etc.), it’s the name of your stats unit. If you check the weight of your server, put lb (isn’t it ? Oh :) ).

graph_category contains the name of the part where will be your graph on the web page. It’s very important to correctly set this name to well organize your graphs.

graph_order value is the list of your variables, in the good order for displays under the graph. For example, if you’re monitoring some processes, put the most important process in first place, to see it immediately.

The last very important field is the variable labels. Each variable had to appear with its label, like:

variable.label NameOfTheVariable

The variable label will appear under the graph, it had to be the same that in graph_order list.
For example, if you’re monitoring Processor Time:

usertime.label ProcessorTimeUsedByUser
totaltime.label TotalProcessorTime

You can specify (not required) at the same time the type of draw for the variable, type or cdef (change value before display), see the precedent link for more informations.

Optionally, you can add these parameters:

graph_info
graph_scale
graph_width
graph_height

graph_info contains a description of your graph, may be useful of your web page is about to be used by newbies.
graph_scale set if your graph is scalable or not, by default on yes.
graph_width and graph_height are explicit, only if you want a very big graph to see all details.

That’s all for the answer to config parameter, and never forget that the config must end by a dot (.) on a new line !

For the name parameter, it’s very easy, but required to the load of the node. It had to answers its name, and only its name, no dot (.), no spaces, and no other word.

These 2 parameters are for the node load, first call the plugin with name, and then (if name success) launch plugin with config.

At each call of node by the server, the node will launch your plugin without any parameter, and it had to answer the values of your variables, and end like config, with a dot (.).
With the previous example, it should be display:

usertime.value 47
totaltime.value 72
.

So here, my processor is used at 47% by user, and use 72% of its total time.
Never forget the dot (.).

So now, a complete example, it’s one of my plugin (maybe a post about it later):
The file is called errors.ps1, and I retrieve IIS errors on a Windows Server.

Launched with “name”:
>errors.ps1 name

IISerrors

Launched with “config”
>errors.ps1 config

graph_args -l 0 --upper-limit 2000
graph_title Erreurs IIS
graph_vlabel NumberOfErrors
graph_category system
graph_info Error graph of IIS6.0
graph_order BadRequest TimerConnectionIdle Hostname ConnectionDropped TimerHeaderWait Verb TimerMinBytesPerSecond Header ConnectionAbandonedByAppPool
errorHostname.label Hostname
errorTimerConnectionIdle.label TimerConnectionIdle
errorBadRequest.label BadRequest
errorConnectionDropped.label ConnectionDropped
errorVerb.label Verb
errorTimerHeaderWait.label TimerHeaderWait
errorTimerMinBytesPerSecond.label TimerMinBytesPerSecond
errorConnectionAbandonnedByAppPool.label ConnectionAbandonedByAppPool
errorHeader.label Header
.

Launched with no parameter
>errors.ps1

errorHostname.value 58
errorTimerConnectionIdle.value 45
errorBadRequest.value BadRequest 4
errorConnectionDropped.value 85
errorVerb.value 23
errorTimerHeaderWait.value 8
errorTimerMinBytesPerSecond.value 56
errorConnectionAbandonnedByAppPool.value 7
errorHeader.value 87
.

Never forget the dot.

Enjoy !

Tags: , ,