1NAME
2 Monitor::Simple - Simple monitoring of applications and services
3
4VERSION
5 version 0.2.8
6
7SYNOPSIS
8 # check services defined in 'my.cfg' and report to the STDOUT
9 use Monitor::Simple;
10 my $args = { config_file => 'my.cfg' };
11 Monitor::Simple->check_services ($args);
12
13 It displays something like this:
14
15 DATE SERVICE STATUS MESSAGE
16 Tue Sep 20 12:15:00 2011 Memory Check 1 Memory WARNING - 70.7% (1064960 kB) used
17 Tue Sep 20 12:15:01 2011 NCBI PubMed page 0 OK
18
19 --- or using a ready-to-use script:
20
21 smonitor -cfg my.cfg
22
23DESCRIPTION
24 The Monitor::Simple allows simple monitoring of applications and
25 services of your IT infrastructure. There are many such tools, some of
26 them very complex and sophisticated. For example, one widely used is
27 *Nagios* (<http://www.nagios.org/>). The *Monitor::Simple* does not aim,
28 as its name indicates, for all features provided by those tools. It
29 allows, however, to check whether your applications and services are
30 running correctly. Its simple command-line interface can be used in cron
31 jobs and reports can be viewed as a single HTML or text page.
32
33 Regarding what it checks, it uses the same concept as *Nagios*: all
34 checking is done by plugins, standalone scripts. And more to it: these
35 plugins are fully compatible with the Nagios plugins. Which means that
36 you either write your own plugins and use them either with
37 *Monitor::Simple* or with *Nagios*, or you can use many existing Nagios
38 plugins and use them directly with the *Monitor::Simple*. For example,
39 the "Memory check" in the synopsis above is an unchanged Nagios plugin.
40
41 Another concept used by *Monitor::Simple* are notifiers. These are again
42 standalone scripts that are called whenever a service/application check
43 is done and there is a notifier (or notifiers) defined to be used. The
44 notification can be sent (or ignored) for every possible check result
45 (errors, OK, all, etc.). Because these *notifiers* are just standalone
46 scripts, one can easily wrapped many existing notifying tools (pagers,
47 SMS senders, etc.); again, many of them are known to Nagios and similar
48 programs.
49
50 Finally, the last "concept" in *Monitor::Simple* is the configuration.
51 The Monitor::Simple uses an XML configuration file defining what
52 services should be checked, how to check them (meaning, what plugins to
53 use) and whom to notify (meaning, what notifiers to use). You can use
54 Monitor::Simple without any Perl programming, just by creating a
55 configuration file (because only you know what services you wish to
56 check) and use it with the provided ready-to-use script smonitor,
57 providing that the few plugins and notifiers distributed with
58 Monitor::Simple are good enough (at least as a starting point). The
59 *smonitor* has its own documentation describing its command-line
60 parameters in details:
61
62 smonitor -man
63
64 However, either way (using *smonitor* or embedding *Monitor::Simple*
65 into your Perl code), you need to write a configuration file. So, let's
66 start with it:
67
68 Configuration file
69 The simplest configuration file is:
70
71 <smon/>
72
73 It does nothing but also it does not complain. Even the root tag "smon"
74 can be anything. But let's talk about more useful configuration files.
75 They have a "general" section and a list of services to be checked in
76 "services" section:
77
78 <smon>
79 <general></general>
80 <services></services>
81 </smon>
82
83 However, it still does nothing. We need to add some services. Each
84 service must have its "id" attribute and a "plugin" section where must
85 be a "command" attribute:
86
87 <smon>
88 <services>
89 <service id="service1">
90 <plugin command="get-date.pl" />
91 </service>
92 </services>
93 </smon>
94
95 This configuration file, finally, does something. It invokes the plugin
96 script "get-date.pl". The script only returns the current date (so it
97 does not do much of the checking) but it returns it in compatible way
98 with all other plugins (also with Nagios plugins). It is good for
99 testing. Here is how it reports (assuming that we named our
100 configuration file "my.cfg"):
101
102 $> smonitor -cfg my.cfg
103 DATE SERVICE STATUS MESSAGE
104 Tue Sep 20 14:05:29 2011 service1 0 Tue Sep 20 14:05:29 2011
105
106 The "service" tag can also have a "name" attribute for a more human
107 readable display name and a "description" tag (used in the HTML format
108 of reports). The "plugin" tag can also have (and usually it has) more
109 sub-tags. They varies depending on the plugin's command. Generally, all
110 additional arguments for a plugin can be defined by the "args" and "arg"
111 tags. They simply specify what will get the plugin on its command-line.
112 For example, the Nagios plugin for checking available memory accepts
113 these arguments:
114
115 <smon>
116 <services>
117 <service id="memory" name="Memory Check">
118 <plugin command="check_mem.pl">
119 <args>
120 <arg>-u</arg> <!-- check USED memory -->
121 <arg>-w</arg> <!-- -w PERCENT Percent free/used when to warn -->
122 <arg>55</arg>
123 <arg>-c</arg> <!-- -c PERCENT Percent free/used when critical -->
124 <arg>80</arg>
125 </args>
126 </plugin>
127 </service>
128 </services>
129 </smon>
130
131 $> smonitor -cfg my.cfg
132 DATE SERVICE STATUS MESSAGE
133 Tue Sep 20 14:23:09 2011 Memory Check 1 Memory WARNING - 66.5% (893584 kB) used
134
135 Read more about specific tags for plugins distributed with
136 *Monitor::Simple* in the "Plugins" section.
137
138 Each service can also have one or more notifiers. Each notifier (see
139 "Notifiers") is an external script defined by the "command" attribute.
140 The script will be executed if the attribute "on" is satisfied. The "on"
141 attribute contains a code or a comma-separated list of codes
142 representing the result of the service check. If the result matches the
143 attribute value (or, in case of a list, any of the values), the notifier
144 is invoked. If you need to use the codes in your Perl programming, they
145 are available as constants *Monitor::Simple::NOTIFY_**. The code values
146 in the configuration files are these:
147
148 NOTIFY_OK => 'ok',
149 NOTIFY_WARNING => 'w',
150 NOTIFY_CRITICAL => 'c',
151 NOTIFY_UNKNOWN => 'u',
152 NOTIFY_ALL => 'all',
153 NOTIFY_ERRORS => 'err',
154 NOTIFY_NONE => 'none',
155
156 There are few other attributes and sub-tags for notifiers, such as
157 *whom* the notification should be sent to. They depend on the type of
158 the notifier - read more about specific attributes and tags for
159 notifiers distributed with *Monitor::Simple* in the "Notifiers" section.
160 Here is an example of a service with two configured notifiers:
161
162 <smon>
163 <services>
164 <service id="date">
165 <plugin command="get-date.pl" />
166 <notifier command="send-email" on="err" email="senger@localhost" />
167 <notifier command="copy-to-file" on="all">
168 <args>
169 <arg>-file</arg> <arg>report.txt</arg>
170 </args>
171 </notifier>
172 </service>
173 </services>
174 </smon>
175
176 Each notifier can also have an attribute "format" specifying the format
177 of the notification. The formats are "tsv" (TAB-separated values),
178 "html" and "human" (plain text). But read about pitfalls of some of
179 these formats in the "Notifiers" section.
180
181 Finally, the notifiers can be also specified in the "general" section of
182 the configuration file. These notifiers are then used for every service
183 (additionally to the notifiers defined in individual services):
184
185 <smon>
186 <general>
187 <notifier command="copy-to-file" on="all" format="tsv">
188 <args>
189 <arg>-file</arg> <arg>report.tsv</arg>
190 </args>
191 </notifier>
192 </general>
193 ...
194 </smon>
195
196 Sometimes, you have a service for which you wish to exclude (to ignore)
197 the general notifiers (those defined in the "general" tag). In such case
198 use the "ignore-general-notifiers" tag:
199
200 <service id="ping-git" name="Ping Git Repository">
201 <ignore-general-notifiers />
202 <plugin command="check-ping">
203 <args>
204 ...
205 </args>
206 </plugin>
207 </service>
208
209 For exploring configuration, the *Monitor::Simple* distribution has
210 directory Monitor/Simple/configs with few examples of configuration
211 files.
212
213 Plugins
214 The plugins are external scripts that are invoked to do the real service
215 checking. Each service has its plugin defined in the configuration file:
216
217 <service id="service1">
218 <plugin command="check-my-service.pl" />
219 </service>
220
221 The plugins usually take some parameters - which are also specified in
222 the configuration files (examples below).
223
224 Because plugins are just external scripts they can be anywhere on your
225 machine. For such cases, you can use the full (absolute) path in the
226 "command" attribute of the plugin. But usually, all (or most) plugins
227 are in a single directory which you can specify in the "general" section
228 of the configuration file:
229
230 <general>
231 <plugins-dir>/some/directory/on/my/computer</plugins-dir>
232 </general>
233
234 Default location for all plugins is a directory "plugins" in the
235 directory where sub-modules of Monitor::Simple are installed. Which
236 means "...somewhere/Monitor/Simple/plugins/".
237
238 There are several rather general plugins distributed with the
239 *Monitor::Simple*:
240
241 Plugin: check-url.pl
242 A general plugin for checking availability of a single URL, using the
243 *HTTP HEAD* method. You can use this plugin to check if the URL of your
244 service or application is not broken, or/and if it returns within a
245 specified timeout period. The configuration is the following:
246
247 <plugin command="check-url.pl">
248 <head-test>
249 <url>http://you.server.org/home/applications.php</url>
250 <timeout>5</timeout>
251 </head-test>
252 ... more <head-test>s can be here...
253 </plugin>
254
255 The "url" tag is mandatory, the "timeout" tag is only optional. There
256 may be more "head-test" sections if you wish to check more URLs by the
257 same plugin call.
258
259 The plugin script is very simple; all the work is actually done by the
260 method "Monitor::Simple::UserAgent->head_or_exit()".
261
262 Plugin: check-post.pl
263 This is a slightly generalized check-url.pl plugin. It can do also the
264 "head-test"s (as the "check-url.pl" does) but its main purpose is to
265 send data to the service using the *HTTP POST* method. It allows you to
266 check whether your service returns expected data. The full configuration
267 is the following:
268
269 <plugin command="check-post.pl">
270 <head-test>
271 <url>...</url>
272 </head-test>
273 <post-test>
274 <timeout>5</timeout>
275 <url>...</url>
276 <data><![CDATA[name=brca1&namespace=geneid&format=html]]></data>
277 <response>
278 <content-type>text/json</content-type>
279 <contains>BRCA1</contains>
280 </response>
281 </post-test>
282 <post-test>
283 <url></url>
284 <data><![CDATA[namespace=geneid&action=table]]></data>
285 <response>
286 <content-type>text/json</content-type>
287 <contains>Alternate_name</contains>
288 <contains>Gene_Symbol</contains>
289 <equal>...</equal>
290 </response>
291 </post-test>
292 </plugin>
293
294 At least one "post-test" section is mandatory, and it has to have a
295 "url" and "data". The response can be checked for the returned *HTTP
296 Content type* or for text anywhere within the response body, or for
297 equality (after trimming heading and trailing white-spaces). More
298 "contains" tags means that all such texts must be found in the response
299 body.
300
301 The plugin script is also simple; all the work is actually done by the
302 method "Monitor::Simple::UserAgent->post_or_exit()".
303
304 Plugin: check-get.pl
305 This is very similar to check-post.pl plugin, except it uses *HTTP GET*
306 method. And, therefore, it does not use "data" tag in the configuration
307 file (because all input data are already part of the "url" tag). It does
308 not use *HTTP HEAD* method.
309
310 Again, it allows you to check whether your service returns expected
311 data. The full configuration is the following:
312
313 <plugin command="check-get.pl">
314 <get-test>
315 <timeout>5</timeout>
316 <url>![CDATA[...]]></url>
317 <response>
318 <content-type>text/json</content-type>
319 <contains>...</contains>
320 <equal>...</equal>
321 </response>
322 </get-test>
323 <get-test>
324 ...
325 </get-test>
326 </plugin>
327
328 At least one "get-test" section is mandatory, and it has to have a
329 "url". The response can be checked for the returned *HTTP Content type*
330 or for text anywhere within the response body, or for equality (after
331 trimming heading and trailing white-spaces). More "contains" tags means
332 that all such texts must be found in the response body.
333
334 The plugin script is also simple; all the work is actually done by the
335 method "Monitor::Simple::UserAgent->get_or_exit()".
336
337 Plugin: check-prg.pl
338 A general plugin that executes any command-line program with the given
339 arguments and then it reports warning if there was any STDERR and it
340 checks the STDOUT for expected values. The full configuration is the
341 following:
342
343 <plugin command="check-prg.pl">
344 <prg-test>
345 <program>...</program>
346 <timeout>...</timeout>
347 <args>
348 <arg>...</arg>
349 <arg>...</arg>
350 </args>
351 <stdout>
352 <contains>...</contains>
353 <contains>...</contains>
354 </stdout>
355 </prg-test>
356 <prg-test>
357 <program>...</program>
358 <timeout>...</timeout>
359 <args>
360 <arg>...</arg>
361 </args>
362 <stdout>
363 <is-integer/>
364 </stdout>
365 </prg-test>
366 </plugin>
367
368 At least one "prg-test" section is mandatory, and it has to have a
369 "program" tag (a program that will be invoked). The STDOUT of the
370 invoked program can be checked that it contains given text. More
371 "contains" tags means that all such texts must be present. It can also
372 make a test that the produced STDOUT is nothing than white-spaces and an
373 integer.
374
375 The "timeout" tag may specify how many seconds to wait for the program
376 completion before it reports timeout warning.
377
378 Again, the plugin script is simple; all the work is actually done by the
379 method "Monitor::Simple::Utils->exec_or_exit()".
380
381 Creating your own plugins
382 Plugins are executed from inside of the main method
383 "Monitor::Simple->check_services()". The method creates one of the two
384 possible types of command-line. One is used for native *Monitor::Simple*
385 plugins. This type is created if there are no "arg" tags in the plugin
386 configuration:
387
388 <plugin-command> -service <id> \
389 -cfg <config-file> \
390 -logfile <logfile> \
391 -loglevel <level> \
392 -logformat <format>
393
394 The "service id" identifies what service this plugin was invoked for.
395 The "-cfg config-file" contains a filename with the XML configuration.
396 From this file, you can get the full configuration by using:
397
398 my $config = Monitor::Simple::Config->get_config ($config_file);
399
400 All command-line arguments can be parsed by calling
401 "Monitor::Simple::Utils->parse_plugin_args()". Therefore, the
402 *Monitor::Simple* native plugin scripts usually start with:
403
404 use Monitor::Simple;
405 use Log::Log4perl qw(:easy);
406
407 # read command-line arguments and configuration
408 my ($config_file, $service_id) = Monitor::Simple::Utils->parse_plugin_args ('', @ARGV);
409 LOGDIE ("Unknown service (missing parameter '-service <id>')\n")
410 unless $service_id;
411 my $config = Monitor::Simple::Config->get_config ($config_file);
412
413 As you see in this example, you can use the logging system by calling
414 "Log::Log4perl" so-called "easy" methods: DEBUG(), INFO(), WARN(),
415 ERROR(), LOGDIE() and LOGWARN(), without doing anything with the
416 log-related arguments.
417
418 If the plugin configuration contains "arg" tags, then the plugin will be
419 invoked with the command-line exactly as defined by these "args" tags.
420 This is how to use plugins written without *Monitor::Simple* support. An
421 example is the Nagios plugin "check-mem.pl". Its configuration looks
422 like this:
423
424 <plugin command="check_mem.pl">
425 <args>
426 <arg>-u</arg>
427 <arg>-w</arg> <arg>75</arg>
428 <arg>-c</arg> <arg>80</arg>
429 </args>
430 </plugin>
431
432 and it will be called with this command-line:
433
434 check_mem.pl -u -w 75 -c 80
435
436 Regarding the results, each plugin is expected to comply with the Nagios
437 plugins standard <http://nagios.sourceforge.net/docs/3_0/pluginapi.html>
438 which means:
439
440 Exit code
441 The exit code should be zero for success and 1, 2 or 3 when the
442 checking failed:
443
444 Exit code Service State
445 0 OK
446 1 WARNING
447 2 CRITICAL
448 3 UNKNOWN
449
450 In your programming you may use the predefined constants in
451 *Monitor::Simple* module:
452
453 use constant {
454 RETURN_OK => 0,
455 RETURN_WARNING => 1,
456 RETURN_CRITICAL => 2,
457 RETURN_UNKNOWN => 3,
458 }
459
460 STDOUT
461 The output can be a single line of text (which is mandatory), or it
462 can be more lines (they are optional).
463
464 TEXT OUTPUT
465 LONG TEXT LINE 1
466 LONG TEXT LINE 2
467 ...
468 LONG TEXT LINE N
469
470 Additionally, the first and the last line can be extended by
471 "performance data" separated by a bar ("|") character:
472
473 TEXT OUTPUT | OPTIONAL PERFDATA
474 LONG TEXT LINE 1
475 LONG TEXT LINE 2
476 ...
477 LONG TEXT LINE N | PERFDATA LINE 2
478 PERFDATA LINE 3
479 ...
480 PERFDATA LINE N
481
482 The *Monitor::Simple* does not do anything special with the
483 performance data, it just leaves them in the report. But you should
484 be aware of it and not to use bar characters in the output of your
485 plugins.
486
487 The *Monitor::Simple* provides few methods that can be useful in your
488 plugins. For example, for checking availability of a URL or for checking
489 contents of a checked web page. See the distributed plugins (and their
490 documentation above) for more details.
491
492 Notifiers
493 The notifiers are external scripts that are called whenever a need for a
494 notification occurs. The notifiers can be specified for individual
495 services, or for all services (see examples in "Configuration file").
496
497 Each notifier is used independently on other notifiers; there is no
498 mechanism collecting them together and sending all notifications in one
499 go. If you need a "collective report" (which you often do) for all
500 services, use rather STDOUT produced by the
501 "Monitor::Simple->check_services()" method. This method can be used in a
502 program (do not forget the ready-to-use such program "smonitor") that is
503 called in a cron job - and the cron job itself takes care about sending
504 an email with the full result, without any notifier. Sending email
505 notifications by using notifiers is more fine-grained: with the
506 notifiers you can send notifications to different email addresses for
507 each service or a group of services.
508
509 Because of the independence of notifiers, some notification formats may
510 be less convenient. You can use without problems the "tsv"
511 (TAB-separated values) format because this format does not produce any
512 header or footer lines. All such notifications can be, therefore,
513 conveniently, appended to a single file keeping the full history of all
514 checking. Other formats, such as "html", are better used for
515 not-so-frequent notifications, such as sending an email if a service
516 failed.
517
518 A notifier is invoked only if the result of a service check matches the
519 code in the "on" attribute of this notifier (again, see the
520 "Configuration file").
521
522 Because notifiers are just external scripts they can be anywhere on your
523 machine. For such cases, you can use the full (absolute) path in the
524 "command" attribute of the notifier. But usually, all (or most)
525 notifiers are in a single directory which you can specify in the
526 "general" section of the configuration file:
527
528 <general>
529 <notifiers-dir>/some/directory/on/my/computer</notifiers-dir>
530 </general>
531
532 Default location for all notifiers is a directory "notifiers" in the
533 directory where sub-modules of *Monitor::Simple* are installed. Which
534 means "...somewhere/Monitor/Simple/notifiers/". This is also the place
535 where you can find the ready-to-use notifiers coming with the
536 *Monitor::Simple* distribution. Each of them has slightly different
537 needs for the configuration:
538
539 Notifier: copy-to-file
540 A notifier appending its notification to a file. Here is how to
541 configure this notifier (either within the "service" tag or within the
542 "general" tag):
543
544 <notifier command="copy-to-file" on="all" format="tsv">
545 <args>
546 <arg>-file</arg> <arg>report.tsv</arg>
547 <arg>-login</arg> <arg>senger@allele</arg>
548 </args>
549 </notifier>
550
551 The mandatory "-file" argument specifies the name of a file (usually
552 with the full path) where the notification will be appended. The
553 argument "-login" allows to use a file on a remote machine, providing
554 the SSH login name. This notifier does not have any provision for
555 specifying a password. Therefore, the user from the "-login" argument
556 must have its public key already installed on the remote machine.
557
558 Notifier: send-email
559 A notifier sending notification to one or more email addresses. Be aware
560 that this could work only if your computer can send emails. If not check
561 the following notifier "send-email-via-ssh".
562
563 Configuration of this notifier uses either attribute "email" or
564 "email-group" or both. Each of this attributes can have one or more,
565 comma-separated, values. Examples are:
566
567 <notifier command="send-email" on="err" email="senger@localhost" />
568 <notifier command="send-email" on="err" email="senger@localhost,kim@localhost" />
569 <notifier command="send-email" on="err" email-group="watch-dogs" />
570 <notifier command="send-email" on="err" email-group="watch-dogs, others" />
571 <notifier command="send-email" on="err" email-group="secrets" email="senger@localhost"/>
572
573 If you use the "email-group" attribute, you need also to tell what
574 addresses this group contains. It is done in the "general" section. For
575 example:
576
577 <general>
578 <email-group id="others">
579 <email>jitka@localhost</email>
580 <email>guest@localhost</email>
581 </email-group>
582 <email-group id="secrets">
583 <email>top.secret@elsewhere.com</email>
584 </email-group>
585 </general>
586
587 Notifier: send-email-via-ssh
588 This notifier does the same as the previous *send-email* except that it
589 first logs-in to a remote machine using SSH and executes the "mail"
590 command there. It is useful when your computer cannot directly send
591 emails - but it requires that you have an SSH account somewhere and that
592 machine has your SSH public key installed (there is no provision for
593 specifying a password in this notifier configuration).
594
595 The configuration attributes for this notifier are the same as for
596 "send-email" (except the different name of the command) and additionally
597 it has the "-login" argument:
598
599 <notifier command="send-email-via-ssh" on="err" email="martin.senger@gmail.com">
600 <args>
601 <arg>-login</arg>
602 <arg>senger@open-bio.org</arg>
603 </args>
604 </notifier>
605
606 Creating your own notifiers
607 The notifiers are invoked - whenever necessary - from inside of the main
608 method "Monitor::Simple->check_services()". The method creates the
609 following command-line:
610
611 <notifier-command> -service <id> \
612 -msg <file> \
613 -emails email1 [email2...] \
614 -logfile <logfile> \
615 -loglevel <level> \
616 -logformat <format> \
617 <additional arguments>
618
619 where additional arguments comes from the configuration file from the
620 "arg" tags specified for this notifier. The "service id" identifies what
621 service this notifier was invoked for. The "-msg file" is a filename
622 with already formatted notification message. Read this file but do not
623 destroy it - other notifiers may want to read it, too. The "-emails..."
624 may not be relevant to your notifier but if there were attributes
625 "email" and/or "email-group" in the notifier configuration they are
626 passed here.
627
628 All basic (not additional) arguments can be parsed by calling
629 "Monitor::Simple::Utils->parse_notifier_args()". Therefore, the notifier
630 script usually starts with:
631
632 use Monitor::Simple;
633 use Log::Log4perl qw(:easy);
634
635 # read command-line arguments
636 my ($service_id, $msgfile, $emails) = Monitor::Simple::Utils->parse_notifier_args (\@ARGV);
637
638 You can continue by parsing the additional arguments (if any). Here is
639 an example from "send-email-via-ssh" notifier:
640
641 # read more command-line arguments specific for this notifier
642 my ($login_name);
643 Getopt::Long::Configure ('no_ignore_case', 'pass_through');
644 GetOptionsFromArray (\@ARGV,
645 'login=s' => \$login_name,
646 );
647 LOGDIE ("Missing parameter '-login' with hostname or user\@hostname\n")
648 unless $login_name;
649
650 And then you do whatever your notifier needs to do. You can use the
651 logging system by calling "Log::Log4perl" so-called "easy" methods:
652 DEBUG(), INFO(), WARN(), ERROR(), LOGDIE() and LOGWARN().
653
654MODULES and METHODS
655 The best way to explore modules, methods and how to use them is to look
656 the *smonitor* script. Here is a short summary what methods are
657 available. The main focus is on methods helping to write your own
658 plugins and notifiers.
659
660 Monitor::Simple
661 This module is a wrapper for all other modules and has only one, but
662 important, method (it is a class method):
663
664 check_services ($args)
665 It loops over all services and checks them (by invoking their plugins).
666 If necessary, it invokes their notifiers. And it produces a summary
667 report about all checks. The $args is a hashref with the following keys
668 and values:
669
670 config_file -> $file
671 A mandatory argument. It specifies what configuration to use.
672
673 outputter => an instance of *Monitor::Simple::Output*
674 This outputter will be responsible for creating the summary report
675 of all checks. If not given, a default outputter is used.
676
677 filter => hashref or arrayref or scalar
678 If any filter given then it contains IDs of services that will be
679 checked (and only them will be checked). Of course, it can still be
680 only services that are defined in the configuration file.
681
682 The scalar is use if you need to check only one service. The
683 arrayref points to a list of service IDs. The hashref has service
684 IDs as keys (values are ignored).
685
686 nonotif => boolean
687 If set to true all notifications (for all services) will be
688 disabled. Default is false.
689
690 npp => integer
691 Maximum number of service checks done in parallel. Default is 10.
692
693 Monitor::Simple::Config
694 This module helps to find and explore the configuration file (that
695 defines what should be monitored). There are no instances of this module
696 (no "new" or similar method), all methods are class methods (but still
697 methods - so use "Monitor::Simple::Config->" to call them).
698
699 resolve_config_file ($filename)
700 It tries to locate given $filename and return its full path:
701
702 a) as it is - if such file exists
703 b) as $ENV{MONITOR_SIMPLE_CFG_DIR}/$filename
704 c) in the directory where the main invoker (e.g. your program) is
705 located
706 d) in one of the @INC directories
707 e) return undef
708
709 get_config ([$filename])
710 It reads configuration from a file and returns it as a hashref. The
711 configuration is looked for in the given $filename or in a default
712 configuration file name. The path to both given and default
713 configuration file is resolved by rules defined in
714 resolve_config_file(). The default configuration file name is in
715 $Monitor::Simple::DEFAULT_CONFIG_FILE.
716
717 extract_service_config ($service_id, $config)
718 Return a hashref with configuration for a given service (identified by
719 its $service_id). If such configuration cannot be found, a warning is
720 issued and undef is returned. The service configuration is looked for in
721 the given hashref $config containing the full configuration (usually
722 obtained by get_config()).
723
724 Monitor::Simple::UserAgent
725 This module deals with the Web communication. It uses *LWP::UserAgent*
726 module to do the communication. It uses only class methods.
727
728 head_or_exit ($service_id, $config)
729 It makes the *HTTP HEAD* test described in check_url.pl plugin. If
730 everything okay it just returns. Otherwise, it exits with the
731 Nagios-compliant reporting (see more about it in report_and_exit()).
732
733 This method uses "head-test" portion of this service configuration.
734
735 post_or_exit ($service_id, $config)
736 It makes the *HTTP POST* test described in check_post.pl plugin. If
737 everything okay it just returns. Otherwise, it exits with the
738 Nagios-compliant reporting (see more about it in report_and_exit()).
739
740 This method uses "post-test" portion of this service configuration.
741
742 Monitor::Simple::Output
743 This module is responsible for outputting the results of service checks
744 in several different formats. It is also used by notifiers to format
745 their notification messages. The main method is "out()" that prints the
746 given message in the given format to the given target, both as defined
747 in the "new()" constructor method.
748
749 new (%args)
750 It creates an instance (an *outputter*) with the given arguments. The
751 recognized keys are:
752
753 config => $config
754 A configuration - the only mandatory argument.
755
756 outfile => $file
757 A destination of the messages.
758
759 onlyerr => 1 | 0
760 It influences where the method "out()" prints its messages. If
761 "onlyerr" is set to 1 (default is 0) only the erroneous messages
762 will be sent to STDOUT. Here are various combinations of "outfile"
763 and "onlyerr" arguments:
764
765 outfile onlyerr what will be done
766 --------------------------------------------
767 yes no all output to file
768
769 yes yes all output to file
770 + errors also on STDOUT
771
772 no no all output to STDOUT
773
774 no yes only errors to STDOUT
775 ---------------------------------------------
776
777 format => tsv | human | html
778 How to format output messages. Default is "human". The list of
779 actually supported formats can be obtained by calling a class method
780 "Monitor::Simple::Output->list_formats()".
781
782 cssurl => $url
783 Used only for "html" format . It points to a URL with the
784 CSS-stylesheet for the output. By default, it uses stylesheet
785 similar to the one shown in the distribution in file
786 Monitor/Simple/configs/monitor-default.css.
787
788 list_formats
789 A class method. It returns a hashref with a list of actually supported
790 formats (keys) and their description (values). At the time of writing
791 this document, it returns:
792
793 { tsv => 'TAB-separated (good for machines)',
794 human => 'Easier readable by humans',
795 html => 'Formatted as an HTML document' }
796
797 out ($service_id, $code, $message)
798 It formats and outputs one message about a just finished service check
799 (with an additional date field). $service_id defines what service is the
800 report about, $code indicates what kind of message is being outputted
801 (see $Monitor::Simple::RETURN* constants) and $msg is the real message.
802
803 This method outputs one message, nothing before and nothing after it.
804 Because some formats needs also a header and possible a footer, there
805 are also methods "header" and "footer".
806
807 header ([$header])
808 It outputs a header line (in the format specified in the "new()"
809 constructor). The content of the header is either taken from the $header
810 argument or a default one is used.
811
812 footer ([$footer])
813 It outputs a footer line (in the format specified in the "new()"
814 constructor). The content of the footer is either taken from the $footer
815 argument or a default one is used.
816
817 Monitor::Simple::Notifier
818 This module is responsible for deciding whether a notification should be
819 sent and for sending it. The main method is "notify()" that actually
820 does first the decision if the notification should be sent and then
821 sending it using its own "outputter", an instance of
822 *Monitor::Simple::Output*.
823
824 new (%args)
825 It creates an instance (an *outputter*) with the given arguments. The
826 recognized keys are:
827
828 config => $config
829 A configuration - the only mandatory argument. Actually, so far, the
830 only argument.
831
832 notify ($result)
833 Given a $result of a service check, it makes all expected notifications
834 (as defined in the $config given in the "new()" constructor). The
835 $result is a hashref with this content:
836
837 { service => $service_id,
838 code => $code,
839 msg => $msg }
840
841 Monitor::Simple::Log
842 log_init ($logging_options)
843 It initiates logging (using the *Log::Log4perl* module).
844 $logging_options is a hashref with the keys "level", "file" and "layout"
845 (some or all keys may be missing). The level is a (case-insensitive)
846 text acceptable by the method "Log::Log4perl::Level::to_priority()":
847 "debug", "info", "warn", "error" or "fatal". The file is where the log
848 will be created to. Value STDOUT is also accepted. Finally, the layout
849 is a format of the log messages as defined by in Log::Log4Perl; default
850 value being
851
852 %d (%r) %p> %m%n
853
854 When writing a plugin or a notifier, this method is called for you
855 automatically from the parse_plugin_args() or parse_notifier_args().
856
857 get_logging_options
858 It returns currently used logging options - in the same format as the
859 same options are define in log_init().
860
861 Monitor::Simple::Utils
862 This module is a container for various methods that did not fit
863 elsewhere. There are no instances of this module (no "new" or similar
864 method), all methods are class methods (but still methods - so use
865 "Monitor::Simple::Util->" to call them).
866
867 parse_plugin_args ($default_service_id, @args)
868 It reads plugin's command-line arguments @args. It returns two-element
869 array with the configuration file name (may be undef) and service ID (if
870 the service id is found in @args, it uses $default_service_id). It uses
871 logging options (if any found in @args) to set the logging system. Read
872 about possible arguments in @args in "Plugins".
873
874 report_and_exit ($service_id, $config, $exit_code, $return_msg)
875 It prints $return_msg on the STDOUT and exits with the $exit_code.
876 $config is not used (at least now) and can be undef. This method is
877 usually the last call in your plugin.
878
879 exec_or_exit ($service_id, $config)
880 It executes an external program with the given arguments and
881 (optionally) checks its STDOUT for the given content. If everything okay
882 it just returns. Otherwise, it exits with the Nagios-compliant reporting
883 (see more about it in report_and_exit()).
884
885 This method uses "prg-test" portion of this service configuration.
886
887 parse_notifier_args ($args)
888 It reads plugin's command-line arguments $args (an arrayref - so the
889 recognized arguments can be removed from the provided array). It returns
890 a three-element array with a service ID, a file name with the
891 notification message and a reference to an array with all email
892 addresses (may be empty for some notifiers). It uses logging options (if
893 any found in $args) to set the logging system. Read about possible
894 arguments in $args in "Notifiers".
895
896BUGS
897 Please report any bugs or feature requests to
898 <http://github.com/msenger/Monitor-Simple/issues>.
899
900 Known bugs and limitations
901 Locking remote files
902 The *copy-to-file* notifier adds notification messages to a file on
903 a remote machine (if it is configured to use SSH) and it does it
904 without any concern about the potential need of exclusively locking
905 that file (it may be accessed in the same time by many notifiers).
906 It is this way because it uses program "cat" which, as far as I
907 know, does not do locking.
908
909 Similarly, log files are not using any locking.
910
911ACKNOWLEDGMENT
912 Thanks to Gisbert W. Selke "<gws@cpan.org>" the tests should be now
913 working also under Windows. He also provided a new version of the
914 "check_mem.pl" - under the name *check_mem2.pl* - a plugin, that should
915 work both under Windows and Unix.
916
917AUTHOR
918 Martin Senger <martin.senger@gmail.com>
919
920COPYRIGHT AND LICENSE
921 This software is copyright (c) 2013 by Martin Senger, CBRC-KAUST
922 (Computational Biology Research Center - King Abdullah University of
923 Science and Technology) All Rights Reserved.
924
925 This is free software; you can redistribute it and/or modify it under
926 the same terms as the Perl 5 programming language system itself.
927
928