root/src/modules/external.xml

Revision 51133d86a6006bde4c604315dbb7b3b2caa647d2, 4.2 kB (checked in by Philip Maddox <pmaddox@circonus.com>, 1 month ago)

Updated External check docs.

  • Property mode set to 100644
Line 
1 <module>
2   <name>external</name>
3   <description><para>The external module performs checks via external processes like more traditional monitoring systems.  While this approach is far less efficient and does not scale well on a single system, it provides easier transition from existing monitoring systems.  Checks should exit normally with an exit status of 0 for success, 1 or 2 for failure and 3 for unknown.  Exiting with a status of 3 is highly discouraged.  The standard output is provided as the status of the check.</para></description>
4   <loader>C</loader>
5   <image>external.so</image>
6   <moduleconfig>
7     <parameter name="user"
8                required="optional"
9                allowed=".+">The user under which the external checks should be executed.</parameter>
10     <parameter name="group"
11                required="optional"
12                allowed=".+">The group under which the external checks should be executed.</parameter>
13     <parameter name="path"
14                required="optional"
15                default="/"
16                allowed=".+">The path under which all external commands to be executed will be located. Commands outside of this path will not be executed.</parameter>
17     <parameter name="nagios_regex"
18                required="optional"
19                default="\'?(?&lt;key&gt;[^'=\s]+)\'?=(?&lt;value&gt;-?[0-9]+(\.[0-9]+)?)(?&lt;uom&gt;[a-zA-Z%]+)?(?=[;,\s])"
20                allowed=".+">The default regular expression with which to parse Nagios data. Named values are "key", "value", and "uom" (unit of measurement)</parameter>
21   </moduleconfig>
22   <checkconfig>
23     <parameter name="command"
24                required="required"
25                allowed=".+">The path to the command to be executed.  This is the first argument to the execve system call.</parameter>
26     <parameter name="arg0"
27                required="optional"
28                allowed=".+">The program name.  If not specified, it is derived from the command argument. Normal interpolation rules apply.</parameter>
29     <parameter name="arg\d+"
30                required="optional"
31                allowed=".+">The arguments to the program.  The external module will start with arg1 and increment collecting arguments until argN is not found.  Normal interpolation rules apply.</parameter>
32     <parameter name="env_\S+"
33                required="optional"
34                allowed=".+">These parameters allow the setting of environment variables for the command execution.  The text following env_ is the key and the parameter value is the value of the environment variable to be set via execve.</parameter>
35     <parameter name="output_extract"
36                required="optional"
37                allowed=".+">This is a regular expression that is globally applied to the stdout of the command.  Each match is turned into a metric. It is a requirement to used named capturing in the regular expression where "key" is the named match of the metric name and "value" is the named match for the matric value.  A sample for extracting performance data from Nagios commands would be: <![CDATA[(?<key>\S+)=(?<value>[^;\s]+)(?=[;\s])]]>. "NAGIOS" may also be specified as a value, which will configure the external check to do Nagios parsing based on the nagios_regex module configuration parameter.</parameter>
38   </checkconfig>
39   <examples>
40     <example>
41       <title>Checking a service via the /path/to/check_foo command.</title>
42       <para>The hypothetical check_foo command takes a target host with the -H parameter, runs a check and returns its health via exit code and stdout. We set the environment variable QUUX to the value BAZ.  The check is against host 10.10.2.2.</para>
43       <programlisting><![CDATA[
44       <noit>
45         <modules>
46           <module image="external" name="external"/>
47         </modules>
48         <checks>
49           <check uuid="1e8edc38-0d88-11de-93ee-af2195eab5d5"
50                  module="external" name="foo" target="10.10.2.2">
51             <config>
52               <command>/path/to/check_foo</command>
53               <arg1>-H</arg1>
54               <arg2>%[target]</arg2>
55               <env_QUUX>BAZ</env_QUUX>
56             </config>
57           </check>
58         </checks>
59       </noit>
60       ]]></programlisting>
61     </example>
62   </examples>
63 </module>
Note: See TracBrowser for help on using the browser.