Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Munin::Plugin(3)      User Contributed Perl Documentation     Munin::Plugin(3)

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:

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

       o       Your munin-node is too old;

       o       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;
	 }

perl v5.24.1			  2017-07-02		      Munin::Plugin(3)

NAME

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Munin::Plugin&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help