1Nagios::Plugin(3) User Contributed Perl Documentation Nagios::Plugin(3)
2
6 Nagios::Plugin - A family of perl modules to streamline writing Nagios
7 plugins
8
10 # Constants OK, WARNING, CRITICAL, and UNKNOWN are exported by default
11 # See also Nagios::Plugin::Functions for a functional interface
12 use Nagios::Plugin;
13 # Constructor
15 $np = Nagios::Plugin->new; # OR
16 $np = Nagios::Plugin->new( shortname => "PAGESIZE" ); # OR
17 # use Nagios::Plugin::Getopt to process the @ARGV command line options:
20 # --verbose, --help, --usage, --timeout and --host are defined automatically.
21 $np = Nagios::Plugin->new(
22 usage => "Usage: %s [ -v|--verbose ] [-H <host>] [-t <timeout>] "
23 . "[ -c|--critical=<threshold> ] [ -w|--warning=<threshold> ]",
24 );
25 # add valid command line options and build them into your usage/help documentation.
27 $np->add_arg(
28 spec => 'warning|w=s',
29 help => '-w, --warning=INTEGER:INTEGER . See '
30 . 'http://nagiosplug.sourceforge.net/developer-guidelines.html#THRESHOLDFORMAT '
31 . 'for the threshold format. ',
32 );
33 # Parse @ARGV and process standard arguments (e.g. usage, help, version)
35 $np->getopts;
36 # Exit/return value methods - nagios_exit( CODE, MESSAGE ),
39 # nagios_die( MESSAGE, [CODE])
40 $page = retrieve_page($page1)
41 or $np->nagios_exit( UNKNOWN, "Could not retrieve page" );
42 # Return code: 3;
43 # output: PAGESIZE UNKNOWN - Could not retrieve page
44 test_page($page)
45 or $np->nagios_exit( CRITICAL, "Bad page found" );
46 # nagios_die() is just like nagios_exit(), but return code defaults
48 # to UNKNOWN
49 $page = retrieve_page($page2)
50 or $np->nagios_die( "Could not retrieve page" );
51 # Return code: 3;
52 # output: PAGESIZE UNKNOWN - Could not retrieve page
53 # Threshold methods
55 $code = $np->check_threshold(
56 check => $value,
57 warning => $warning_threshold,
58 critical => $critical_threshold,
59 );
60 $np->nagios_exit( $code, "Threshold check failed" ) if $code != OK;
61 # Message methods (EXPERIMENTAL AND SUBJECT TO CHANGE) -
64 # add_message( CODE, $message ); check_messages()
65 for (@collection) {
66 if (m/Error/) {
67 $np->add_message( CRITICAL, $_ );
68 } else {
69 $np->add_message( OK, $_ );
70 }
71 }
72 ($code, $message) = $np->check_message();
73 nagios_exit( $code, $message );
74 # If any items in collection matched m/Error/, returns CRITICAL and
75 # the joined set of Error messages; otherwise returns OK and the
76 # joined set of ok messages
77 # Perfdata methods
80 $np->add_perfdata(
81 label => "size",
82 value => $value,
83 uom => "kB",
84 threshold => $threshold,
85 );
86 $np->add_perfdata( label => "time", ... );
87 $np->nagios_exit( OK, "page size at http://... was ${value}kB" );
88 # Return code: 0;
89 # output: PAGESIZE OK - page size at http://... was 36kB \
90 # | size=36kB;10:25;25: time=...
91
93 Nagios::Plugin and its associated Nagios::Plugin::* modules are a
94 family of perl modules to streamline writing Nagios plugins. The main
95 end user modules are Nagios::Plugin, providing an object-oriented
96 interface to the entire Nagios::Plugin::* collection, and
97 Nagios::Plugin::Functions, providing a simpler functional interface to
98 a useful subset of the available functionality.
99 The purpose of the collection is to make it as simple as possible for
101 developers to create plugins that conform the Nagios Plugin guidelines
102 (http://nagiosplug.sourceforge.net/developer-guidelines.html).
103 EXPORTS
105 Nagios status code constants are exported by default:
106 OK
108 WARNING
109 CRITICAL
110 UNKNOWN
111 DEPENDENT
112 The following variables are also exported on request:
114 %ERRORS
116 A hash mapping error strings ("CRITICAL", "UNKNOWN", etc.) to the
117 corresponding status code.
118 %STATUS_TEXT
120 A hash mapping status code constants (OK, WARNING, CRITICAL, etc.)
121 to the corresponding error string ("OK", "WARNING, "CRITICAL",
122 etc.) i.e. the reverse of %ERRORS.
123 CONSTRUCTOR
125 Nagios::Plugin->new;
126 Nagios::Plugin->new( shortname => 'PAGESIZE' );
128 Nagios::Plugin->new(
130 usage => "Usage: %s [ -v|--verbose ] [-H <host>] [-t <timeout>]
131 [ -c|--critical=<critical threshold> ] [ -w|--warning=<warning threshold> ] ",
132 version => $VERSION,
133 blurb => $blurb,
134 extra => $extra,
135 url => $url,
136 license => $license,
137 plugin => basename $0,
138 timeout => 15,
139 );
140 Instantiates a new Nagios::Plugin object. Accepts the following named
142 arguments:
143 shortname
145 The 'shortname' for this plugin, used as the first token in the
146 plugin output by the various exit methods. Default: uc basename $0.
147 usage ("Usage: %s --foo --bar")
149 Passing a value for the usage() argument makes Nagios::Plugin
150 instantiate its own "Nagios::Plugin::Getopt" object so you can
151 start doing command line argument processing. See "CONSTRUCTOR" in
152 Nagios::Plugin::Getopt for more about "usage" and the following
153 options:
154 version
156 url
157 blurb
158 license
159 extra
160 plugin
161 timeout
162 OPTION HANDLING METHODS
164 "Nagios::Plugin" provides these methods for accessing the functionality
165 in "Nagios::Plugin::Getopt".
166 add_arg
168 Examples:
169 # Define --hello argument (named parameters)
171 $plugin->add_arg(
172 spec => 'hello=s',
173 help => "--hello\n Hello string",
174 required => 1,
175 );
176 # Define --hello argument (positional parameters)
178 # Parameter order is 'spec', 'help', 'default', 'required?'
179 $plugin->add_arg('hello=s', "--hello\n Hello string", undef, 1);
180 See "ARGUMENTS" in Nagios::Plugin::Getopt for more details.
182 getopts()
184 Parses and processes the command line options you've defined,
185 automatically doing the right thing with help/usage/version
186 arguments.
187 See "GETOPTS" in Nagios::Plugin::Getopt for more details.
189 opts()
191 Assuming you've instantiated it by passing 'usage' to new(), opts()
192 returns the Nagios::Plugin object's "Nagios::Plugin::Getopt"
193 object, with which you can do lots of great things.
194 E.g.
196 if ( $plugin->opts->verbose ) {
198 print "yah yah YAH YAH YAH!!!";
199 }
200 # start counting down to timeout
202 alarm $plugin->opts->timeout;
203 your_long_check_step_that_might_time_out();
204 # access any of your custom command line options,
206 # assuming you've done these steps above:
207 # $plugin->add_arg('my_argument=s', '--my_argument [STRING]');
208 # $plugin->getopts;
209 print $plugin->opts->my_argument;
210 Again, see Nagios::Plugin::Getopt.
212 EXIT METHODS
214 nagios_exit( <CODE>, $message )
215 Exit with return code CODE, and a standard nagios message of the
216 form "SHORTNAME CODE - $message".
217 nagios_die( $message, [<CODE>] )
219 Same as nagios_exit(), except that CODE is optional, defaulting to
220 UNKNOWN. NOTE: exceptions are not raised by default to calling
221 code. Set $_use_die flag if this functionality is required (see
222 test code).
223 die( $message, [<CODE>] )
225 Alias for nagios_die(). Deprecated.
226 max_state, max_state_alt
228 These are wrapper function for Nagios::Plugin::Functions::max_state
229 and Nagios::Plugin::Functions::max_state_alt.
230 THRESHOLD METHODS
232 These provide a top level interface to the "Nagios::Plugin::Threshold"
233 module; for more details, see Nagios::Plugin::Threshold and
234 Nagios::Plugin::Range.
235 check_threshold( $value )
237 check_threshold( check => $value, warning => $warn, critical => $crit )
238 Evaluates $value against the thresholds and returns OK, CRITICAL,
239 or WARNING constant. The thresholds may be:
240 1. explicitly set by passing 'warning' and/or 'critical' parameters
242 to
243 "check_threshold()", or,
244 2. explicitly set by calling "set_thresholds()" before
246 "check_threshold()", or,
247 3. implicitly set by command-line parameters -w, -c, --critical or
249 --warning, if you have run "$plugin->getopts()".
250 The return value is ready to pass to C <nagios_exit>, e . g .,
252 $p->nagios_exit(
254 return_code => $p->check_threshold($result),
255 message => " sample result was $result"
256 );
257 set_thresholds(warning => "10:25", critical => "~:25")
259 Sets the acceptable ranges and creates the plugin's
260 Nagios::Plugins::Threshold object. See
261 http://nagiosplug.sourceforge.net/developer-guidelines.html#THRESHOLDFORMAT
262 for details and examples of the threshold format.
263 threshold()
265 Returns the object's "Nagios::Plugin::Threshold" object, if it has
266 been defined by calling set_thresholds(). You can pass a new
267 Threshold object to it to replace the old one too, but you
268 shouldn't need to do that from a plugin script.
269 MESSAGE METHODS
271 EXPERIMENTAL AND SUBJECT TO CHANGE
272 add_messages and check_messages are higher-level convenience methods to
274 add and then check a set of messages, returning an appropriate return
275 code and/or result message. They are equivalent to maintaining a set of
276 @critical, @warning, and and @ok message arrays (add_message), and then
277 doing a final if test (check_message) like this:
278 if (@critical) {
280 nagios_exit( CRITICAL, join(' ', @critical) );
281 }
282 elsif (@warning) {
283 nagios_exit( WARNING, join(' ', @warning) );
284 }
285 else {
286 nagios_exit( OK, join(' ', @ok) );
287 }
288 add_message( <CODE>, $message )
290 Add a message with CODE status to the object. May be called
291 multiple times. The messages added are checked by check_messages,
292 following.
293 Only CRITICAL, WARNING, and OK are accepted as valid codes.
295 check_messages()
297 Check the current set of messages and return an appropriate nagios
298 return code and/or a result message. In scalar context, returns
299 only a return code; in list context returns both a return code and
300 an output message, suitable for passing directly to nagios_exit()
301 e.g.
302 $code = $np->check_messages;
304 ($code, $message) = $np->check_messages;
305 check_messages returns CRITICAL if any critical messages are found,
307 WARNING if any warning messages are found, and OK otherwise. The
308 message returned in list context defaults to the joined set of
309 error messages; this may be customised using the arguments below.
310 check_messages accepts the following named arguments (none are
312 required):
313 join => SCALAR
315 A string used to join the relevant array to generate the
316 message string returned in list context i.e. if the 'critical'
317 array @crit is non-empty, check_messages would return:
318 join( $join, @crit )
320 as the result message. Default: ' ' (space).
322 join_all => SCALAR
324 By default, only one set of messages are joined and returned in
325 the result message i.e. if the result is CRITICAL, only the
326 'critical' messages are included in the result; if WARNING,
327 only the 'warning' messages are included; if OK, the 'ok'
328 messages are included (if supplied) i.e. the default is to
329 return an 'errors-only' type message.
330 If join_all is supplied, however, it will be used as a string
332 to join the resultant critical, warning, and ok messages
333 together i.e. all messages are joined and returned.
334 critical => ARRAYREF
336 Additional critical messages to supplement any passed in via
337 add_message().
338 warning => ARRAYREF
340 Additional warning messages to supplement any passed in via
341 add_message().
342 ok => ARRAYREF | SCALAR
344 Additional ok messages to supplement any passed in via
345 add_message().
346 PERFORMANCE DATA METHODS
348 add_perfdata( label => "size", value => $value, uom => "kB", threshold
349 => $threshold )
350 Add a set of performance data to the object. May be called multiple
351 times. The performance data is included in the standard plugin
352 output messages by the various exit methods.
353 See the Nagios::Plugin::Performance documentation for more
355 information on performance data and the various field definitions,
356 as well as the relevant section of the Nagios Plugin guidelines
357 (http://nagiosplug.sourceforge.net/developer-guidelines.html#AEN202).
358
360 "Enough talk! Show me some examples!"
361 See the file 'check_stuff.pl' in the 't' directory included with the
363 Nagios::Plugin distribution for a complete working example of a plugin
364 script.
365
367 The Nagios::Plugin::* modules are currently experimental and so the
368 interfaces may change up until Nagios::Plugin hits version 1.0,
369 although every attempt will be made to keep them as backwards
370 compatible as possible.
371
373 See Nagios::Plugin::Functions for a simple functional interface to a
374 subset of the available Nagios::Plugin functionality.
375 See also Nagios::Plugin::Getopt, Nagios::Plugin::Range,
377 Nagios::Plugin::Performance, Nagios::Plugin::Range, and
378 Nagios::Plugin::Threshold.
379 The Nagios Plugin project page is at http://nagiosplug.sourceforge.net.
381
383 Please report bugs in these modules to the Nagios Plugin development
384 team: nagiosplug-devel@lists.sourceforge.net.
385
387 Maintained by the Nagios Plugin development team -
388 http://nagiosplug.sourceforge.net.
389 Originally by Ton Voon, <ton.voon@altinity.com>.
391
393 Copyright (C) 2006 by Nagios Plugin Development Team
394 This library is free software; you can redistribute it and/or modify it
396 under the same terms as Perl itself, either Perl version 5.8.4 or, at
397 your option, any later version of Perl 5 you may have available.
398perl v5.12.1 2010-04-15 Nagios::Plugin(3)