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