Creating Plug-in Service Monitors in up.time

\n

\n \n

\n \n

Article \nContents \n

\n \n

\n \n
• Formatting \nyour monitoring station script for a plug-in service monitor
\n \n
• Changing \nthe check_temp script for use within a plug-in service monitor
\n \n
• Creating \nthe XML definition for your plug-in service monitor
\n \n
• Importing \nand managing your XML plug-in monitor definition
\n \n
• Adding \nInstances of your plug-in service monitor
\n \n

\n \n

---

\n

Overview
\n \n

\n \n

Plug-in service monitors allow you to add service \nmonitors directly into the up.time interface. You can use plug-in \nservice monitors to check, alert on and graph your own custom \napplication or business metrics. Plug-in in monitors have the following \nbenefits: \n

\n \n

\n \n \n
• Plug-in monitors \nenable you create more meaningful graphs with customized headings for \nyour retained application and business metrics.
\n \n
• They are installed \ndirectly into the up.time interface, beside the standard up.time \nservice monitors. Your plug-in monitors are as transparent as other \nmonitors to your end users.
\n \n
• Creating instances \nof your monitor much easier using a standard service monitor template \nthat you define. Once you create your monitor template you never have \nto remember the exact arguments or location of your custom script, they \nare included right in the interface automatically.
\n \n \n

\n \n \n

Example graph produced using a plug-in \nmonitor.
\n \n
\n \n

\n \n

The process of updating your existing scripts and service monitors to be \nplug-in monitors can usually be \ncompleted in just a few minutes. This article builds on the scripts and \nknowledge that were developed in previous articles. Take some time to \nreview the previous articles before continuing.

\n \n

---

\n

Formatting your monitoring \nstation script for retained data tracking
\n \n

\n \n

To format your custom script for use with a plug-in monitor, \nyou will only need to make changes to the way that it outputs \ninformation when the script is run. Instead of printing a \nnumber to screen on individual lines -- like the Custom with Retained \nData -- you must also print a variable name along with the numerical or \nstring value. Choosing a variable name is the most important part of \nsetting up the plug-in monitor. The variable name must be exactly the \nsame within your script output and the XML definition for your service \nmonitor. This is discussed later in this article.

\n \n

The format of plug-in monitor output is included below along \nwith an example set of output that includes two integer variables (transactions \nand users) \nand two string values (lasterror \nand connectmsg). The output format is a simple name and value pairing, the variable naming coming first on a line and the value for that variable following it. \n

\n \n

Expected format:
\n \nvariable value
\n \nvariableX valueX
\n \n
\n \nExample Script Execution and Output
\n \n> gather_data.sh
\n \ntransactions 2398
\n \nusers 5
\n \nlasterror Error opening user connection!
\n \nconnectmsg Connection refused
\n \n

\n \n

---

\n

Changing the check_temp script \nfor use within a plug-in service monitor
\n \n

\n \n

Using the check_temp.sh \nscript as an example, change the output format so that it can be used \nwithin a plug-in monitor. You must first decide what to call \nthe variables that the script will output. Currently, the \nscript outputs temperature and relative humidity -- name the \ntwo variables temp \nand rh. 

\n \n

Next, change the output of the script check_temp.sh \nas detailed below: \n

\n \n

\nPrevious Format - For a custom service monitor with retained \nperformance data.
\n \n> ./check_temp.sh test-agent 9998
\n \n64.5
\n \n32.8
\n \n

\n \n
\n \n

\nNew Format - For use within a plug-in service monitor, notice that we \nhave added our variable names to the output lines:
\n \n> ./check_temp.sh test-agent 9998
\n \ntemp 64.5
\n \nrh 32.8
\n \n

\n \n

If you look back through the examples in previous articles, \nyou will notice that the output format from the monitoring station \nscript above now matches that of the agent side script. Note \nthat this is not always the case, but works well for this example.

\n \n

In order for the check_temp.sh \nscript to produce the output listed above, edit the script so that it \nmatches the example below:

\n \n

\n#!/bin/sh
\n \n
\n \n# This script takes the following arguments:
\n \n# check_temp.sh hostname port
\n \n# Example execution:
\n \n# ./check_temp.sh my-agent 9998
\n \n
\n \n# This script can be placed anywhere on the monitoring station system as long as it is
\n# executable by the uptime user.
\n \n
\n \n#First, collect our arguments
\nAGENT=$1
\nPORT=$2
\n
\nTMPFILE=/tmp/$$.temp
\n \n
\n \n# now use the info above to contact the agent, store the output in a file for parsing
\n \n`echo -n rexec secretpassword /opt/uptime-agent/my-scripts/show_temp.sh \nmy-arguments | /usr/local/uptime/bin/netcat $AGENT $PORT > $TMPFILE`

\n \n

Note: If you are using agentcmd instead of netcat, replace netcat with agentcmd in the command above. For example:

\n \n

