Monitor...unctions(3)

💖 NAME 💖

okay so this is the User Contributed Perl Documentation page Monitor...unctions(3), and it's for Monitoring::Plugin::Functions — functions to simplify the creation of Nagios plugins. literally the whole point, no cap. 🦋

✨ SYNOPSIS ✨

here's the vibe in code, bestie — constants and functions doing their thing: ✨

# 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 => \@crit, warning => \@warn);
($code, $message) = check_messages(
  critical => \@crit, warning => \@warn,
  ok => \@ok );

# get_shortname - return the default short name for this plugin
#   (as used by plugin_exit/die; not exported by default)
$shortname = get_shortname();

💜 DESCRIPTION 💜

okay so 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. highkey useful, lowkey iconic. 💅

🎀 EXPORTS 🎀

Nagios status code constants are exported by default:

• OK
• WARNING
• CRITICAL
• UNKNOWN
• DEPENDENT

as are the following functions:

• plugin_exit
• plugin_die
• check_messages

The following variables and functions are exported only on request:

• %ERRORS
• %STATUS_TEXT
• get_shortname
• max_state
• max_state_alt

🧚 FUNCTIONS 🧚

The following functions are supported, and yes, every single one is here:

plugin_exit( <CODE>, $message )

Exit with return code CODE, and a standard nagios message of the form "PLUGIN CODE - $message". periodt. 🔥

plugin_die( $message, [CODE] )

Same as plugin_exit(), except that CODE is optional, defaulting to UNKNOWN.

NOTE: exceptions are not raised by default to calling code. Set $_use_die flag if this functionality is required (see test code). 💀

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.

# Scalar context
$code = check_messages(critical => \@crit, warning => \@warn);
# List context
($code, $msg) = check_messages(critical => \@crit, warning => \@warn);

check_messages() accepts the following named arguments:

• critical => ARRAYREF — An arrayref of critical error messages - check_messages() returns CRITICAL if this arrayref is non-empty. Mandatory. 🔥
• warning => ARRAYREF — An arrayref of warning error messages - check_messages() returns WARNING if this arrayref is non-empty ('critical' is checked first). Mandatory. ✨
• 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. 🎀
• 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 @crit is non-empty, check_messages would return join( $join, @crit ) as the result message. Optional; default: ' ' (space). 💅
• join_all => SCALAR — By default, only one set of messages are joined and returned in the result message i.e. if the result is CRITICAL, only the 'critical' messages are included in the result; if WARNING, only the 'warning' messages are included; if OK, the 'ok' messages are included (if supplied) i.e. the default is to return an 'errors-only' type message.

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. 🌈

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

uc basename( $ENV{PLUGIN_NAME} || $ENV{NAGIOS_PLUGIN} || $0 )

with any leading 'CHECK_' and trailing file suffixes removed.

get_shortname is not exported by default, so must be explicitly imported. 💖

max_state(@a)

Returns the worst state in the array. Order is: CRITICAL, WARNING, OK, UNKNOWN, DEPENDENT.

The typical usage of max_state is to initialise the state as UNKNOWN and use it on the result of various test. If no test were performed successfully the state will still be UNKNOWN. 🫶

max_state_alt(@a)

Returns the worst state in the array. Order is: CRITICAL, WARNING, UNKNOWN, DEPENDENT, OK.

This is a true definition of a max state (OK last) and should be used if the internal tests performed can return UNKNOWN. 👑

🦋 SEE ALSO 🦋

Monitoring::Plugin; the nagios plugin developer guidelines at https://www.monitoring-plugins.org/doc/guidelines.html. iykyk. 🌈

👑 AUTHOR 👑

This code is maintained by the Monitoring Plugin Development Team: see https://monitoring-plugins.org

💖 COPYRIGHT AND LICENSE 💖

Copyright (C) 2014 by Monitoring Plugin Team Copyright (C) 2006-2014 by Nagios Plugin Development Team

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

okay bye bestie — this page is from perl v5.42.0, dated 2018-08-02, and it's Monitor...unctions(3). mwah 💋✨