1Monitoring::Plugin(3) User Contributed Perl DocumentationMonitoring::Plugin(3)
2
3
4

NAME

6       Monitoring::Plugin - A family of perl modules to streamline writing
7       Naemon, Nagios, Icinga or Shinken (and compatible) plugins.
8

SYNOPSIS

10          # Constants OK, WARNING, CRITICAL, and UNKNOWN are exported by default
11          # See also Monitoring::Plugin::Functions for a functional interface
12          use Monitoring::Plugin;
13
14          # Constructor
15          $np = Monitoring::Plugin->new;                               # OR
16          $np = Monitoring::Plugin->new( shortname => "PAGESIZE" );    # OR
17
18
19          # use Monitoring::Plugin::Getopt to process the @ARGV command line options:
20          #   --verbose, --help, --usage, --timeout and --host are defined automatically.
21          $np = Monitoring::Plugin->new(
22            usage => "Usage: %s [ -v|--verbose ]  [-H <host>] [-t <timeout>] "
23              . "[ -c|--critical=<threshold> ] [ -w|--warning=<threshold> ]",
24          );
25
26          # 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              . 'https://www.monitoring-plugins.org/doc/guidelines.html#THRESHOLDFORMAT '
31              . 'for the threshold format. ',
32          );
33
34          # Parse @ARGV and process standard arguments (e.g. usage, help, version)
35          $np->getopts;
36
37
38          # Exit/return value methods - plugin_exit( CODE, MESSAGE ),
39          #                             plugin_die( MESSAGE, [CODE])
40          $page = retrieve_page($page1)
41              or $np->plugin_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->plugin_exit( CRITICAL, "Bad page found" );
46
47          # plugin_die() is just like plugin_exit(), but return code defaults
48          #   to UNKNOWN
49          $page = retrieve_page($page2)
50            or $np->plugin_die( "Could not retrieve page" );
51            # Return code: 3;
52            #   output: PAGESIZE UNKNOWN - Could not retrieve page
53
54          # Threshold methods
55          $code = $np->check_threshold(
56            check => $value,
57            warning => $warning_threshold,
58            critical => $critical_threshold,
59          );
60          $np->plugin_exit( $code, "Threshold check failed" ) if $code != OK;
61
62          # Message methods
63          #   add_message( CODE, $message ); check_messages()
64          for (@collection) {
65            if (m/Error/) {
66              $np->add_message( CRITICAL, $_ );
67            } else {
68              $np->add_message( OK, $_ );
69            }
70          }
71          ($code, $message) = $np->check_messages();
72          plugin_exit( $code, $message );
73          # If any items in collection matched m/Error/, returns CRITICAL and
74          #   the joined set of Error messages; otherwise returns OK and the
75          #   joined set of ok messages
76
77
78          # Perfdata methods
79          $np->add_perfdata(
80            label => "size",
81            value => $value,
82            uom => "kB",
83            threshold => $threshold,
84          );
85          $np->add_perfdata( label => "time", ... );
86          $np->plugin_exit( OK, "page size at http://... was ${value}kB" );
87          # Return code: 0;
88          #   output: PAGESIZE OK - page size at http://... was 36kB \
89          #   | size=36kB;10:25;25: time=...
90

DESCRIPTION

