Monitor Type: Custom monitors

Monitor Parameters: Monitor Type

<Prev Databases Index Virtual Machines Next>


Monitor Type: Custom monitors

Monitor Type Properties
Custom monitors
Python script

This monitor type allows to run a Python script and to interpret the script return code and output according to the following rules:

When the script returns zero, its standard output stream is interpreted as follows:

  • The first decimal numeric value found in the stream is treated as a monitor’s Numeric Performance value.

    Note: To be captured correctly the number should be separated by space or punctuation symbol from any text prefix. For example in string “Error code U8566: Windows 98 is not supported” 8566 will not be interpreted as a performance value. It will be 98 instead.

  • Anything else after the number in the stream becomes a monitor’s String Response Value. This value is subject for validation and may be used to change the monitor state as described here.

If script returns non-zero code, its standard error stream (or standard output stream if the former is empty) is interpreted as an error message.

Note: To correctly handle the non-latin characters script should produce output in UTF-8 and be encoded in UTF-8 itself.

Divide returned value by – has the same meaning as for the SNMP monitor; the decimal number that allows scaling performance values to make them valid signed 32-bit integers. Options Take delta and Normalize by time behave accordingly to the ones in aforementioned SNMP monitor.
Because some counter values increase over time and their absolute values are not of interest but deltas are. For example, a counter can return the total number of bytes sent by the network interface while it is important to monitor the number of bytes sent between the polls or per second. To automate this task, you may use Take delta parameter. It instructs the monitoring service to calculate deltas of each of the two subsequent performance values.
You can also check Normalize by time to see the value divided by the number of seconds between polls.
Note that such counters do not show any value until the second poll.

Script Path – is a full path to a Python script that you can enter manually or select using the File Open dialog.

Script Arguments – are arguments that are passed to the script; make sure to quote parts of this string that should be considered as a single argument and may contain spaces.

Script Input – data to be passed to the script standard input. This is useful when the script expects human interaction such as entering passwords. You can use password variables here (as well as in the script arguments).

Authentication section – specifies what Windows account to use. By default, the Monitoring Service Account is used (this is normally LocalSystem), another option is to use the Windows account defined in the Credentials section below.

Note: Python interpreter used to execute the script is configured here in a Settings Dialog.

Script or Program

This monitor type allows to run an external program, batch file or Windows Scripting Host script such as Visual Basic script and to interpret the script output as a performance value and optional text message as described here. Use it to monitor anything that is not covered by the standard monitor types.

Program type Mode – is a radiobutton with the two following options:

  • Run program starts a binary .exe file or batch script.

    Note: program output must be encoded in UTF-8 to let IPHost correctly handle the non-latin characters. If your program produces output in a different encoding you may do the following:

    • Create a Python script monitor instead of this one
    • Use $IPHostInstallDir\scripts\output_to_utf8.py for the Path property
    • For the Parameters use --enc <encoding> <command line> where
      • <encoding> specifies encoding used by your program. It may be one of the supported ones listed here
      • <command line> is a path to your program with arguments.
  • Run script starts Windows Scripting Host script.

    Note: To let IPHost correctly handle the non-latin character script output must be encoded in ANSI or Unicode (also known as UCS-2 LE, UTF-16 LE) and NOT in UTF-8 as Windows Scripting Host does not recognize that encoding.

Nagios Plugin – mode is a checkbox that allows plugging in monitors that conform to the Nagios Plugin API. In this mode the plugin can also calculate a monitor performance state; plugin response code 1 (Nagios WARNING) is mapped to IPHost Network Monitor’s Warning. We provide instructions on how to commence using Nagios plugins via the IPHost Network Monitor’s polling engine, to perform specific monitoring tasks not covered by the other monitor types.

