Page History

...

Now that we've talked about the details that go into a plugin's XML file, let's take a look at how these input variables are displayed in the UIM GUI when creating an instance of the Custom Remote Monitor:

• The first thing you 'll notice is that we don't see either the process_windows or process_linux fields, but that's to be expected here, as those fields where set as hidden.
• The contents of the password field are obscured, as expected. 
• The Remote Script & and Arguments fields are basic string fields.
• You can also see the two output values for this monitor, but we'll talk about those more later. 

...

Next let's take a look at how all these parameters and input fields come together as the environment variables that are used by the script itself. Environment variables aren't normally / displayed or retained by the service monitor when it runs, but they're easy to capture for testing /and debugging purposes by adding the appropriate command to your shell/bat script:

...

Here's a few things you should notice about these values: 

• They all start with UPTIME_ and the contents of the name attribute from the element tag. 
• The UPTIME_HOSTNAME has the hostname of the element the monitor is running against.
• The rest of our remaining input variables show - up as expected with the same contents as we set in the GUI example above. 

...

Now let's take a quick look at what the custom_remote.bat and custom_remote.sh scripts actually do with these environment variables. As mentioned above, most of the Uptime Infrastructure Monitor UIM-provided plugins rely on a common PHP script to perform the actual task of monitoring. As such, the bat and sh scripts are just responsible for telling Uptime Infrastructure MonitorUIM's bundled php executable to run the required script, and then pass along the environment variables in the correct order. The specifics of how this done obviously varies between both Windows and Linux, so let's take a look at both methods.

...

From the example here, you can see that windows allows you access environment variables by wrapping the name in % characters, i.e. % UPTIME%UPTIME_HOSTNAME%. So we've used that to arrange the input variables from xml into the order expected by the rcs.php script. You may also notice the ..\..\..\apache\php\php.exe path used to start php. Whenever a script monitor is triggered the current working directory is set to the location of the
script itself, which is in this case is 'is C:\Program Files\uptime software\uptime\plugins\scripts\monitor-custom-remote\monitor-custom-remote.bat'. But the location of the uptime UIM directory can vary depending on where it was initially installed. So we use a relative path from the plugin's location to find find <uptime_dir>\apache\php\php.exe. When making your own plugins, you can usually simplify this by using the hardcoded hard-coded path of your uptime UIM directory.

For more information about this feature, see monitor-custom-remote.sh on GitHub.

#!/bin/sh 

inst=`grep ^inst /etc/init.d/uptime_httpd | cut -d= -f2`
MIBDIRS=$inst/mibs
export MIBDIRS

/usr/local/uptime/apache/bin/php rcs.php -h=$UPTIME_HOSTNAME -p=$UPTIME_PORT -s=$UPTIME_PASSWORD -c=$UPTIME_REMOTE_SCRIPT -a=$UPTIME_ARGS

In the case of the linux Linux shell script, we can access the contents of our environment variables by prefacing the name with the $ symbol. We then pass the same input variables along to php in the same order as in the bat script above. Just like on Windows, the current working directly is set to the location of plugin script itself, but in this case we can use the contents of the /etc/init.d/uptime_httpd script to find the location the Uptime Infrastructure Monitor UIM install directory and use to that to set the location of an extra MIBDIRS environment. This is only required for PHP scripts on linuxLinux, so that the php_snmp library doesn't complain about being unable to find it's mibdirs. If your you are not using php in your own script, you can ignore this completely. The other thing worth noticing here is that we've hardcoded the path of Uptime Infrastructure MonitorUIM's bundled php executable, as uptime's the Apache folder is always installed into the default location of /usr/local/uptime/apache even if Uptime Infrastructure Monitor UIM was installed elsewhere, this . This prevents us from using the same relative path method as we did on Windows. 

We won't get into the details of the rcs.php script itself as this will typically change depending on the details of the plugin itself. But the full contents of this file on GitHub here if you are interested.

Output variables

Now that weWe've looked at all the details that go into a plugin scripts input variables . All all the way from the xml file, the Edit Service Monitor Screen, and how they finally get exposed to the custom script as environment variables. LetNow let's take a look at how a custom monitor can return it's output back to Uptime Infrastructure MonitorUIM, and the different things we can do it with.

...

Just like input variables, output variables are also defined in the xml file via the same element tags. They're covered by the same basic rules outlined above, and full details for their XML definitions are available here: 'Integration Guide -> in the Plugin Guide'.

Below is are the two output variables that are defined in the Custom Remote Monitor's xml file. For reference the full version of this file is available on GitHub here GitHub here.

            <element name='custom1' parameter_type='output' data_type='string' gui_basic='1' range_type='0' units=''>
                 <control_options>size:8</control_options>
                 <default_value></default_value>
                  <short_description>Output</short_description>
                  <long_description>Output from the script</long_description>
                  <validation_rule/>
                  <error_message/>
                  <gui_type>
                        <string/>
                  </gui_type>
            </element>
            <element name="timer" parameter_type="output" data_type="integer" gui_basic="0" range_type="0" units="ms">
                  <control_options>size:8</control_options>
                  <default_value/>
                  <short_description>Response time</short_description>
                  <long_description>Response time in ms</long_description>
                  <validation_rule/>
                  <error_message/>
                  <gui_type>
                        <integer/>
                  </gui_type>
            </element>
      </elements>
      <help>Execute remote scripts via the up.time agent. Output from the remote string is returned as String Data.</help>
</uptime>

Here's some things you notice about these examples:

• Both In both cases, the parameter_type is set as output . This tells uptime UIM that this is output we expect to see back form the script.
• There's an optional unit attribute in the element tag, which is used to show that the response time is being stored in ' milliseconds' . This unit will is also be displayed when graphing these metrics within Uptime Infrastructure MonitorUIM.
• We have an example of both the integer & string and string data_types, which in the case of output variables controls what type of threshold comparisons can be used to set the monitors WARN/CRIT status. Integer type values allow for Greater Than/Less Than greater/less than numerical comparisons. Where-as strings have contains/does not contains and regex-style comparisons.

Now that we've see what the output variables look like in the xml itself, lets take a look at what the script needs to return so that Uptime Infrastructure Monitor UIM knows which output variable is which. This is based on the element tag's name attribute. Which , which is used to look for a line of output from the script that starts with that name, which in the case above is 'custom1'. The rest of that line will is then be pulled into Uptime Infrastructure Monitor UIM as the variable and can used for threshold comparisons. In our example here, this custom1 variable will be is treated as string. In monitors with multiple output variables, the output from the script itself can come any order, but any lines that don't start with the name of a variable will be are ignored.

The 'timer' output variable is a special case that will always contain contains the time it took takes the service monitor to run in milliseconds. This doesn't need to be provided as part of the output from your custom script.

The best way to understand how this works it to look at the output on the ' Test Service Monitor ' screen. Which will show screen, which shows you the raw output from the service monitor, and then a list of any output variables that Uptime Infrastructure Monitor UIM was able to parse out based on their names. For an example here, we'll use the ' custom remote monitor ' with an agent side script called ' check-uptime ' which returns output similar to:

...