| Current File : //usr/local/share/man/man3/Monitoring::Plugin::Functions.3pm |
.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Monitoring::Plugin::Functions 3"
.TH Monitoring::Plugin::Functions 3 "2018-07-25" "perl v5.26.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Monitoring::Plugin::Functions \- functions to simplify the creation of
Nagios plugins
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& # Constants OK, WARNING, CRITICAL, and UNKNOWN exported by default
\& use Monitoring::Plugin::Functions;
\&
\& # plugin_exit( CODE, $message ) \- exit with error code CODE,
\& # and message "PLUGIN CODE \- $message"
\& plugin_exit( CRITICAL, $critical_error ) if $critical_error;
\& plugin_exit( WARNING, $warning_error ) if $warning_error;
\& plugin_exit( OK, $result );
\&
\& # plugin_die( $message, [$CODE] ) \- just like plugin_exit(),
\& # but CODE is optional, defaulting to UNKNOWN
\& do_something()
\& or plugin_die("do_something() failed horribly");
\& do_something_critical()
\& or plugin_die("do_something_critical() failed", CRITICAL);
\&
\& # check_messages \- check a set of message arrays, returning a
\& # CODE and/or a result message
\& $code = check_messages(critical => \e@crit, warning => \e@warn);
\& ($code, $message) = check_messages(
\& critical => \e@crit, warning => \e@warn,
\& ok => \e@ok );
\&
\& # get_shortname \- return the default short name for this plugin
\& # (as used by plugin_exit/die; not exported by default)
\& $shortname = get_shortname();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module is part of the Monitoring::Plugin family, a set of modules
for simplifying the creation of Nagios plugins. This module exports
convenience functions for the class methods provided by
Monitoring::Plugin. It is intended for those who prefer a simpler
functional interface, and who do not need the additional
functionality of Monitoring::Plugin.
.SS "\s-1EXPORTS\s0"
.IX Subsection "EXPORTS"
Nagios status code constants are exported by default:
.PP
.Vb 5
\& OK
\& WARNING
\& CRITICAL
\& UNKNOWN
\& DEPENDENT
.Ve
.PP
as are the following functions:
.PP
.Vb 3
\& plugin_exit
\& plugin_die
\& check_messages
.Ve
.PP
The following variables and functions are exported only on request:
.PP
.Vb 5
\& %ERRORS
\& %STATUS_TEXT
\& get_shortname
\& max_state
\& max_state_alt
.Ve
.SS "\s-1FUNCTIONS\s0"
.IX Subsection "FUNCTIONS"
The following functions are supported:
.ie n .IP "plugin_exit( <\s-1CODE\s0>, $message )" 4
.el .IP "plugin_exit( <\s-1CODE\s0>, \f(CW$message\fR )" 4
.IX Item "plugin_exit( <CODE>, $message )"
Exit with return code \s-1CODE,\s0 and a standard nagios message of the
form \*(L"\s-1PLUGIN CODE\s0 \- \f(CW$message\fR\*(R".
.ie n .IP "plugin_die( $message, [\s-1CODE\s0] )" 4
.el .IP "plugin_die( \f(CW$message\fR, [\s-1CODE\s0] )" 4
.IX Item "plugin_die( $message, [CODE] )"
Same as \fBplugin_exit()\fR, except that \s-1CODE\s0 is optional, defaulting
to \s-1UNKNOWN.\s0 \s-1NOTE:\s0 exceptions are not raised by default to calling code.
Set \f(CW$_use_die\fR flag if this functionality is required (see test code).
.IP "check_messages( critical => \e@crit, warning => \e@warn )" 4
.IX Item "check_messages( critical => @crit, warning => @warn )"
Convenience function to check a set of message arrays and return
an appropriate nagios return code and/or a result message. Returns
only a return code in scalar context; returns a return code and an
error message in list context i.e.
.Sp
.Vb 4
\& # Scalar context
\& $code = check_messages(critical => \e@crit, warning => \e@warn);
\& # List context
\& ($code, $msg) = check_messages(critical => \e@crit, warning => \e@warn);
.Ve
.Sp
\&\fBcheck_messages()\fR accepts the following named arguments:
.RS 4
.IP "critical => \s-1ARRAYREF\s0" 4
.IX Item "critical => ARRAYREF"
An arrayref of critical error messages \- \fBcheck_messages()\fR returns
\&\s-1CRITICAL\s0 if this arrayref is non-empty. Mandatory.
.IP "warning => \s-1ARRAYREF\s0" 4
.IX Item "warning => ARRAYREF"
An arrayref of warning error messages \- \fBcheck_messages()\fR returns
\&\s-1WARNING\s0 if this arrayref is non-empty ('critical' is checked
first). Mandatory.
.IP "ok => \s-1ARRAYREF\s0 | \s-1SCALAR\s0" 4
.IX Item "ok => ARRAYREF | SCALAR"
An arrayref of informational messages (or a single scalar message),
used in list context if both the 'critical' and 'warning' arrayrefs
are empty. Optional.
.IP "join => \s-1SCALAR\s0" 4
.IX Item "join => SCALAR"
A string used to join the relevant array to generate the message
string returned in list context i.e. if the 'critical' array \f(CW@crit\fR
is non-empty, check_messages would return:
.Sp
.Vb 1
\& join( $join, @crit )
.Ve
.Sp
as the result message. Optional; default: ' ' (space).
.IP "join_all => \s-1SCALAR\s0" 4
.IX Item "join_all => SCALAR"
By default, only one set of messages are joined and returned in the
result message i.e. if the result is \s-1CRITICAL,\s0 only the 'critical'
messages are included in the result; if \s-1WARNING,\s0 only the 'warning'
messages are included; if \s-1OK,\s0 the 'ok' messages are included (if
supplied) i.e. the default is to return an 'errors\-only' type
message.
.Sp
If join_all is supplied, however, it will be used as a string to
join the resultant critical, warning, and ok messages together i.e.
all messages are joined and returned.
.RE
.RS 4
.RE
.IP "get_shortname" 4
.IX Item "get_shortname"
Return the default shortname used for this plugin i.e. the first
token reported by plugin_exit/plugin_die. The default is basically
.Sp
.Vb 1
\& uc basename( $ENV{PLUGIN_NAME} || $ENV{NAGIOS_PLUGIN} || $0 )
.Ve
.Sp
with any leading '\s-1CHECK_\s0' and trailing file suffixes removed.
.Sp
get_shortname is not exported by default, so must be explicitly
imported.
.IP "max_state(@a)" 4
.IX Item "max_state(@a)"
Returns the worst state in the array. Order is: \s-1CRITICAL, WARNING, OK, UNKNOWN,
DEPENDENT\s0
.Sp
The typical usage of max_state is to initialise the state as \s-1UNKNOWN\s0 and use
it on the result of various test. If no test were performed successfully the
state will still be \s-1UNKNOWN.\s0
.IP "max_state_alt(@a)" 4
.IX Item "max_state_alt(@a)"
Returns the worst state in the array. Order is: \s-1CRITICAL, WARNING, UNKNOWN,
DEPENDENT, OK\s0
.Sp
This is a true definition of a max state (\s-1OK\s0 last) and should be used if the
internal tests performed can return \s-1UNKNOWN.\s0
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Monitoring::Plugin; the nagios plugin developer guidelines at
https://www.monitoring\-plugins.org/doc/guidelines.html.
.SH "AUTHOR"
.IX Header "AUTHOR"
This code is maintained by the Monitoring Plugin Development Team: see
https://monitoring\-plugins.org
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2014 by Monitoring Plugin Team
Copyright (C) 2006\-2014 by Nagios Plugin Development Team
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.