summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorNathan Vonnahme <n8v@users.sourceforge.net>2006-11-21 21:00:47 +0000
committerNathan Vonnahme <n8v@users.sourceforge.net>2006-11-21 21:00:47 +0000
commit0f69ed4346405fc21fd13c21c60e87b57b5d47c9 (patch)
tree2fbb55e51bdb7c42454cb80d4ddc3a2f0015185e
parente0c038d4c2a974f53c37d0b9fb3b22b7cd8d765b (diff)
downloadmonitoring-plugin-perl-0f69ed4346405fc21fd13c21c60e87b57b5d47c9.tar.gz
* POD updates to reflect Getopt and Threshold top level interface work.
git-svn-id: https://nagiosplug.svn.sourceforge.net/svnroot/nagiosplug/Nagios-Plugin/trunk@1540 f882894a-f735-0410-b71e-b25c423dba1c
-rw-r--r--lib/Nagios/Plugin.pm279
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
228Nagios::Plugin - a family of perl modules to streamline writing Nagios 227Nagios::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
300Nagios::Plugin and its associated Nagios::Plugin::* modules are a family of 317Nagios::Plugin and its associated Nagios::Plugin::* modules are a
301perl modules to streamline writing Nagios plugins. The main end user modules 318family of perl modules to streamline writing Nagios plugins. The main
302are Nagios::Plugin, providing an object-oriented interface to the entire 319end user modules are Nagios::Plugin, providing an object-oriented
303Nagios::Plugin::* collection, and Nagios::Plugin::Functions, providing a 320interface to the entire Nagios::Plugin::* collection, and
304simpler functional interface to a useful subset of the available 321Nagios::Plugin::Functions, providing a simpler functional interface to
305functionality. 322a useful subset of the available functionality.
306 323
307The purpose of the collection is to make it as simple as possible for 324The purpose of the collection is to make it as simple as possible for
308developers to create plugins that conform the Nagios Plugin guidelines 325developers 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
346Instantiates a new Nagios::Plugin object. Accepts the following named 375Instantiates a new Nagios::Plugin object. Accepts the following named
347arguments: 376arguments:
@@ -353,8 +382,85 @@ arguments:
353The 'shortname' for this plugin, used as the first token in the plugin 382The 'shortname' for this plugin, used as the first token in the plugin
354output by the various exit methods. Default: uc basename $0. 383output by the various exit methods. Default: uc basename $0.
355 384
385=item usage ("Usage: %s --foo --bar")
386
387Passing a value for the usage() argument makes Nagios::Plugin
388instantiate its own C<Nagios::Plugin::Getopt> object so you can start
389doing command line argument processing. See
390L<Nagios::Plugin::Getopt/CONSTRUCTOR> for more about "usage" and the
391following 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
411C<Nagios::Plugin> provides these methods for accessing the functionality in C<Nagios::Plugin::Getopt>.
412
413=over 4
414
415=item add_arg
416
417Examples:
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
430See L<Nagios::Plugin::Getopt/ARGUMENTS> for more details.
431
432=item getopts()
433
434Parses and processes the command line options you've defined,
435automatically doing the right thing with help/usage/version arguments.
436
437See L<Nagios::Plugin::Getopt/GETOPTS> for more details.
438
439=item opts()
440
441Assuming you've instantiated it by passing 'usage' to new(), opts()
442returns the Nagios::Plugin object's C<Nagios::Plugin::Getopt> object,
443with which you can do lots of great things.
444
445E.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
461Again, 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
381These provide a top level interface to the C<Nagios::Plugins::Threshold> 487These provide a top level interface to the
382module; for more details, see its documentation. 488C<Nagios::Plugin::Threshold> module; for more details, see
489L<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
428EXPERIMENTAL AND SUBJECT TO CHANGE 534EXPERIMENTAL 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
523TODO
524
525NOT 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
532See the file 'check_stuff.pl' in the 't' directory for a complete working 631See the file 'check_stuff.pl' in the 't' directory included with the
533example of a plugin script. 632Nagios::Plugin distribution for a complete working example of a plugin
633script.
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
546See Nagios::Plugin::Functions for a simple functional interface to a subset 646See L<Nagios::Plugin::Functions> for a simple functional interface to a subset
547of the available Nagios::Plugin functionality. 647of the available Nagios::Plugin functionality.
548 648
549See also Nagios::Plugin::Getopt, Nagios::Plugin::Range, 649See also L<Nagios::Plugin::Getopt>, L<Nagios::Plugin::Range>,
550Nagios::Plugin::Performance, Nagios::Plugin::Range, and 650L<Nagios::Plugin::Performance>, L<Nagios::Plugin::Range>, and
551Nagios::Plugin::Threshold. 651L<Nagios::Plugin::Threshold>.
552 652
553The Nagios Plugin project page is at http://nagiosplug.sourceforge.net. 653The 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
575option, any later version of Perl 5 you may have available. 675option, any later version of Perl 5 you may have available.
576 676
577=cut 677=cut
678