Adding a Script/Batch File-based Test

Many system administrators would not prefer to write Custom tests, by programming in Java. To allow administrators to easily extend eG’s capabilities, the Integration Console includes a Script/Batch File test. This test allows an administrator to simply write a shell script / batch file / VB script / powershell script, which they can incorporate into the Integration Console to provide custom monitoring capability. This section will help you gain a lucid understanding of how to add and configure a new test of the Script/Batch File type.

To illustrate how to add a Script/Batch File test, let us take an example of a DiskSpaceTest, which tracks the disk utilization of a server. In order to create the test, first, click the Add New Test button in the integration console - test page (see Figure 2). In the new test details page (see Figure 1) that appears next, specify the Test name.

Note:

While adding a new test using the Integration Console, ensure that the Test name always ends with _ex. If not, an error message (see Figure 3) will appear upon clicking the Add button in Figure 1.

Since the new test is not a duplicate of any existing test, set the Duplicate flag to No. Then, select Script/Batch File as the Test type. Next, mention the Execution mode. The choice of an execution mode depends upon whether the test is to be executed by an internal agent or an external agent. Since the DiskSpaceTest_ex is to be run only by an internal agent, select the Internal option against the Execution field.

Note:

Using the Integration Console plugin, you can add an internal or an external test, but you cannot add tests that need to be run by a remote agent – i.e., tests that need to be executed in an agentless manner.

Next, as the DiskSpaceTest_ex is to be run at the system level, select No against Port based to enable it to be associated with any of the component types.

Figure 1 : Providing the details of the new test of type Script/Batch File

If the test is to be associated with a shell script file, choose Unix as the OS type. If the test is to be associated with a batch file/VB/powershell script, choose the Windows option. Our DiskSpaceTest_ex is associated with a script, and hence, the Unix option needs to be chosen. Then, click the Add button.

The Parameter tab page will automatically open (see Figure 2). To add a new parameter, click the Add New Parameter button.  However, as the DiskSpaceTest_ex does not take any parameters, click the Measure tab page in Figure 2.

Figure 2 : The Parameter tab page of the DiskSpaceTest_ex

Click the Add New Measure button in the Measure tab page of Figure 3 to add a measure for the DiskSpaceTest_ex.

Figure 3 : The Measure tab page of the DiskSpaceTest_ex

Figure 4 will then appear, using which you can configure the new measure for the DiskSpaceTest_ex. As the test should indicate the percentage of disk space utilized, add PercentUtil as the only measure of this test. Therefore, specify PercentUtil as the Measure name. Then, specify the Database column size, the Unit, Conversion Factor, and the Alarm display string in the same manner as discussed in the previous section.

Figure 4 : Specification of a measure (PercentUtil) of the DiskSpaceTest_ex

In addition to the above, this test type requests the specification of a Process method. By selecting an option from the Process method list box, you can indicate the processing that must be performed on the script / batch file’s output before passing the results to the eG agent. The options offered by this list box are:

Process Methods

Option

Information

UNALTERED

Selecting this option will ensure that no additional information is displayed along with the specified measure in the monitor console. In other words the Current Value of the measure is displayed.

PERCENT_INCREASE

Selecting this option will display the percentage by which the current value of the measure exceeds its previous value (i.e. the value of the measure during the previous test execution). While an increase displays a positive value, a decrease will display a negative value. The formula used is:

[(Current Value – Previous Value) / Previous Value] * 100

PERCENT_DECREASE

This option will display the percentage by which the current value of the measure falls below its previous value. While a decrease displays a positive value, an increase will display a negative value.

[(Previous Value – Current Value) / Previous Value] * 100

PERCENT_CHANGE

This displays the percentage change between the current value and the previous value.

ABS[(Current Value – Previous Value) / Previous Value] * 100

RATIO

This displays the ratio of the current value of the measure over its previous value.

(Current Value  / Previous Value)

RATE

This displays the result of the following formula:

(Current Value - Previous Value) / Time since the last measurement

DIFFERENCE

This displays the absolute value of the difference between the current value and the previous value.

ABS(Current Value – Previous Value)

By default, unaltered is selected as the Process method. In the DiskSpaceTest_ex example, no further processing is required. Hence, the default selection is left as is. Finally, click the Add button to add the measure.

When you are prompted to add more measures for the test (see Figure 5), click No to stop adding any more measures; this is because, the DiskSpaceTest_ex in our example reports only one measure. 

Figure 5 : A message box requesting your confirmation to continue adding measures for the NetShare_cf_ex test

Doing so will instantly open the Generate tab page (see Figure 6). Here, proceed to specify the Path of script/batch File (see Figure 6) associated with the test. Multiple script / batch file paths can also be specified, but remember to separate each entry using a comma.

Figure 6 : Generating a test of type Script/Batch File

Note:

While associating a test with multiple script / batch files, make sure that the “main” script that needs to be executed is specified last. Otherwise, no measures will be reported by the eG Enterprise system.