Divide returned value by, Take delta and Normalize by time – all have the same meaning as for the SNMP monitor;
Take delta parameter instructs the monitoring service to calculate deltas of each of the two subsequent performance values.
Normalize by time divides the Delta by the number of seconds between polls.
Divide returned value to make it a valid signed 32-bit integer. In particular, you may specify a value of 0.001 to convert milliseconds to seconds (divide them by 1/1000, that is, multiply by 1000).
Note that counters with Take delta on do not show any value until the second poll.

Program Path – is a full path to a script or program that you can enter manually or select using the File Open dialog. The default location to look for script and program monitors is the scripts/ subdirectory of the program installation directory which contains some useful monitors described here intended to monitor directory size, file content, and HTTP response content.

Program Arguments – are arguments that are passed to the program; make sure to quote parts of this string that should be considered as a single argument and may contain spaces.

Authentication section – specifies what Windows account to use. By default, the Monitoring Service Account is used (this is normally LocalSystem), another option is to use the Windows account defined in the Credentials section below.

SSH (Remote Script or Program)

This monitor type allows to connect to a remote host over SSH and to run any command there. Execution results are interpreted as a performance value and optional text message as described here. Use it to monitor remotely anything that is not covered by the standard monitor types. In particular, you can integrate any already deployed monitoring capabilities for UNIX-based hosts with the IPHost Network Monitor alerting and reporting engine, be it custom scripts, Nagios plugins or interfaces provided by other systems. You can also just measure SSH connecting time using this monitor.

Script execution Mode – is a radiobutton with three options. You can run scripts or commands using either Run Script or Run Nagios Script mode as explained here. In these two cases, the next setting, How to run a script, specifies which script to run as explained below. The last option, Measure Time, disables script execution on the server. Instead, an SSH monitor in this mode just measures the SSH connection time in milliseconds.

How to run a script – a drop down list with three options:

  • Run shell command(s): when you select this option, a single line entry field called Shell command(s) appears. Specify the shell command there; joining multiple commands with pipes (“|” syntax) is supported.
  • Take a script from file: a File name field where you select a local script file to be executed remotely and a Parameters field containing script arguments appear. You should use so called shebang strings to specify command line interpreters. Known supported interpreters are: bash, dash, csh, zsh, perl, python, ruby, nodejs, php.
  • Take a script from the text box below: similar to the previous option, but you write the script directly in a multiline text entry field called Script body. This fits better if the script is short and is not likely to be reused.

Note: To let IPHost correctly handle the non-latin character script or program output must be encoded in UTF-8. If your program or script uses a different encoding, you may want to switch to Run shell command(s) Mode and use pipe as “| iconv -f <encoding> -c -t utf-8” to perform the conversion. Full list of supported encodings can be found by calling locale -m.

Divide returned value by, Take delta and Normalize by time – all have the same meaning as for the SNMP monitor;
Take delta parameter instructs the monitoring service to calculate deltas of each of the two subsequent performance values.
Normalize by time divides the Delta by the number of seconds between polls.
Dividing returned value allows scaling performance numbers to make them valid signed 32-bit integers. In particular, specify value 0.001 to convert milliseconds to seconds (divide them by 1/1000, that is, multiply by 1000).
Note that counters with Take delta on do not show any value until the second poll.

Port (integer, by default 22), is a port to connect to.

Host Key Fingerprint – if this checkbox is checked, the Host Key Fingerprint is compared with the actual fingerprint used by the destination host. When they don’t match, the credentials are not sent to that host and the monitor is considered Down. You can get a current host fingerprint from the error message in the Logs Pane and paste it to the Host Key Fingerprint parameter to make this check succeed.

Authentication – this parameter defines an authentication method to use. Authentication By password uses the credentials selected in the Credentials section below. Authentication By public key uses the values of Path to Public Key File and Path to Private Key File (these should be obtained using the ssh-keygen utility as explained here and registered on your SSH server) as well as Passphrase for a private key. The last authentication method, By public key or password, attempts to authenticate both ways, first by the public key, next by the password.

<Prev Databases Index Virtual Machines Next>