92       Monitoring::Plugin and its associated Monitoring::Plugin::* modules are
93       a family of perl modules to streamline writing Monitoring plugins. The
94       main end user modules are Monitoring::Plugin, providing an object-
95       oriented interface to the entire Monitoring::Plugin::* collection, and
96       Monitoring::Plugin::Functions, providing a simpler functional interface
97       to a useful subset of the available functionality.
98
99       The purpose of the collection is to make it as simple as possible for
100       developers to create plugins that conform the Monitoring Plugin
101       guidelines (https://www.monitoring-plugins.org/doc/guidelines.html).
102
103   EXPORTS
104       Nagios status code constants are exported by default:
105
106           OK
107           WARNING
108           CRITICAL
109           UNKNOWN
110           DEPENDENT
111
112       The following variables are also exported on request:
113
114       %ERRORS
115           A hash mapping error strings ("CRITICAL", "UNKNOWN", etc.) to the
116           corresponding status code.
117
118       %STATUS_TEXT
119           A hash mapping status code constants (OK, WARNING, CRITICAL, etc.)
120           to the corresponding error string ("OK", "WARNING, "CRITICAL",
121           etc.) i.e. the reverse of %ERRORS.
122
123   CONSTRUCTOR
124               Monitoring::Plugin->new;
125
126               Monitoring::Plugin->new( shortname => 'PAGESIZE' );
127
128               Monitoring::Plugin->new(
129                       usage => "Usage: %s [ -v|--verbose ]  [-H <host>] [-t <timeout>]
130                            [ -c|--critical=<critical threshold> ] [ -w|--warning=<warning threshold> ]  ",
131                       version => $VERSION,
132                       blurb   => $blurb,
133                       extra   => $extra,
134                       url     => $url,
135                       license => $license,
136                       plugin  => basename $0,
137                       timeout => 15,
138               );
139
140       Instantiates a new Monitoring::Plugin object. Accepts the following
141       named arguments:
142
143       shortname
144           The 'shortname' for this plugin, used as the first token in the
145           plugin output by the various exit methods. Default: uc basename $0.
146
147       usage ("Usage:  %s --foo --bar")
148           Passing a value for the usage() argument makes Monitoring::Plugin
149           instantiate its own "Monitoring::Plugin::Getopt" object so you can
150           start doing command line argument processing.  See "CONSTRUCTOR" in
151           Monitoring::Plugin::Getopt for more about "usage" and the following
152           options:
153
154       version
155       url
156       blurb
157       license
158       extra
159       plugin
160       timeout
161
162   GETTER/SETTER
163       The following internal variables can be retrieved or set by calling a
164       method with the respective name. Expect for "shortname", don't change
165       values unless you know what you're doing.
166
167       Examples:
168
169         use Data::Dumper;
170         print Dumper($plugin->perfdata);
171         $plugin->shortname('DifferentName');
172
173       shortname
174       perfdata
175       messages
176       opts
177       threshold
178
179   OPTION HANDLING METHODS
180       "Monitoring::Plugin" provides these methods for accessing the
181       functionality in "Monitoring::Plugin::Getopt".
182
183       add_arg
184           Examples:
185
186             # Define --hello argument (named parameters)
187             $plugin->add_arg(
188               spec => 'hello=s',
189               help => "--hello\n   Hello string",
190               required => 1,
191             );
192
193             # Define --hello argument (positional parameters)
194             #   Parameter order is 'spec', 'help', 'default', 'required?'
195             $plugin->add_arg('hello=s', "--hello\n   Hello string", undef, 1);
196
197           See "ARGUMENTS" in Monitoring::Plugin::Getopt for more details.
198
199       getopts()
200           Parses and processes the command line options you've defined,
201           automatically doing the right thing with help/usage/version
202           arguments.
203
204           See  "GETOPTS" in Monitoring::Plugin::Getopt for more details.
205
206       opts()
207           Assuming you've instantiated it by passing 'usage' to new(), opts()
208           returns the Monitoring::Plugin object's
209           "Monitoring::Plugin::Getopt" object, with which you can do lots of
210           great things.
211
212           E.g.
213
214             if ( $plugin->opts->verbose ) {
215                     print "yah yah YAH YAH YAH!!!";
216             }
217
218             # start counting down to timeout
219             alarm $plugin->opts->timeout;
220             your_long_check_step_that_might_time_out();
221
222             # access any of your custom command line options,
223             # assuming you've done these steps above:
224             #   $plugin->add_arg('my_argument=s', '--my_argument [STRING]');
225             #   $plugin->getopts;
226             print $plugin->opts->my_argument;
227
228           Again, see Monitoring::Plugin::Getopt.
229
230   EXIT METHODS
231       plugin_exit( <CODE>, $message )
232           Exit with return code CODE, and a standard nagios message of the
233           form "SHORTNAME CODE - $message".
234
235       nagios_exit( <CODE>, $message )
236           Alias for plugin_exit(). Deprecated.
237
238       plugin_die( $message, [<CODE>] )
239           Same as plugin_exit(), except that CODE is optional, defaulting to
240           UNKNOWN.  NOTE: exceptions are not raised by default to calling
241           code.  Set $_use_die flag if this functionality is required (see
242           test code).
243
244       nagios_die( $message, [<CODE>] )
245           Alias for plugin_die(). Deprecated.
246
247       die( $message, [<CODE>] )
248           Alias for plugin_die(). Deprecated.
249
250       max_state, max_state_alt
251           These are wrapper function for
252           Monitoring::Plugin::Functions::max_state and
253           Monitoring::Plugin::Functions::max_state_alt.
254
255   THRESHOLD METHODS
256       These provide a top level interface to the
257       "Monitoring::Plugin::Threshold" module; for more details, see
258       Monitoring::Plugin::Threshold and Monitoring::Plugin::Range.
259
260       check_threshold( $value )
261       check_threshold( check => $value, warning => $warn, critical => $crit )
262           Evaluates $value against the thresholds and returns OK, CRITICAL,
263           or WARNING constant.  The thresholds may be:
264
265           1. explicitly set by passing 'warning' and/or 'critical' parameters
266           to
267              "check_threshold()", or,
268
269           2. explicitly set by calling "set_thresholds()" before
270           "check_threshold()", or,
271
272           3. implicitly set by command-line parameters -w, -c, --critical or
273              --warning, if you have run "$plugin->getopts()".
274
275           You can specify $value as an array of values and each will be
276           checked against the thresholds.
277
278           The return value is ready to pass to C <plugin_exit>, e . g .,
279
280             $p->plugin_exit(
281                   return_code => $p->check_threshold($result),
282                   message     => " sample result was $result"
283             );
284
285       set_thresholds(warning => "10:25", critical => "~:25")
286           Sets the acceptable ranges and creates the plugin's
287           Monitoring::Plugins::Threshold object.  See
288           https://www.monitoring-plugins.org/doc/guidelines.html#THRESHOLDFORMAT
289           for details and examples of the threshold format.
290
291       threshold()
292           Returns the object's "Monitoring::Plugin::Threshold" object, if it
293           has been defined by calling set_thresholds().  You can pass a new
294           Threshold object to it to replace the old one too, but you
295           shouldn't need to do that from a plugin script.
296
297   MESSAGE METHODS
298       add_messages and check_messages are higher-level convenience methods to
299       add and then check a set of messages, returning an appropriate return
300       code and/or result message. They are equivalent to maintaining a set of
301       @critical, @warning, and and @ok message arrays (add_message), and then
302       doing a final if test (check_messages) like this:
303
304         if (@critical) {
305           plugin_exit( CRITICAL, join(' ', @critical) );
306         }
307         elsif (@warning) {
308           plugin_exit( WARNING, join(' ', @warning) );
309         }
310         else {
311           plugin_exit( OK, join(' ', @ok) );
312         }
313
314       add_message( <CODE>, $message )
315           Add a message with CODE status to the object. May be called
316           multiple times.  The messages added are checked by check_messages,
317           following.
318
319           Only CRITICAL, WARNING, and OK are accepted as valid codes.
320
321       check_messages()
322           Check the current set of messages and return an appropriate nagios
323           return code and/or a result message. In scalar context, returns
324           only a return code; in list context returns both a return code and
325           an output message, suitable for passing directly to plugin_exit()
326           e.g.
327
328               $code = $np->check_messages;
329               ($code, $message) = $np->check_messages;
330
331           check_messages returns CRITICAL if any critical messages are found,
332           WARNING if any warning messages are found, and OK otherwise. The
333           message returned in list context defaults to the joined set of
334           error messages; this may be customised using the arguments below.
335
336           check_messages accepts the following named arguments (none are
337           required):
338
339           join => SCALAR
340               A string used to join the relevant array to generate the
341               message string returned in list context i.e. if the 'critical'
342               array @crit is non-empty, check_messages would return:
343
344                   join( $join, @crit )
345
346               as the result message. Default: ' ' (space).
347
348           join_all => SCALAR
349               By default, only one set of messages are joined and returned in
350               the result message i.e. if the result is CRITICAL, only the
351               'critical' messages are included in the result; if WARNING,
352               only the 'warning' messages are included; if OK, the 'ok'
353               messages are included (if supplied) i.e. the default is to
354               return an 'errors-only' type message.
355
356               If join_all is supplied, however, it will be used as a string
357               to join the resultant critical, warning, and ok messages
358               together i.e.  all messages are joined and returned.
359
360           critical => ARRAYREF
361               Additional critical messages to supplement any passed in via
362               add_message().
363
364           warning => ARRAYREF
365               Additional warning messages to supplement any passed in via
366               add_message().
367
368           ok => ARRAYREF | SCALAR
369               Additional ok messages to supplement any passed in via
370               add_message().
371
372   PERFORMANCE DATA METHODS
373       add_perfdata( label => "size", value => $value, uom => "kB", threshold
374       => $threshold )
375           Add a set of performance data to the object. May be called multiple
376           times.  The performance data is included in the standard plugin
377           output messages by the various exit methods.
378
379           See the Monitoring::Plugin::Performance documentation for more
380           information on performance data and the various field definitions,
381           as well as the relevant section of the Monitoring Plugin guidelines
382           (https://www.monitoring-plugins.org/doc/guidelines.html#AEN202).
383

EXAMPLES

385       "Enough talk!  Show me some examples!"
386
387       See the file 'check_stuff.pl' in the 't' directory included with the
388       Monitoring::Plugin distribution for a complete working example of a
389       plugin script.
390

VERSIONING

392       The Monitoring::Plugin::* modules are currently experimental and so the
393       interfaces may change up until Monitoring::Plugin hits version 1.0,
394       although every attempt will be made to keep them as backwards
395       compatible as possible.
396

SEE ALSO

398       See Monitoring::Plugin::Functions for a simple functional interface to
399       a subset of the available Monitoring::Plugin functionality.
400
401       See also Monitoring::Plugin::Getopt, Monitoring::Plugin::Range,
402       Monitoring::Plugin::Performance, Monitoring::Plugin::Range, and
403       Monitoring::Plugin::Threshold.
404
405       The Monitoring Plugin project page is at http://monitoring-plugins.org.
406

BUGS

408       Please report bugs in these modules to the Monitoring Plugin
409       development team: devel@monitoring-plugins.org.
410

AUTHOR

412       Maintained by the Monitoring Plugin development team -
413       https://www.monitoring-plugins.org.
414
415       Originally by Ton Voon, <ton.voon@altinity.com>.
416
418       Copyright (C) 2014      by Monitoring Plugin Team Copyright (C)
419       2006-2014 by Nagios Plugin Development Team
420
421       This library is free software; you can redistribute it and/or modify it
422       under the same terms as Perl itself, either Perl version 5.8.4 or, at
423       your option, any later version of Perl 5 you may have available.
424
425
426
427perl v5.32.0                      2020-07-28             Monitoring::Plugin(3)
Impressum