1.. _plugin-writing: 2 3======================== 4 Writing a munin plugin 5======================== 6 7A munin plugin is a small executable. Usually, it is written in some 8interpreted language. 9 10In its simplest form, when the plugin is executed with the argument 11"config", it outputs metadata needed for generating the graph. If it 12is called with no arguments, it outputs the data which is to be 13collected, and graphed later. 14 15Plugin output 16============= 17 18The minimum plugin output when called with "config" it must output the 19graph title. 20 21It should also output a label for at least one datasource. 22 23:: 24 25 graph_title Some title for our plugin 26 something.label Foobar per second 27 28When the plugin is executed with no arguments, it should output a 29value for the datasource labelled in "config". It must not output 30values for which there are no matching labels in the configuration 31output. 32 33:: 34 35 something.value 42 36 37For a complete description of the available fields, see the 38:ref:`plugin-reference`. 39 40Example shell plugin 41==================== 42 43The base of a plugin is a small option parser, ensuring the plugin is 44called with the correct argument, if any. 45 46Two main functions are defined: One for printing the configuration to 47the standard output, and one for printing the data. In addition, we 48have defined a function to generate the data itself, just to keep the 49plugin readable. 50 51The "output_usage" function is there just to be polite, it serves no 52other function. :) 53 54.. code-block:: bash 55 56 #!/bin/sh 57 58 output_config() { 59 echo "graph_title Example graph" 60 echo "plugins.label Number of plugins" 61 } 62 63 output_values() { 64 printf "plugins.value %d\n" $(number_of_plugins) 65 } 66 67 number_of_plugins() { 68 find /etc/munin/plugins -type l | wc -l 69 } 70 71 output_usage() { 72 printf >&2 "%s - munin plugin to graph an example value\n" ${0##*/} 73 printf >&2 "Usage: %s [config]\n" ${0##*/} 74 } 75 76 case $# in 77 0) 78 output_values 79 ;; 80 1) 81 case $1 in 82 config) 83 output_config 84 ;; 85 *) 86 output_usage 87 exit 1 88 ;; 89 esac 90 ;; 91 *) 92 output_usage 93 exit 1 94 ;; 95 esac 96 97Activating the plugin 98===================== 99 100Place the plugin in the /etc/munin/plugins/ directory, and make it 101executable. 102 103Then, restart the munin-node. 104 105Debugging the plugin 106==================== 107 108To see how the plugin works, as the munin node would run it, you can 109use the command "munin-run". 110 111If the plugin is called "example", you can run "munin-run example 112config" to see the plugin configuration, and "munin-run example" to 113see the data. 114 115If you do not get the output you expect, check if your munin plugin 116needs more privileges. Normally, it is run as the "munin" user, but 117gathering some data may need more access. 118 119If the munin plugin emits errors, they will be visible in 120/var/log/munin/munin-node.log 121