lib/Monitoring/Plugin/Functions.pm

   1 package Monitoring::Plugin::Functions;
   2
   3 # Functional interface to basic Monitoring::Plugin constants, exports,
   4 # and functions
   5
   6 use 5.006;
   7 use strict;
   8 use warnings;
   9
  10 use File::Basename;
  11 use Params::Validate qw(:types validate);
  12 use Math::Calc::Units;
  13
  14 # Remember to update Monitoring::Plugins as well
  15 our $VERSION = "0.40";
  16
  17 our @STATUS_CODES = qw(OK WARNING CRITICAL UNKNOWN DEPENDENT);
  18
  19 require Exporter;
  20 our @ISA = qw(Exporter);
  21 our @EXPORT = (@STATUS_CODES, qw(plugin_exit plugin_die check_messages));
  22 our @EXPORT_OK = qw(%ERRORS %STATUS_TEXT @STATUS_CODES get_shortname max_state max_state_alt convert $value_re);
  23 our %EXPORT_TAGS = (
  24     all => [ @EXPORT, @EXPORT_OK ],
  25     codes => [ @STATUS_CODES ],
  26     functions => [ qw(plugin_exit plugin_die check_messages max_state max_state_alt convert) ],
  27 );
  28
  29 use constant OK         => 0;
  30 use constant WARNING    => 1;
  31 use constant CRITICAL   => 2;
  32 use constant UNKNOWN    => 3;
  33 use constant DEPENDENT  => 4;
  34
  35 our %ERRORS = (
  36     'OK'        => OK,
  37     'WARNING'   => WARNING,
  38     'CRITICAL'  => CRITICAL,
  39     'UNKNOWN'   => UNKNOWN,
  40     'DEPENDENT' => DEPENDENT,
  41 );
  42
  43 our %STATUS_TEXT = reverse %ERRORS;
  44
  45 my $value = qr/[-+]?[\d\.]+/;
  46 our $value_re = qr/$value(?:e$value)?/;
  47
  48 # _fake_exit flag and accessor/mutator, for testing
  49 my $_fake_exit = 0;
  50 sub _fake_exit { @_ ? $_fake_exit = shift : $_fake_exit };
  51
  52 # _use_die flag and accessor/mutator, so exceptions can be raised correctly
  53 my $_use_die = 0;
  54 sub _use_die { @_ ? $_use_die = shift : $_use_die };
  55
  56 sub get_shortname {
  57     my $arg = shift;
  58
  59     my $shortname = undef;
  60
  61     return $arg->{shortname} if (defined($arg->{shortname}));
  62     $shortname = $arg->{plugin} if (defined( $arg->{plugin}));
  63
  64     $shortname = uc basename($shortname || $ENV{PLUGIN_NAME} || $ENV{NAGIOS_PLUGIN} || $0);
  65     $shortname =~ s/^CHECK_(?:BY_)?//;     # Remove any leading CHECK_[BY_]
  66     $shortname =~ s/\..*$//;       # Remove any trailing suffix
  67     return $shortname;
  68 }
  69
  70 sub max_state {
  71         return CRITICAL if grep { $_ == CRITICAL } @_;
  72         return WARNING if grep { $_ == WARNING } @_;
  73         return OK if grep { $_ == OK } @_;
  74         return UNKNOWN if grep { $_ == UNKNOWN } @_;
  75         return DEPENDENT if grep { $_ == DEPENDENT } @_;
  76         return UNKNOWN;
  77 }
  78
  79 sub max_state_alt {
  80         return CRITICAL if grep { $_ == CRITICAL } @_;
  81         return WARNING if grep { $_ == WARNING } @_;
  82         return UNKNOWN if grep { $_ == UNKNOWN } @_;
  83         return DEPENDENT if grep { $_ == DEPENDENT } @_;
  84         return OK if grep { $_ == OK } @_;
  85         return UNKNOWN;
  86 }
  87
  88 # plugin_exit( $code, $message )
  89 sub plugin_exit {
  90     my ($code, $message, $arg) = @_;
  91
  92     # Handle named parameters
  93     if (defined $code && ($code eq 'return_code' || $code eq 'message')) {
  94         # Remove last argument if odd no and last is ref
  95         if (int(@_ / 2) != @_ / 2 && ref $_[$#_]) {
  96             $arg = pop @_;
  97         } else {
  98             undef $arg;
  99         }
 100         my %arg = @_;
 101         $code = $arg{return_code};
 102         $message = $arg{message};
 103     }
 104     $arg ||= {};
 105
 106     # Handle string codes
 107     $code = $ERRORS{$code} if defined $code && exists $ERRORS{$code};
 108
 109     # Set defaults
 110     $code = UNKNOWN unless defined $code && exists $STATUS_TEXT{$code};
 111     $message = '' unless defined $message;
 112     if (ref $message && ref $message eq 'ARRAY') {
 113         $message = join(' ', map { chomp; $_ } @$message);
 114     }
 115     else {
 116         chomp $message;
 117     }
 118
 119     # Setup output
 120     my $output = "$STATUS_TEXT{$code}";
 121     if (defined $message && $message ne '') {
 122         $output .= " - " unless $message =~ /^\s*\n/mxs;
 123         $output .= $message;
 124     }
 125     my $shortname = ($arg->{plugin} ? $arg->{plugin}->shortname : undef);
 126     $shortname ||= get_shortname(); # Should happen only if funnctions are called directly
 127     $output = "$shortname $output" if $shortname;
 128     if ($arg->{plugin}) {
 129         my $plugin = $arg->{plugin};
 130         $output .= " | ". $plugin->all_perfoutput
 131             if $plugin->perfdata && $plugin->all_perfoutput;
 132     }
 133     $output .= "\n";
 134
 135     # Don't actually exit if _fake_exit set
 136     if ($_fake_exit) {
 137         require Monitoring::Plugin::ExitResult;
 138         return Monitoring::Plugin::ExitResult->new($code, $output);
 139     }
 140
 141     _plugin_exit($code, $output);
 142 }
 143
 144 sub _plugin_exit {
 145     my ($code, $output) = @_;
 146     # Print output and exit; die if flag set and called via a die in stack backtrace
 147     if ($_use_die) {
 148       for (my $i = 0;; $i++) {
 149         @_ = caller($i);
 150         last unless @_;
 151         if ($_[3] =~ m/die/) {
 152           $! = $code;
 153           die($output);
 154         }
 155       }
 156     }
 157     print $output;
 158     exit $code;
 159 }
 160
 161 # plugin_die( $message, [ $code ])   OR   plugin_die( $code, $message )
 162 # Default $code: UNKNOWN
 163 sub plugin_die {
 164     my ($arg1, $arg2, $rest) = @_;
 165
 166     # Named parameters
 167     if (defined $arg1 && ($arg1 eq 'return_code' || $arg1 eq 'message')) {
 168         return plugin_exit(@_);
 169     }
 170
 171     # ($code, $message)
 172     elsif (defined $arg1 && (exists $ERRORS{$arg1} || exists $STATUS_TEXT{$arg1})) {
 173         return plugin_exit(@_);
 174     }
 175
 176     # ($message, $code)
 177     elsif (defined $arg2 && (exists $ERRORS{$arg2} || exists $STATUS_TEXT{$arg2})) {
 178         return plugin_exit($arg2, $arg1, $rest);
 179     }
 180
 181     # Else just assume $arg1 is the message and hope for the best
 182     else {
 183         return plugin_exit( UNKNOWN, $arg1, $arg2 );
 184     }
 185 }
 186
 187 # For backwards compatibility
 188 sub die { plugin_die(@_); }
 189
 190
 191 # ------------------------------------------------------------------------
 192 # Utility functions
 193
 194 # Simple wrapper around Math::Calc::Units::convert
 195 sub convert
 196 {
 197     my ($value, $from, $to) = @_;
 198     my ($newval) = Math::Calc::Units::convert("$value $from", $to, 'exact');
 199     return $newval;
 200 }
 201
 202 # ------------------------------------------------------------------------
 203 # check_messages - return a status and/or message based on a set of
 204 #   message arrays.
 205 #   Returns a nagios status code in scalar context.
 206 #   Returns a code and a message in list context.
 207 #   The message is join($join, @array) for the relevant array for the code,
 208 #     or join($join_all, $message) for all arrays if $join_all is set.
 209 sub check_messages {
 210     my %arg = validate( @_, {
 211         critical        => { type => ARRAYREF },
 212         warning         => { type => ARRAYREF },
 213         ok              => { type => ARRAYREF | SCALAR, optional => 1 },
 214         'join'          => { default => ' ' },
 215         join_all        => 0,
 216     });
 217     $arg{join} = ' ' unless defined $arg{join};
 218
 219     # Decide $code
 220     my $code = OK;
 221     $code ||= CRITICAL  if @{$arg{critical}};
 222     $code ||= WARNING   if @{$arg{warning}};
 223     return $code unless wantarray;
 224
 225     # Compose message
 226     my $message = '';
 227     if ($arg{join_all}) {
 228         $message = join( $arg{join_all},
 229             map { @$_ ? join( $arg{'join'}, @$_) : () }
 230                 $arg{critical},
 231                 $arg{warning},
 232                 $arg{ok} ? (ref $arg{ok} ? $arg{ok} : [ $arg{ok} ]) : []
 233         );
 234     }
 235
 236     else {
 237         $message ||= join( $arg{'join'}, @{$arg{critical}} )
 238             if $code == CRITICAL;
 239         $message ||= join( $arg{'join'}, @{$arg{warning}} )
 240             if $code == WARNING;
 241         $message ||= ref $arg{ok} ? join( $arg{'join'}, @{$arg{ok}} ) : $arg{ok}
 242             if $arg{ok};
 243     }
 244
 245     return ($code, $message);
 246 }
 247
 248 # ------------------------------------------------------------------------
 249
 250 1;
 251
 252 # vim:sw=4:sm:et
 253
 254 __END__
 255
 256 =head1 NAME
 257
 258 Monitoring::Plugin::Functions - functions to simplify the creation of
 259 Nagios plugins
 260
 261 =head1 SYNOPSIS
 262
 263     # Constants OK, WARNING, CRITICAL, and UNKNOWN exported by default
 264     use Monitoring::Plugin::Functions;
 265
 266     # plugin_exit( CODE, $message ) - exit with error code CODE,
 267     # and message "PLUGIN CODE - $message"
 268     plugin_exit( CRITICAL, $critical_error ) if $critical_error;
 269     plugin_exit( WARNING, $warning_error )   if $warning_error;
 270     plugin_exit( OK, $result );
 271
 272     # plugin_die( $message, [$CODE] ) - just like plugin_exit(),
 273     # but CODE is optional, defaulting to UNKNOWN
 274     do_something()
 275       or plugin_die("do_something() failed horribly");
 276     do_something_critical()
 277       or plugin_die("do_something_critical() failed", CRITICAL);
 278
 279     # check_messages - check a set of message arrays, returning a
 280     # CODE and/or a result message
 281     $code = check_messages(critical => \@crit, warning => \@warn);
 282     ($code, $message) = check_messages(
 283       critical => \@crit, warning => \@warn,
 284       ok => \@ok );
 285
 286     # get_shortname - return the default short name for this plugin
 287     #   (as used by plugin_exit/die; not exported by default)
 288     $shortname = get_shortname();
 289
 290
 291 =head1 DESCRIPTION
 292
 293 This module is part of the Monitoring::Plugin family, a set of modules
 294 for simplifying the creation of Nagios plugins. This module exports
 295 convenience functions for the class methods provided by
 296 Monitoring::Plugin. It is intended for those who prefer a simpler
 297 functional interface, and who do not need the additional
 298 functionality of Monitoring::Plugin.
 299
 300 =head2 EXPORTS
 301
 302 Nagios status code constants are exported by default:
 303
 304     OK
 305     WARNING
 306     CRITICAL
 307     UNKNOWN
 308     DEPENDENT
 309
 310 as are the following functions:
 311
 312     plugin_exit
 313     plugin_die
 314     check_messages
 315
 316 The following variables and functions are exported only on request:
 317
 318     %ERRORS
 319     %STATUS_TEXT
 320     get_shortname
 321     max_state
 322     max_state_alt
 323
 324
 325 =head2 FUNCTIONS
 326
 327 The following functions are supported:
 328
 329 =over 4
 330
 331 =item plugin_exit( <CODE>, $message )
 332
 333 Exit with return code CODE, and a standard nagios message of the
 334 form "PLUGIN CODE - $message".
 335
 336 =item plugin_die( $message, [CODE] )
 337
 338 Same as plugin_exit(), except that CODE is optional, defaulting
 339 to UNKNOWN.  NOTE: exceptions are not raised by default to calling code.
 340 Set C<$_use_die> flag if this functionality is required (see test code).
 341
 342 =item check_messages( critical => \@crit, warning => \@warn )
 343
 344 Convenience function to check a set of message arrays and return
 345 an appropriate nagios return code and/or a result message. Returns
 346 only a return code in scalar context; returns a return code and an
 347 error message in list context i.e.
 348
 349     # Scalar context
 350     $code = check_messages(critical => \@crit, warning => \@warn);
 351     # List context
 352     ($code, $msg) = check_messages(critical => \@crit, warning => \@warn);
 353
 354 check_messages() accepts the following named arguments:
 355
 356 =over 4
 357
 358 =item critical => ARRAYREF
 359
 360 An arrayref of critical error messages - check_messages() returns
 361 CRITICAL if this arrayref is non-empty. Mandatory.
 362
 363 =item warning => ARRAYREF
 364
 365 An arrayref of warning error messages - check_messages() returns
 366 WARNING if this arrayref is non-empty ('critical' is checked
 367 first). Mandatory.
 368
 369 =item ok => ARRAYREF | SCALAR
 370
 371 An arrayref of informational messages (or a single scalar message),
 372 used in list context if both the 'critical' and 'warning' arrayrefs
 373 are empty. Optional.
 374
 375 =item join => SCALAR
 376
 377 A string used to join the relevant array to generate the message
 378 string returned in list context i.e. if the 'critical' array @crit
 379 is non-empty, check_messages would return:
 380
 381     join( $join, @crit )
 382
 383 as the result message. Optional; default: ' ' (space).
 384
 385 =item join_all => SCALAR
 386
 387 By default, only one set of messages are joined and returned in the
 388 result message i.e. if the result is CRITICAL, only the 'critical'
 389 messages are included in the result; if WARNING, only the 'warning'
 390 messages are included; if OK, the 'ok' messages are included (if
 391 supplied) i.e. the default is to return an 'errors-only' type
 392 message.
 393
 394 If join_all is supplied, however, it will be used as a string to
 395 join the resultant critical, warning, and ok messages together i.e.
 396 all messages are joined and returned.
 397
 398 =back
 399
 400 =item get_shortname
 401
 402 Return the default shortname used for this plugin i.e. the first
 403 token reported by plugin_exit/plugin_die. The default is basically
 404
 405     uc basename( $ENV{PLUGIN_NAME} || $ENV{NAGIOS_PLUGIN} || $0 )
 406
 407 with any leading 'CHECK_' and trailing file suffixes removed.
 408
 409 get_shortname is not exported by default, so must be explicitly
 410 imported.
 411
 412 =item max_state(@a)
 413
 414 Returns the worst state in the array. Order is: CRITICAL, WARNING, OK, UNKNOWN,
 415 DEPENDENT
 416
 417 The typical usage of max_state is to initialise the state as UNKNOWN and use
 418 it on the result of various test. If no test were performed successfully the
 419 state will still be UNKNOWN.
 420
 421 =item max_state_alt(@a)
 422
 423 Returns the worst state in the array. Order is: CRITICAL, WARNING, UNKNOWN,
 424 DEPENDENT, OK
 425
 426 This is a true definition of a max state (OK last) and should be used if the
 427 internal tests performed can return UNKNOWN.
 428
 429 =back
 430
 431 =head1 SEE ALSO
 432
 433 Monitoring::Plugin; the nagios plugin developer guidelines at
 434 https://www.monitoring-plugins.org/doc/guidelines.html.
 435
 436 =head1 AUTHOR
 437
 438 This code is maintained by the Monitoring Plugin Development Team: see
 439 https://monitoring-plugins.org
 440
 441 =head1 COPYRIGHT AND LICENSE
 442
 443 Copyright (C) 2014      by Monitoring Plugin Team
 444 Copyright (C) 2006-2014 by Nagios Plugin Development Team
 445
 446 This library is free software; you can redistribute it and/or modify
 447 it under the same terms as Perl itself.
 448
 449 =cut