diff options
-rw-r--r-- | lib/Nagios/Plugin.pm | 279 |
1 files changed, 190 insertions, 89 deletions
diff --git a/lib/Nagios/Plugin.pm b/lib/Nagios/Plugin.pm index 7187048..23d8450 100644 --- a/lib/Nagios/Plugin.pm +++ b/lib/Nagios/Plugin.pm | |||
@@ -222,7 +222,6 @@ sub check_messages { | |||
222 | 222 | ||
223 | __END__ | 223 | __END__ |
224 | 224 | ||
225 | |||
226 | =head1 NAME | 225 | =head1 NAME |
227 | 226 | ||
228 | Nagios::Plugin - a family of perl modules to streamline writing Nagios | 227 | Nagios::Plugin - a family of perl modules to streamline writing Nagios |
@@ -230,79 +229,97 @@ plugins | |||
230 | 229 | ||
231 | =head1 SYNOPSIS | 230 | =head1 SYNOPSIS |
232 | 231 | ||
233 | # TODO NJV -- make this more like check_stuff. | 232 | # Constants OK, WARNING, CRITICAL, and UNKNOWN are exported by default |
234 | 233 | # See also Nagios::Plugin::Functions for a functional interface | |
235 | # Constants OK, WARNING, CRITICAL, and UNKNOWN are exported by default | 234 | use Nagios::Plugin; |
236 | # See also Nagios::Plugin::Functions for a functional interface | 235 | |
237 | use Nagios::Plugin; | 236 | # Constructor |
238 | 237 | $np = Nagios::Plugin->new; # OR | |
239 | # Constructor | 238 | $np = Nagios::Plugin->new( shortname => "PAGESIZE" ); # OR |
240 | $np = Nagios::Plugin->new; # OR | 239 | |
241 | $np = Nagios::Plugin->new( shortname => "PAGESIZE" ); | 240 | |
242 | 241 | # use Nagios::Plugin::Getopt to process the @ARGV command line options: | |
243 | # Exit methods - nagios_exit( CODE, MESSAGE ), | 242 | # --verbose, --help, --usage, --timeout and --host are defined automatically. |
244 | # nagios_die( MESSAGE, [CODE]) | 243 | $np = Nagios::Plugin->new( |
245 | $page = retrieve_page($page1) | 244 | usage => "Usage: %s [ -v|--verbose ] [-H <host>] [-t <timeout>] " |
246 | or $np->nagios_exit( UNKNOWN, "Could not retrieve page" ); | 245 | . "[ -c|--critical=<threshold> ] [ -w|--warning=<threshold> ]", |
247 | # Return code: 3; | 246 | ); |
248 | # output: PAGESIZE UNKNOWN - Could not retrieve page | 247 | |
249 | test_page($page) | 248 | # add valid command line options and build them into your usage/help documentation. |
250 | or $np->nagios_exit( CRITICAL, "Bad page found" ); | 249 | $p->add_arg( |
251 | 250 | spec => 'warning|w=s', | |
252 | # nagios_die() is just like nagios_exit(), but return code defaults | 251 | help => '-w, --warning=INTEGER:INTEGER . See ' |
253 | # to UNKNOWN | 252 | . 'http://nagiosplug.sourceforge.net/developer-guidelines.html#THRESHOLDFORMAT ' |
254 | $page = retrieve_page($page2) | 253 | . 'for the threshold format. ', |
255 | or $np->nagios_die( "Could not retrieve page" ); | 254 | ); |
256 | # Return code: 3; | 255 | |
257 | # output: PAGESIZE UNKNOWN - Could not retrieve page | 256 | # Parse @ARGV and process standard arguments (e.g. usage, help, version) |
258 | 257 | $p->getopts; | |
259 | # Threshold methods | 258 | |
260 | $code = $np->check_threshold( | 259 | |
261 | check => $value, | 260 | # Exit/return value methods - nagios_exit( CODE, MESSAGE ), |
262 | warning => $warning_threshold, | 261 | # nagios_die( MESSAGE, [CODE]) |
263 | critical => $critical_threshold, | 262 | $page = retrieve_page($page1) |
264 | ); | 263 | or $np->nagios_exit( UNKNOWN, "Could not retrieve page" ); |
265 | $np->nagios_exit( $code, "Threshold check failed" ) if $code != OK; | 264 | # Return code: 3; |
266 | 265 | # output: PAGESIZE UNKNOWN - Could not retrieve page | |
267 | # Message methods (EXPERIMENTAL AND SUBJECT TO CHANGE) - | 266 | test_page($page) |
268 | # add_message( CODE, $message ); check_messages() | 267 | or $np->nagios_exit( CRITICAL, "Bad page found" ); |
269 | for (@collection) { | 268 | |
270 | if (m/Error/) { | 269 | # nagios_die() is just like nagios_exit(), but return code defaults |
271 | $np->add_message( CRITICAL, $_ ); | 270 | # to UNKNOWN |
272 | } else { | 271 | $page = retrieve_page($page2) |
273 | $np->add_message( OK, $_ ); | 272 | or $np->nagios_die( "Could not retrieve page" ); |
274 | } | 273 | # Return code: 3; |
275 | } | 274 | # output: PAGESIZE UNKNOWN - Could not retrieve page |
276 | ($code, $message) = $np->check_message(); | 275 | |
277 | nagios_exit( $code, $message ); | 276 | # Threshold methods |
278 | # If any items in collection matched m/Error/, returns CRITICAL and | 277 | $code = $np->check_threshold( |
279 | # the joined set of Error messages; otherwise returns OK and the | 278 | check => $value, |
280 | # joined set of ok messages | 279 | warning => $warning_threshold, |
281 | 280 | critical => $critical_threshold, | |
282 | # Perfdata methods | 281 | ); |
283 | $np->add_perfdata( | 282 | $np->nagios_exit( $code, "Threshold check failed" ) if $code != OK; |
284 | label => "size", | 283 | |
285 | value => $value, | 284 | |
286 | uom => "kB", | 285 | # Message methods (EXPERIMENTAL AND SUBJECT TO CHANGE) - |
287 | threshold => $threshold, | 286 | # add_message( CODE, $message ); check_messages() |
288 | ); | 287 | for (@collection) { |
289 | $np->add_perfdata( label => "time", ... ); | 288 | if (m/Error/) { |
290 | $np->nagios_exit( OK, "page size at http://... was ${value}kB" ); | 289 | $np->add_message( CRITICAL, $_ ); |
291 | # Return code: 0; | 290 | } else { |
292 | # output: PAGESIZE OK - page size at http://... was 36kB \ | 291 | $np->add_message( OK, $_ ); |
293 | # | size=36kB;10:25;25: time=... | 292 | } |
294 | 293 | } | |
295 | # Option handling methods (NOT YET IMPLEMENTED - use | 294 | ($code, $message) = $np->check_message(); |
296 | # Nagios::Plugin::Getopt for | 295 | nagios_exit( $code, $message ); |
296 | # If any items in collection matched m/Error/, returns CRITICAL and | ||
297 | # the joined set of Error messages; otherwise returns OK and the | ||
298 | # joined set of ok messages | ||
299 | |||
300 | |||
301 | # Perfdata methods | ||
302 | $np->add_perfdata( | ||
303 | label => "size", | ||
304 | value => $value, | ||
305 | uom => "kB", | ||
306 | threshold => $threshold, | ||
307 | ); | ||
308 | $np->add_perfdata( label => "time", ... ); | ||
309 | $np->nagios_exit( OK, "page size at http://... was ${value}kB" ); | ||
310 | # Return code: 0; | ||
311 | # output: PAGESIZE OK - page size at http://... was 36kB \ | ||
312 | # | size=36kB;10:25;25: time=... | ||
313 | |||
297 | 314 | ||
298 | =head1 DESCRIPTION | 315 | =head1 DESCRIPTION |
299 | 316 | ||
300 | Nagios::Plugin and its associated Nagios::Plugin::* modules are a family of | 317 | Nagios::Plugin and its associated Nagios::Plugin::* modules are a |
301 | perl modules to streamline writing Nagios plugins. The main end user modules | 318 | family of perl modules to streamline writing Nagios plugins. The main |
302 | are Nagios::Plugin, providing an object-oriented interface to the entire | 319 | end user modules are Nagios::Plugin, providing an object-oriented |
303 | Nagios::Plugin::* collection, and Nagios::Plugin::Functions, providing a | 320 | interface to the entire Nagios::Plugin::* collection, and |
304 | simpler functional interface to a useful subset of the available | 321 | Nagios::Plugin::Functions, providing a simpler functional interface to |
305 | functionality. | 322 | a useful subset of the available functionality. |
306 | 323 | ||
307 | The purpose of the collection is to make it as simple as possible for | 324 | The purpose of the collection is to make it as simple as possible for |
308 | developers to create plugins that conform the Nagios Plugin guidelines | 325 | developers to create plugins that conform the Nagios Plugin guidelines |
@@ -339,9 +356,21 @@ reverse of %ERRORS. | |||
339 | 356 | ||
340 | =head2 CONSTRUCTOR | 357 | =head2 CONSTRUCTOR |
341 | 358 | ||
342 | Nagios::Plugin->new; | 359 | Nagios::Plugin->new; |
360 | |||
361 | Nagios::Plugin->new( shortname => 'PAGESIZE' ); | ||
343 | 362 | ||
344 | Nagios::Plugin->new( shortname => 'PAGESIZE' ); | 363 | Nagios::Plugin->new( |
364 | usage => "Usage: %s [ -v|--verbose ] [-H <host>] [-t <timeout>] | ||
365 | [ -c|--critical=<critical threshold> ] [ -w|--warning=<warning threshold> ] ", | ||
366 | version => $VERSION, | ||
367 | blurb => $blurb, | ||
368 | extra => $extra, | ||
369 | url => $url, | ||
370 | license => $license, | ||
371 | plugin => basename $0, | ||
372 | timeout => 15, | ||
373 | ); | ||
345 | 374 | ||
346 | Instantiates a new Nagios::Plugin object. Accepts the following named | 375 | Instantiates a new Nagios::Plugin object. Accepts the following named |
347 | arguments: | 376 | arguments: |
@@ -353,8 +382,85 @@ arguments: | |||
353 | The 'shortname' for this plugin, used as the first token in the plugin | 382 | The 'shortname' for this plugin, used as the first token in the plugin |
354 | output by the various exit methods. Default: uc basename $0. | 383 | output by the various exit methods. Default: uc basename $0. |
355 | 384 | ||
385 | =item usage ("Usage: %s --foo --bar") | ||
386 | |||
387 | Passing a value for the usage() argument makes Nagios::Plugin | ||
388 | instantiate its own C<Nagios::Plugin::Getopt> object so you can start | ||
389 | doing command line argument processing. See | ||
390 | L<Nagios::Plugin::Getopt/CONSTRUCTOR> for more about "usage" and the | ||
391 | following options: | ||
392 | |||
393 | =item version | ||
394 | |||
395 | =item url | ||
396 | |||
397 | =item blurb | ||
398 | |||
399 | =item license | ||
400 | |||
401 | =item extra | ||
402 | |||
403 | =item plugin | ||
404 | |||
405 | =item timeout | ||
406 | |||
356 | =back | 407 | =back |
357 | 408 | ||
409 | =head2 OPTION HANDLING METHODS | ||
410 | |||
411 | C<Nagios::Plugin> provides these methods for accessing the functionality in C<Nagios::Plugin::Getopt>. | ||
412 | |||
413 | =over 4 | ||
414 | |||
415 | =item add_arg | ||
416 | |||
417 | Examples: | ||
418 | |||
419 | # Define --hello argument (named parameters) | ||
420 | $plugin->add_arg( | ||
421 | spec => 'hello=s', | ||
422 | help => "--hello\n Hello string", | ||
423 | required => 1, | ||
424 | ); | ||
425 | |||
426 | # Define --hello argument (positional parameters) | ||
427 | # Parameter order is 'spec', 'help', 'default', 'required?' | ||
428 | $plugin->add_arg('hello=s', "--hello\n Hello string", undef, 1); | ||
429 | |||
430 | See L<Nagios::Plugin::Getopt/ARGUMENTS> for more details. | ||
431 | |||
432 | =item getopts() | ||
433 | |||
434 | Parses and processes the command line options you've defined, | ||
435 | automatically doing the right thing with help/usage/version arguments. | ||
436 | |||
437 | See L<Nagios::Plugin::Getopt/GETOPTS> for more details. | ||
438 | |||
439 | =item opts() | ||
440 | |||
441 | Assuming you've instantiated it by passing 'usage' to new(), opts() | ||
442 | returns the Nagios::Plugin object's C<Nagios::Plugin::Getopt> object, | ||
443 | with which you can do lots of great things. | ||
444 | |||
445 | E.g. | ||
446 | |||
447 | if ( $plugin->opts->verbose ) { | ||
448 | print "yah yah YAH YAH YAH!!!"; | ||
449 | } | ||
450 | |||
451 | # start counting down to timeout | ||
452 | alarm $plugin->opts->timeout; | ||
453 | your_long_check_step_that_might_time_out(); | ||
454 | |||
455 | # access any of your custom command line options, | ||
456 | # assuming you've done these steps above: | ||
457 | # $plugin->add_arg('my_argument=s', '--my_argument [STRING]'); | ||
458 | # $plugin->getopts; | ||
459 | print $plugin->opts->my_argument; | ||
460 | |||
461 | Again, see L<Nagios::Plugin::Getopt>. | ||
462 | |||
463 | =back | ||
358 | 464 | ||
359 | =head2 EXIT METHODS | 465 | =head2 EXIT METHODS |
360 | 466 | ||
@@ -378,8 +484,9 @@ Alias for nagios_die(). Deprecated. | |||
378 | 484 | ||
379 | =head2 THRESHOLD METHODS | 485 | =head2 THRESHOLD METHODS |
380 | 486 | ||
381 | These provide a top level interface to the C<Nagios::Plugins::Threshold> | 487 | These provide a top level interface to the |
382 | module; for more details, see its documentation. | 488 | C<Nagios::Plugin::Threshold> module; for more details, see |
489 | L<Nagios::Plugin::Threshold> and L<Nagios::Plugin::Range>. | ||
383 | 490 | ||
384 | =over 4 | 491 | =over 4 |
385 | 492 | ||
@@ -422,7 +529,6 @@ need to do that from a plugin script. | |||
422 | 529 | ||
423 | =back | 530 | =back |
424 | 531 | ||
425 | |||
426 | =head2 MESSAGE METHODS | 532 | =head2 MESSAGE METHODS |
427 | 533 | ||
428 | EXPERIMENTAL AND SUBJECT TO CHANGE | 534 | EXPERIMENTAL AND SUBJECT TO CHANGE |
@@ -518,19 +624,13 @@ section of the Nagios Plugin guidelines | |||
518 | =back | 624 | =back |
519 | 625 | ||
520 | 626 | ||
521 | =head2 OPTION HANDLING METHODS | ||
522 | |||
523 | TODO | ||
524 | |||
525 | NOT YET IMPLEMENTED - use Nagios::Plugin::Getopt directly for now. | ||
526 | |||
527 | |||
528 | =head1 EXAMPLES | 627 | =head1 EXAMPLES |
529 | 628 | ||
530 | "Enough talk! Show me some examples!" | 629 | "Enough talk! Show me some examples!" |
531 | 630 | ||
532 | See the file 'check_stuff.pl' in the 't' directory for a complete working | 631 | See the file 'check_stuff.pl' in the 't' directory included with the |
533 | example of a plugin script. | 632 | Nagios::Plugin distribution for a complete working example of a plugin |
633 | script. | ||
534 | 634 | ||
535 | 635 | ||
536 | =head1 VERSIONING | 636 | =head1 VERSIONING |
@@ -543,12 +643,12 @@ possible. | |||
543 | 643 | ||
544 | =head1 SEE ALSO | 644 | =head1 SEE ALSO |
545 | 645 | ||
546 | See Nagios::Plugin::Functions for a simple functional interface to a subset | 646 | See L<Nagios::Plugin::Functions> for a simple functional interface to a subset |
547 | of the available Nagios::Plugin functionality. | 647 | of the available Nagios::Plugin functionality. |
548 | 648 | ||
549 | See also Nagios::Plugin::Getopt, Nagios::Plugin::Range, | 649 | See also L<Nagios::Plugin::Getopt>, L<Nagios::Plugin::Range>, |
550 | Nagios::Plugin::Performance, Nagios::Plugin::Range, and | 650 | L<Nagios::Plugin::Performance>, L<Nagios::Plugin::Range>, and |
551 | Nagios::Plugin::Threshold. | 651 | L<Nagios::Plugin::Threshold>. |
552 | 652 | ||
553 | The Nagios Plugin project page is at http://nagiosplug.sourceforge.net. | 653 | The Nagios Plugin project page is at http://nagiosplug.sourceforge.net. |
554 | 654 | ||
@@ -575,3 +675,4 @@ under the same terms as Perl itself, either Perl version 5.8.4 or, at your | |||
575 | option, any later version of Perl 5 you may have available. | 675 | option, any later version of Perl 5 you may have available. |
576 | 676 | ||
577 | =cut | 677 | =cut |
678 | |||