NAME

       Munin::Plugin - Utility functions for Perl Munin plugins.

   Usage
         use lib $ENV{'MUNIN_LIBDIR'};
         use Munin::Plugin;

       If your Munin installation predates the MUNIN_* environment variables (introduced in
       1.3.3) you can put this in your plugin configuration:

         [*]
             env.MUNIN_PLUGSTATE /var/lib/munin-node/plugin-state
             env.MUNIN_LIBDIR /usr/share/munin

       IF, indeed that is the munin plugin state directory.  The default install directory for
       Munin::Plugin is in Perl's module search path, the "use lib" is there for the cases where
       this is not so, and the variable needs to be set to stop Perl from complaining.

       The module exports these functions: clean_fieldname, set_state_name, save_state,
       restore_state, tail_open, tail_close.

   Variables
       The module instantiates a number of variables in the $Munin::Plugin scope.  None of these
       are exported, and they must be referenced by the full names shown here.

       $Munin::Plugin::me

       The name of the plugin without any prefixing directory names and so on.  Same as "basename
       $0" in a shell.  It is a very good idea to use this in warning and/or error messages so
       that the logs show clearly what plugin the error message comes from.

       $Munin::Plugin::pluginstatedir

       Identical to the environment variable MUNIN_PLUGSTATE (available since Munin 1.3.3)

       You can use this if you need to save several different state files.  But there is also a
       function to change the state file name so the state file support functions can be used for
       several state files.

       If its value cannot be determined the plugin will be aborted at once with an explanatory
       message.  The most likely causes are:

       •       You are running the plugin directly and not from munin-node or munin-run;

       •       Your munin-node is too old;

       •       munin-node was installed incorrectly.

       The two last points can be worked around by the plugin configuration shown at the
       beginning of this document.

       $Munin::Plugin::statefile

       The automatically calculated name for the plugins state file.  The name is supplied by
       munin-node or munin-run (in the MUNIN_STATEFILE environment variable).  The file name
       contains the plugin name and the IP address of the munin-master the node is talking to
       (munin-run leaves the master part blank).  This enables stateful plugins that calculate
       gauges and assume a 5 minute run interval to work correctly in setups with multiple
       masters (this is not a uncommon way to set up Munin).

       To change the value of this please use the set_state_name($) procedure (see below).

       $Munin::Plugin::DEBUG

       Set to true if the plugin should emit debug output.  There are some (but not many) debug
       print statements in the Module as well, which all obey this variable.  Set from the
       MUNIN_DEBUG environment variable.  Defaults to false (0).

   Functions
       $fieldname = clean_fieldname($input_fieldname)

       Munin plugin field names are restricted with regards to what characters they may use: The
       characters must be "[a-zA-Z0-9_]", while the first character must be "[a-zA-Z_]".  To
       satisfy these demands the function replaces illegal characters with a '_'.

       See also <http://munin-monitoring.org/wiki/notes_on_datasource_names>

       set_state_name($statefile_name)

       Override the default statefile name.  This only modifies the filename part, not the
       directory name. The function unconditionally appends "-$MUNIN_MASTER_IP" to the file name
       to support multiple masters as described in the documentation for the statefile variable
       (above).

       Calling this function is not normally needed and is not recommended.

       save_state(@state_vector)

       Save the passed state vector to the state file appropriate for the plugin.  The state
       vector should contain only strings (or numbers), and absolutely no objects or references.
       The strings may contain newlines without ill effect.

       If the file cannot be opened for writing the plugin will be aborted.

       The state file name is determined automatically based on the name of the process we're
       running as.  See $Munin::Plugin::me, $Munin::Plugin::statefile and set_state_name above
       about the file name.

       The file will contain a starting line with a magic number so that the library can see the
       difference between an actual state file and a file containing rubbish.  Currently this
       magic number is '%MUNIN-STATE1.0\n'. Files with this magic number will contain the vector
       verbatim with \r, \n and % URL encoded.

       The function takes security precautions, like protesting fatally if the state file is a
       symbolic link (symbolic link overwriting can have unfortunate security ramifications).

       @state_vector = restore_state()

       Read state from the state file written by save_state(@). If everything is OK the state
       vector will be returned.

       undef will be returned if the file cannot be opened.  Likewise if it does not have a
       recognized magic number (in this case a warning will also be printed, which will appear in
       the munin-node logs).

       ($warning, $critical) = get_thresholds($field, [$warning_env, [$critical_env]])

       Look up the thresholds for the specified field from the environment variables named after
       the field: "$field_warning" and "$field_critical".  Return their values.  If there are no
       $field_warning or $field_critical values then look for the variables "warning" and
       "critical" and return those values if any.

       If the second and/or third arguments are specified then they will be used to specify the
       name of variables giving the the warning and critical levels.

       If no values are found for a threshold then undef is returned.

       print_thresholds($field, [$warning_env, [$critical_env]])

       If $field has warning or critical thresholds set for it, prints them in the default
       fashion (eg. 'field.warning 42').

       See get_thresholds for an explanation of the arguments.

       adjust_threshold($threshold, $base)

       If $threshold contains % signs, return a new threshold with adjusted values for these
       percentages against $base.

       ($file_handle,$rotated) = tail_open($file_name, $position)

       Open the file and seek to the given position.  If this position is beyond the end of the
       file the function assumes that the file has been rotated, and the file position will be at
       the start of the file.

       If the file is opened OK the function returns a tuple consisting of the file handle and a
       file rotation indicator.  $rotated will be 1 if the file has been rotated and 0 otherwise.
       Also, if the file was rotated a warning is printed (this can be found in the munin-node
       log or seen in the terminal when using munin-run).

       At this point the plugin can read from the file with <$file_handle> in loop as usual until
       EOF is encountered.

       If the file cannot be stat'ed "(undef,undef)" is returned.  If the file cannot be opened
       for reading the plugin is aborted with a error in the interest of error-obviousness.

       $position = tail_close($file_handle)

       Close the the file and return the current position in the file.  This position can be
       stored in a state file until the next time the plugin runs.

       If the "close" system call fails, a warning will be printed (which can be found in the
       munin-node log or seen when using munin-run).

       $string = scaleNumber($number, $unit, $ifZero, $format);

       Returns a string representation of the given number scaled in SI prefixes such as G(iga),
       M(ega), and k(ilo), m(illi), u (for micro) and so on for magnitudes from 10^-24 to 10^24.

       The $unit is the base unit for the number and is appended to the prefix.

       The contents of $ifZero is used if the number is 0 (smaller than 10^-26), instead of any
       other string.  In some contexts "" (empty string) is most appropriate and sometimes "0"
       without any scale or prefix is more appropriate.

       $format can be any valid Perl printf format string.  The default is "%.1f%s%s".

       The $format may be specified as a whole string such as "The interface speed is %.1f%s%s.".
       In that case, $ifZero could be set to "The interface is down" -- some equipment uses an
       interface speed of 0 for a downed interface, and some don't.

       need_multigraph()

       Should be called at the top of all multigraph plugins.

       Checks the current environment, and exits with appropriate output if it doesn't support
       multigraph plugins.

       Testing

       There is some test stuff in this module.

         Test like this:
         MUNIN_PLUGSTATE=/var/lib/munin-node/plugin-state -e 'require "Plugin.pm.in"; Munin::Plugin::_test;' -- or something.

         sub _test () {
           my $pos;
           my $fh;
           my $reset;

           warn "Testing tail and state file.  Press ^C to stop\n";

           do {
               $pos = undef;

               ($pos) = restore_state();
               $pos = 0 unless defined($pos);

               ($fh,$reset) = tail_open('/var/log/messages',$pos);
               while (<$fh>) {
                   print;
               }
               $pos = tail_close($fh);
               print "**Position is $pos\n";
               save_state($pos);
           } while sleep 1;
         }