1Munin::Plugin(3) User Contributed Perl Documentation Munin::Plugin(3)
2
6 Munin::Plugin - Utility functions for Perl Munin plugins.
7 Usage
9 use lib $ENV{'MUNIN_LIBDIR'};
10 use Munin::Plugin;
11 If your Munin installation predates the MUNIN_* environment variables
13 (introduced in 1.3.3) you can put this in your plugin configuration:
14 [*]
16 env.MUNIN_PLUGSTATE /lib/munin/plugin-state
17 env.MUNIN_LIBDIR /usr/share/munin
18 IF, indeed that is the munin plugin state directory. The default
20 install directory for Munin::Plugin is in Perl's module search path,
21 the "use lib" is there for the cases where this is not so, and the
22 variable needs to be set to stop Perl from complaining.
23 The module exports these functions: clean_fieldname, set_state_name,
25 save_state, restore_state, tail_open, tail_close.
26 Variables
28 The module instantiates a number of variables in the $Munin::Plugin
29 scope. None of these are exported, and they must be referenced by the
30 full names shown here.
31 $Munin::Plugin::me
33 The name of the plugin without any prefixing directory names and so on.
35 Same as "basename $0" in a shell. It is a very good idea to use this
36 in warning and/or error messages so that the logs show clearly what
37 plugin the error message comes from.
38 $Munin::Plugin::pluginstatedir
40 Identical to the environment variable MUNIN_PLUGSTATE (available since
42 Munin 1.3.3) or the install time @@PLUGSTATE@@ 'constant'. You can use
43 this if you need to save several different state files. But there is
44 also a function to change the state file name so the state file support
45 functions can be used for several state files.
46 If its value cannot be determined the plugin will be aborted at once
48 with an explanatory message. The most likely causes are:
49 · You are running the plugin directly and not from munin-node or
51 munin-run;
52 · Your munin-node is too old;
54 · munin-node was installed incorrectly.
56 The two last points can be worked around by the plugin configuration
58 shown at the beginning of this document.
59 $Munin::Plugin::statefile
61 The automatically calculated name for the plugins state file. The name
63 is supplied by munin-node or munin-run (in the MUNIN_STATEFILE
64 environment variable). The file name contains the plugin name and the
65 ip-number of the munin-master the node is talking to (munin-run leaves
66 the master part blank) to enable stateful plugins that calculate
67 gauguges and assumes a 5 minute run interval to work in munin-setups
68 with multiple munin-masters (this is not a uncommon way to set up
69 Munin).
70 To change the value of this please use the set_state_name($) procedure
72 (see below).
73 $Munin::Plugin::DEBUG
75 Set to true if the plugin should emit debug output. There are some
77 (but not many) debug print statements in the Module as well, which all
78 obey this variable. Set from the MUNIN_DEBUG environment variable.
79 Defaults to false (0).
80 Functions
82 $fieldname = clean_fieldname($input_fieldname)
83 Munin plugin field names are restricted with regards to what characters
85 they may use: The characters must be "[a-zA-Z0-9_]", while the first
86 character must be "[a-zA-Z_]". To satisfy these demands the function
87 replaces illegal characters with a '_'.
88 See also
90 <http://munin.projects.linpro.no/wiki/notes_on_datasource_names>
91 set_state_name($statefile_name)
93 Override the default statefile name. This only modifies the filename
95 part, not the directory name. The function unconditionally appends
96 "-$MUNIN_MASTER_IP" to the file name to support multiple masters as
97 described in the documentation for the statefile variable (above).
98 Calling this function is not normally needed and is not recommended.
100 save_state(@state_vector)
102 Save the passed state vector to the state file appropriate for the
104 plugin. The state vector should contain only strings (or numbers), and
105 absolutely no objects or references. The strings may contain newlines
106 without ill effect.
107 If the file cannot be opened for writing the plugin will be aborted.
109 The state file name is determined automatically based on the name of
111 the process we're running as. See $Munin::Plugin::me,
112 $Munin::Plugin::statefile and set_state_name above about the file name.
113 The file will contain a starting line with a magic number so that the
115 library can see the difference between an actual state file and a file
116 containing rubbsh. Currently this magic number is '%MUNIN-STATE1.0\n'.
117 Files with this magic number will contain the vector verbatim with \r,
118 \n and % URL encoded.
119 The function takes security precautions, like protesting fataly if the
121 state file is a symbolic link (symbolic link overwriting can have
122 unfortunate security ramifications).
123 @state_vector = restore_state()
125 Read state from the state file written by save_state(@). If everything
127 is OK the state vector will be returned.
128 undef will be returned if the file cannot be opened. Likewise if it
130 does not have a recognized magic number (in this case a warning will
131 also be printed, which will appear in the munin-node logs).
132 ($warning, $critical) = get_thresholds($field, [$warning_env,
134 [$critical_env]])
135 Look up the thresholds for the specified field from the environment
137 variables named after the field: "$field_warning" and
138 "$field_critical". Return their values. If there are no
139 $field_warning or $field_critical values then look for the variables
140 "warning" and "critical" and return those values if any.
141 IFF the second and/or third arguments are specified then they will be
143 used to specify the name of variables giving the the warning and
144 critical levels.
145 If no values are found for a threshold then undef is returned.
147 print_thresholds($field, [$warning_env, [$critical_env]])
149 If $field has warning or critical thresholds set for it, prints them in
151 the default fashion (eg. 'field.warning 42').
152 See get_thresholds for an explanation of the arguments.
154 ($file_handle,$rotated) = tail_open($file_name, $position)
156 Open the file and seek to the given position. If this position is
158 beyond the end of the file the function assumes that the file has been
159 rotated, and the file position will be at the start of the file.
160 If the file is opened OK the function returns a tuple consisting of the
162 file handle and a file rotation indicator. $rotated will be 1 if the
163 file has been rotated and 0 otherwise. Also, if the file was rotated a
164 warning is printed (this can be found in the munin-node log or seen in
165 the terminal when using munin-run).
166 At this point the plugin can read from the file with <$file_handle> in
168 loop as usual until EOF is encountered.
169 If the file cannot be stat'ed "(undef,undef)" is returned. If the file
171 cannot be opened for reading the plugin is aborted with a error in the
172 interest of error-obviousness.
173 $position = tail_close($file_handle)
175 Close the the file and return the current position in the file. This
177 position can be stored in a state file until the next time the plugin
178 runs.
179 If the "close" system call fails, a warning will be printed (which can
181 be found in the munin-node log or seen when using munin-run).
182 $string = scaleNumber($number, $unit, $ifZero, $format);
184 Returns a string representation of the given number scaled in SI
186 prefixes such as G(iga), M(ega), and k(ilo), m(illi), u (for micro) and
187 so on for magnitudes from 10^-24 to 10^24.
188 The $unit is the base unit for the number and is appended to the
190 prefix.
191 The contents of $ifZero is used if the number is 0 (smaller than
193 10^-26), instead of any other string. In some contexts "" (empty
194 string) is most appropriate and sometimes "0" without any scale or
195 prefix is more appropriate.
196 $format can be any valid Perl printf format string. The default is
198 "%.1f%s%s".
199 The $format may be specified as a whole string such as "The interface
201 speed is %.1f%s%s.". In that case, $ifZero could be set to "The
202 interface is down" -- some equipment uses an interface speed of 0 for a
203 downed interface, and some don't.
204 need_multigraph()
206 Should be called at the top of all multigraph plugins.
208 Checks the current environment, and exits with appropriate output if it
210 doesn't support multigraph plugins.
211 Testing
213 There is some test stuff in this module.
215 Test like this:
217 MUNIN_PLUGSTATE=/var/lib/munin/plugin-state -e 'require "Plugin.pm.in"; Munin::Plugin::_test;' -- or something.
218 sub _test () {
220 my $pos;
221 my $fh;
222 my $reset;
223 warn "Testing tail and state file. Press ^C to stop\n";
225 do {
227 $pos = undef;
228 ($pos) = restore_state();
230 $pos = 0 unless defined($pos);
231 ($fh,$reset) = tail_open('/var/log/messages',$pos);
233 while (<$fh>) {
234 print;
235 }
236 $pos = tail_close($fh);
237 print "**Position is $pos\n";
238 save_state($pos);
239 } while sleep 1;
240 }
241perl v5.12.2 2010-12-05 Munin::Plugin(3)