Any script used for a Script/Batch File test should provide one or more lines of output. If a test is descriptor-based, it can have multiple lines of output, with the first entry of each line being the descriptor. In case of scripts other than VB/powershell scripts, the descriptor and its corresponding measures are separated by whitespaces (space or tab), as shown below:

Output of a (non-VB/non-powershell) script for a descriptor-based test

DESC 1Value 1Value 2 ...Value N

DESC 2Value 1Value 2 ...Value N

.

.

DESC NValue 1Value 2 .Value N

In case of VB/powershell scripts on the other hand, the descriptor and its corresponding measures are separated by “:”, as shown below:

Output of a VB/powershell script for a descriptor-based test

DESC 1:Value 1:Value 2:…:Value N

DESC 2:Value 1:Value 2:…:Value N

.

.

DESC N:Value 1:Value 2:…:Value N

The DiskSpaceTest_ex we have configured is a descriptor-based test and hence, its output would be of the following format (if the script associated with this test is not a VB/powershell script):

/tmp30

/boot22

/usr12

In the above output, /tmp, /boot and /usr are some of the descriptors for the DiskSpaceTest_ex and 30, 22 and 12 are the values of the PercentUtil measure of each of these descriptors. For example, for the /tmp descriptor, the disk space utilized is 30%.

If a test is not descriptor-based, then the script should report only one line of output. The first entry of this line should be “NONE”.

Output of a (non-VB/non-powershell) script for a non-descriptor-based test

NONEValue 1Value 2 ...Value N

Output of a VB/powershell script for a non-descriptor-based test

NONE:Value 1:Value 2:…:Value N

If the DiskSpaceTest_ex we have configured is a non-descriptor-based test, its output would be of the following format (provided, a VB/powershell script is not associated with this test):

NONE30

A script on Linux would look like this:

#!/bin/sh

df -k | grep “/” | awk ‘{print $6 “     “ $5 -1}’

A sample powershell script has also been provided below:

$services = get-service

foreach($service in $services)

{

$name = $service.displayname

$status = $service.status

if($status -eq “Running”)

{

$value = 100

}

else

{

$value = 0

}

Write-Host($name,$value)  -Separator “:”

}

The above script implements a descriptor-based test. This script reports the status of each of the services available on a Windows host.

Find below a sample non-descriptor-based powershell script:

$x = Get-Random -minimum 50 -maximum 101

$y = Get-Random -minimum 25 -maximum 50

$z = $x + $y

$w = $x - $y

Write-Host($x,$y,$z,$w)  -Separator “:”

The above script reports random I/O-related measurements pertaining to a target Windows host.

Note:

Powershell scripts can be executed on only those targets that have Powershell SDK v1/v2 installed.

All the scripts sampled above (the Linux script and the powershell scripts) did not take any arguments. To offer more flexibility in script execution, the Integration Console allows a user to specify multiple arguments for a script/batch file test. When the script/batch file is executed each time, the test’s arguments are passed to the script/batch file. Note that the arguments are typically passed to a script with a hyphen (i.e., ‘-‘) preceding them. Each argument is expected to be followed by its value (e.g., -argument1 <argument1Val> -argument2 <argument2Val>). The script/batch file has to parse the arguments that are passed to it at the time of invocation and perform the appropriate functions.  The following example provides an illustration of how a Linux shell script can parse the arguments provided to it:

#!/bin/sh
# This is an example of a simple script that processes its arguments.

# This script takes two arguments and outputs the values of the arguments.

out1=””;
out2=””;
#out1 and out2 are output variables

while [ $# -ge 1 ]

do

case $1 in

-argument1) shift; out1=$1;;  # if the current argument is argument1

-argument2) shift; out2=$1;;  # if the current argument is argument2

esac

shift;

done

echo “NONE $out1 $out2”

If the script files are present in a remote location, then you can upload them to the eG manager, by clicking on the Choose button adjacent to the Path of script/batch File text box in Figure 6. This will invoke a pop-up window using which you can Browse for the files and specify their location. Finally, click on the Upload button in the pop-up window, to upload the script/batch files in the remote location to the eG manager. However, if the files have already been uploaded to the eG manager, then this procedure can be dispensed with. Instead, just specify the location of the files against the Path of script/batch File text box.

Select the Load file (see Figure 6) check box if:

  • The specified script/batch file has been modified, or
  • The measures are being associated with the script/batch file for the very first time

If the script/batch file has changed, then selecting the Load file check box will ensure that when the test runs, the agent downloads the revised version of the file from the manager, and executes the same. This in turn ensures that the changes take effect. While associating the script/batch file with the test for the first time, it is mandatory to select this check box, as doing so enables the agent to download the file along with the measurements during test execution.

Finally, click the Generate button in Figure 6 to generate the test.

When a test’s measurements are successfully configured and the associated script/batch file has been added to the eG Enterprise system, the eG Enterprise system prompts you to specify the default threshold settings for each of the measurements made by the newly added test (see Figure 7). Click on the measure name in Figure 7 to configure its thresholds.

Figure 7 : Specifying the threshold values of the measures of the DiskSpaceTest_ex