`/usr/local/uptime/scripts/agentcmd -p $PORT $AGENT rexec secretpassword /opt/uptime-agent/my-scripts/show_temp.sh my-arguments > $TMPFILE`

\n \n

For more information on the syntax used with agentcmd, see this Knowledge Base article.

\n \n

\n# we have the output from the agent. If it is ERR that means there was a problem running the script on the agent
\n \n`grep ERR $TMPFILE`
\n \nif [ $? -eq 0 ]
\n \nthen
\n \necho "Could not execute agent side script!"
\n \n# by exiting with a 2 we are forcing a CRIT service outage
\n \nexit 2
\n \nfi
\n \n
\n \n# because our agent side script produces output that fits into the \nplug-in monitor format
\n \n# we don't have to format our output at all, simply print it to the \nscreen and we are finished.
\n \n
\n \ncat $TMPFILE
\n \n
\n \nexit 0
\n \n

\n \n

---

\n

Creating the XML definition for \nyour plug-in service monitor
\n \n

\n \n

To integrate the plug-in monitor with up.time, you must \nproduce an XML definition that up.time will use to understand how to \nprocess your custom script and what options should be displayed within \nthe up.time interface. To create your XML definition browse to the Plug-in \nService Monitor XML Generation Tool and follow the steps on screen. 

\n

This page will be your primary \ntool to create and edit your XML definition files. If you want to further customize the XML definition of your plug-in \nmonitor, please contact [email protected]for assistance. \nBefore you use the XML Generation Tool, have the following information \nabout your plug-in monitor available: \n

\n \n

\n \n
• The name of your monitor, which will appear in the up.time services list. This name \nmust be unique.
\n \n
• The full path to \nyour custom script
\n \n
• For each variable \nthat your script produces:
\n \n
\n \n
• Var Name: this \nmust match the output variable name and be only one word.
\n \n
• Title: for \ninstance if your variable was named 'temp' an appropriate title may be \n'Temperature'
\n \n
• Description: Full description \nof the variable.
\n \n
• Unit: if the \nvariable should have a unit associated with it for graphing
\n \n
• Type: Either \nString or Decimal based on the value for your variable.
\n \n
\n \n

\n \n \n

Once you have generated your XML file, save it to your \nmonitoring station in the UPTIME_DIRxml folder and continue to the \nnext step. Below is an example screen shot of the options used to \ncreate an XML definition for the check_temp.sh script. The XML file \nthat these options produce is attached to this article.

\n \n \n

Example options used to produce XML for \ncheck_temp.sh.
\n \n
\n \n

\n \n

---

\n

Importing and managing your XML \nplug-in monitor definition
\n \n

\n \n

Now that you have both the XML definition for your custom \nscript and your custom script in place, you can import your \nplug-in monitor into up.time. You use the erdcloader and erdcdeleter to import and export your plug-in monitor. Examples \nof the options for these commands are included below.

\n \n

The UPTIME_DIRscriptserdcloader utility is used to import \nyour plug-in monitor XML definition as a service monitor template \nwithin up.time.
\n \n

\n \n \n \n

\nExample Execution:
\n \n> cd UPTIME_DIR
\n \n> scripts/erdcloader -x MyMonitor.xml
\n \n

\nThe UPTIME_DIRscriptserdcdeleter utility is used to \nremove your plug-in monitor template from up.time.
\n \n

\n

\n \n

\n \n

Example Execution:
\n \n> cd UPTIME_DIR
\n \n> scripts/erdcdeleter --list
\n \n.
\n \n.
\n \n.
\n \nMy test monitor template
\n \n> scripts/erdcdeleter --name "My test monitor template"
\n \n

\nWhile working with your XML definition and \nensuring that your service monitor works correctly, you will probably run each of \nthese commands a number of times. Below is a quick example of the \noutput expected when importing the check_temp.xml template using the \nerdcloader utility. \n \n

> cd UPTIME_DIR
\n \n> ls scripts/check_temp.sh
\n \nscripts/check_temp.sh
\n \n> ls xml/check_temp.xml
\n \nxml/check_temp.xml
\n \n> scripts/erdcloader -x xml/check_temp.xml
\n \n2006-05-12 17:09:03,376 DEBUG (HibernateManager:178) - Configuring \ndatabase for: mysql
\n \n2006-05-12 17:09:08,743 DEBUG (ERDCXmlParser:56) - Plug-in monitor: \nTemp and Humid
\n \n

\n \n

Now that the plug-in monitor has been imported, you can browse to \nthe Add Service Instance page in the up.time user interface and see the \nplug-in monitor listed, as shown below:

\n \n

\n \n

---

\n

Adding Instances of your plug-in \nservice monitor

\n \n

To add an instance of your plug-in service monitor, browse to \nthe Add Service Instance list, select your plug-in service monitor, and click Continue. The options displayed on the monitor template match the definition that you created with the XML generation tool. The service monitor settings that would \nappear based on the example XML definition are shown below: \n

\n \n

\n