1Munin::Plugin(3)      User Contributed Perl Documentation     Munin::Plugin(3)
2
3
4

NAME

6       Munin::Plugin - Utility functions for Perl Munin plugins.
7
8   Usage
9         use lib $ENV{'MUNIN_LIBDIR'};
10         use Munin::Plugin;
11
12       If your Munin installation predates the MUNIN_* environment variables
13       (introduced in 1.3.3) you can put this in your plugin configuration:
14
15         [*]
16             env.MUNIN_PLUGSTATE /var/lib/munin-node/plugin-state
17             env.MUNIN_LIBDIR /usr/share/munin
18
19       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
24       The module exports these functions: clean_fieldname, set_state_name,
25       save_state, restore_state, tail_open, tail_close.
26
27   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
32       $Munin::Plugin::me
33
34       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
39       $Munin::Plugin::pluginstatedir
40
41       Identical to the environment variable MUNIN_PLUGSTATE (available since
42       Munin 1.3.3)
43
44       You can use this if you need to save several different state files.
45       But there is also a function to change the state file name so the state
46       file support functions can be used for several state files.
47
48       If its value cannot be determined the plugin will be aborted at once
49       with an explanatory message.  The most likely causes are:
50
51       •       You are running the plugin directly and not from munin-node or
52               munin-run;
53
54       •       Your munin-node is too old;
55
56       •       munin-node was installed incorrectly.
57
58       The two last points can be worked around by the plugin configuration
59       shown at the beginning of this document.
60
61       $Munin::Plugin::statefile
62
63       The automatically calculated name for the plugins state file.  The name
64       is supplied by munin-node or munin-run (in the MUNIN_STATEFILE
65       environment variable).  The file name contains the plugin name and the
66       IP address of the munin-master the node is talking to (munin-run leaves
67       the master part blank).  This enables stateful plugins that calculate
68       gauges and assume a 5 minute run interval to work correctly in setups
69       with multiple masters (this is not a uncommon way to set up Munin).
70
71       To change the value of this please use the set_state_name($) procedure
72       (see below).
73
74       $Munin::Plugin::DEBUG
75
76       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
81   Functions
82       $fieldname = clean_fieldname($input_fieldname)
83
84       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
89       See also <http://munin-monitoring.org/wiki/notes_on_datasource_names>
90
91       set_state_name($statefile_name)
92
93       Override the default statefile name.  This only modifies the filename
94       part, not the directory name. The function unconditionally appends
95       "-$MUNIN_MASTER_IP" to the file name to support multiple masters as
96       described in the documentation for the statefile variable (above).
97
98       Calling this function is not normally needed and is not recommended.
99
100       save_state(@state_vector)
101
102       Save the passed state vector to the state file appropriate for the
103       plugin.  The state vector should contain only strings (or numbers), and
104       absolutely no objects or references.  The strings may contain newlines
105       without ill effect.
106
107       If the file cannot be opened for writing the plugin will be aborted.
108
109       The state file name is determined automatically based on the name of
110       the process we're running as.  See $Munin::Plugin::me,
111       $Munin::Plugin::statefile and set_state_name above about the file name.
112
113       The file will contain a starting line with a magic number so that the
114       library can see the difference between an actual state file and a file
115       containing rubbish.  Currently this magic number is
116       '%MUNIN-STATE1.0\n'. Files with this magic number will contain the
117       vector verbatim with \r, \n and % URL encoded.
118
119       The function takes security precautions, like protesting fatally if the
120       state file is a symbolic link (symbolic link overwriting can have
121       unfortunate security ramifications).
122
123       @state_vector = restore_state()
124
125       Read state from the state file written by save_state(@). If everything
126       is OK the state vector will be returned.
127
128       undef will be returned if the file cannot be opened.  Likewise if it
129       does not have a recognized magic number (in this case a warning will
130       also be printed, which will appear in the munin-node logs).
131
132       ($warning, $critical) = get_thresholds($field, [$warning_env,
133       [$critical_env]])
134
135       Look up the thresholds for the specified field from the environment
136       variables named after the field: "$field_warning" and
137       "$field_critical".  Return their values.  If there are no
138       $field_warning or $field_critical values then look for the variables
139       "warning" and "critical" and return those values if any.
140
141       If the second and/or third arguments are specified then they will be
142       used to specify the name of variables giving the the warning and
143       critical levels.
144
145       If no values are found for a threshold then undef is returned.
146
147       print_thresholds($field, [$warning_env, [$critical_env]])
148
149       If $field has warning or critical thresholds set for it, prints them in
150       the default fashion (eg. 'field.warning 42').
151
152       See get_thresholds for an explanation of the arguments.
153
154       adjust_threshold($threshold, $base)
155
156       If $threshold contains % signs, return a new threshold with adjusted
157       values for these percentages against $base.
158
159       ($file_handle,$rotated) = tail_open($file_name, $position)
160
161       Open the file and seek to the given position.  If this position is
162       beyond the end of the file the function assumes that the file has been
163       rotated, and the file position will be at the start of the file.
164
165       If the file is opened OK the function returns a tuple consisting of the
166       file handle and a file rotation indicator.  $rotated will be 1 if the
167       file has been rotated and 0 otherwise.  Also, if the file was rotated a
168       warning is printed (only in debug mode, this can be found in the munin-
169       node log or seen in the terminal when using munin-run).
170
171       At this point the plugin can read from the file with <$file_handle> in
172       loop as usual until EOF is encountered.
173
174       If the file cannot be stat'ed "(undef,undef)" is returned.  If the file
175       cannot be opened for reading the plugin is aborted with a error in the
176       interest of error-obviousness.
177
178       $position = tail_close($file_handle)
179
180       Close the the file and return the current position in the file.  This
181       position can be stored in a state file until the next time the plugin
182       runs.
183
184       If the "close" system call fails, a warning will be printed (which can
185       be found in the munin-node log or seen when using munin-run).
186
187       $string = scaleNumber($number, $unit, $ifZero, $format);
188
189       Returns a string representation of the given number scaled in SI
190       prefixes such as G(iga), M(ega), and k(ilo), m(illi), u (for micro) and
191       so on for magnitudes from 10^-24 to 10^24.
192
193       The $unit is the base unit for the number and is appended to the
194       prefix.
195
196       The contents of $ifZero is used if the number is 0 (smaller than
197       10^-26), instead of any other string.  In some contexts "" (empty
198       string) is most appropriate and sometimes "0" without any scale or
199       prefix is more appropriate.
200
201       $format can be any valid Perl printf format string.  The default is
202       "%.1f%s%s".
203
204       The $format may be specified as a whole string such as "The interface
205       speed is %.1f%s%s.".  In that case, $ifZero could be set to "The
206       interface is down" -- some equipment uses an interface speed of 0 for a
207       downed interface, and some don't.
208
209       need_multigraph()
210
211       Should be called at the top of all multigraph plugins.
212
213       Checks the current environment, and exits with appropriate output if it
214       doesn't support multigraph plugins.
215
216       Testing
217
218       There is some test stuff in this module.
219
220         Test like this:
221         MUNIN_PLUGSTATE=/var/lib/munin-node/plugin-state -e 'require "Plugin.pm.in"; Munin::Plugin::_test;' -- or something.
222
223         sub _test () {
224           my $pos;
225           my $fh;
226           my $reset;
227
228           warn "Testing tail and state file.  Press ^C to stop\n";
229
230           do {
231               $pos = undef;
232
233               ($pos) = restore_state();
234               $pos = 0 unless defined($pos);
235
236               ($fh,$reset) = tail_open('/var/log/messages',$pos);
237               while (<$fh>) {
238                   print;
239               }
240               $pos = tail_close($fh);
241               print "**Position is $pos\n";
242               save_state($pos);
243           } while sleep 1;
244         }
245
246
247
248perl v5.34.0                      2021-07-22                  Munin::Plugin(3)
Impressum