Endpoint Operations Management Agent Plug-in Development Kit A script plug-in uses the org. hyperic hq- product. DaemonDetector support to discover resources from the process table- DaemonDetector runs a PTQL processquery Script Plug-in Contents and Packaging A script plug-in comprises the following components An XML plug-in descriptor that defines the monitored process and its properties, along with the metrics that the script reports. A script that returns metric name: value pairs You can embed your script in the XML plug-in descriptor, in which case you deploy only the XML file If your script is in its own file, you reference it in the descriptor, and deploy an archive containing the script and the descriptor. Save the script in AgentHome/bundles/AgentBundleDir/pdk/scripts/, or in the XML descriptor Requirements for script Note the following requirements for writing a script plug-in The script can be written in any required language. For example, Batch for Windows and Shell for Linux A measurement script must report metrics as name-value pairs. For example %./pdk/scripts/device_iostat pl sda rrgm/s=0. 02 w/s=0.54 rsec/s=2.00 wsec/s=. 06 avgqu-5Z=e ee ait=4.21 svctm=1.75 ‰util=0.11 Unicode characters must be escaped Unicode characters in a script are decoded during script processing. For example, the string %3D decoded to an equals sign(). To preserve the value of s string that might be interpreted as a unicode character, escape the string with a double backslash, for example: \\%3D Defining the proxy Resources in the plug-in Descriptor If the plug- in manages a single process, model the monitored process as a platform service. Specify it in a <service> element in the root <plugin> element of the descriptor
A script plug-in uses the org.hyperic.hq.product.DaemonDetector support to discover resources from the process table — DaemonDetector runs a PTQL process.query. Script Plug-in Contents and Packaging A script plug-in comprises the following components. n An XML plug-in descriptor that defines the monitored process and its properties, along with the metrics that the script reports. n A script that returns metric name: value pairs. You can embed your script in the XML plug-in descriptor, in which case you deploy only the XML file. If your script is in its own file, you reference it in the descriptor, and deploy an archive containing the script and the descriptor. Save the script in AgentHome/bundles/AgentBundleDir/pdk/scripts/, or in the XML descriptor. Requirements for Script Note the following requirements for writing a script plug-in. n The script can be written in any required language. For example, Batch for Windows and Shell for Linux. n A measurement script must report metrics as name-value pairs. For example, % ./pdk/scripts/device_iostat.pl sda rrqm/s=0.02 wrqm/s=0.59 r/s=0.07 w/s=0.54 rsec/s=2.00 wsec/s=9.06 avgrq-sz=17.95 avgqu-sz=0.00 await=4.21 svctm=1.75 %util=0.11 n Unicode characters must be escaped. Unicode characters in a script are decoded during script processing. For example, the string %3D is decoded to an equals sign (=). To preserve the value of s string that might be interpreted as a unicode character, escape the string with a double backslash, for example: \\%3D. Defining the Proxy Resources in the Plug-in Descriptor If the plug-in manages a single process, model the monitored process as a platform service. Specify it in a <service> element in the root <plugin> element of the descriptor. Endpoint Operations Management Agent Plug-in Development Kit VMware, Inc. 11
Endpoint Operations Management Agent Plug-in Development Kit If the plug-in manages a server and its component services, script reports on a multiple services, create a server-service hierarchy. Specify the parent <server> element in the root <plugin> element of the descriptor, and specify each of the component services as a child <service> element Defining Management Functions in a Script plug-in A script plug-in can perform various management functions, including auto-discovery, measurement and control Auto-Discovery Script plug-ins use the org. hyperic hq. product. Daemon Detector auto-discovery support class to discover a process. DaemonDetector requires a PTQL process query Determine the PTQL statement that identifies the target process. The most common query types for discovering a process are Query Type State Name eq=BASENAME Where BASENAME is the base name of the process executable(or regex )and uniquely identifies Pid. PidFile eq=PIDFILE Where PIDFILE is the path and name of the process PID file. For example, Pid. PidFile eq=/var/run/sshd. pid This query is useful if the process base name does not uniquely identify the process Pid Service. eq=SERVICENAME Where SERVICENAME is the name of the process. This query is useful in Windows environments. For example, Pid Service. eq= Eventlog You can supply multiple, comma-separated PTQL queries, if necessary For a Java process, you typically must specify command line arguments for the process to identify it. To define auto-discovery in the plug-in descriptor, if you have defined a server-service hierarchy, in the <server> define a <property> element whose name is HAS_BUILTIN_SERVICES and value="true",so that component services are discovered When you define the auto-discovery function, identify org. hyperic hq. product. Daemon Detector as the class that performs it in a <plugin> element whose type is"autoinventory" If you defined a server- service hierarchy, put the <plugin> element in the <server> element. If the plug-in manages a single service, put it in the <service> element that models the process to discover You also need to define the process query in an <option> element whose name is process query and whose default is the PTQL query in the same resource element that contains the <plugin> element Measurement Script plug-ins use the org. hyperic hg product Measurement Plugin class to report the metrics returned by the scripts. Measurement Plugin accepts metric name: value
If the plug-in manages a server and its component services, script reports on a multiple services, create a server-service hierarchy. Specify the parent <server> element in the root <plugin> element of the descriptor, and specify each of the component services as a child <service> element. Defining Management Functions in a Script Plug-in A script plug-in can perform various management functions, including auto-discovery, measurement and control. Auto-Discovery Script plug-ins use the org.hyperic.hq.product.DaemonDetector auto-discovery support class to discover a process. DaemonDetector requires a PTQL process query. Determine the PTQL statement that identifies the target process. The most common query types for discovering a process are: Query Type Description State.Name.eq=BASENAME Where BASENAME is the base name of the process executable (or regex ) and uniquely identifies it. For example, State.Name.eq=crond . Pid.PidFile.eq=PIDFILE Where PIDFILE is the path and name of the process PID file. For example, Pid.PidFile.eq=/var/run/sshd.pid. This query is useful if the process base name does not uniquely identify the process. Pid.Service.eq=SERVICENAME Where SERVICENAME is the name of the process. This query is useful in Windows environments. For example, Pid.Service.eq=Eventlog. You can supply multiple, comma-separated PTQL queries, if necessary. For a Java process, you typically must specify command line arguments for the process to identify it. To define auto-discovery in the plug-in descriptor, if you have defined a server-service hierarchy, in the <server> define a <property> element whose name is HAS_BUILTIN_SERVICES and value="true", so that component services are discovered. When you define the auto-discovery function, identify org.hyperic.hq.product.DaemonDetector as the class that performs it in a <plugin> element whose type is "autoinventory". If you defined a serverservice hierarchy, put the <plugin> element in the <server> element. If the plug-in manages a single service, put it in the <service> element that models the process to discover. You also need to define the process query in an <option> element whose name is process.query and whose default is the PTQL query in the same resource element that contains the <plugin> element. Measurement Script plug-ins use the org.hyperic.hq.product.MeasurementPlugin class to report the metrics returned by the scripts. MeasurementPlugin accepts metric name:value pairs. Endpoint Operations Management Agent Plug-in Development Kit VMware, Inc. 12
Endpoint Operations Management Agent Plug-in Development Kit You define the measurement function and identify Measurement Plugin as the class that performs it in a <plugin> element whose type is measurement. If you have defined a server-service hierarchy, put the <plugin> element in the <server> element. If your resource " hierarchy"is simply a single platform service, put <p lugin> element in the <service> element that models the process You must also define a <metric> element for each metric reported by the script. You must define at least the name, indicator, and template attributes The form of a metric template for a metric collected by a script is exec: timeout=TIMEOUT, exec=PREFIX, file=FILENAME, exec=MODE, args=ARGUMENTS: METRIC where TIMEOUT The time in seconds to wait for a response when the script runs. Optional, but recommended. PREFIX The script prefix, for example, sudo FILENAME The path and name of script that retums the metric. Mandatory ARGUMENTs A space-separated list of argument values to pass to the script METRIC The name of the metric For example, exec: timeout=10, exec=sudo, file=pdk/scripts/metric_script. pl, args=sda: w/s Script Plug-in Examples Use these examples to help you create your own script plug-ins Control Script Example <?xml version="1.0"encoding="UTF-8"?> <plugin name="hqcont-l-script-solution"> <script name="controlscript bat"> echo controlscript called /script <script name="controlscript sh"> <I [CDATAL #Ish echo controlscript called /script> <server name="HQCoNT-l My Control Server"> <property name="PROC_QUERY value="State Name. eq-firefox"/> <config> option default="State Name eq=firefox
You define the measurement function and identify MeasurementPlugin as the class that performs it in a <plugin> element whose type is measurement. If you have defined a server-service hierarchy, put the <plugin> element in the <server> element. If your resource "hierarchy" is simply a single platform service, put <plugin> element in the <service> element that models the process. You must also define a <metric> element for each metric reported by the script. You must define at least the name, indicator, and template attributes. The form of a metric template for a metric collected by a script is: exec:timeout=TIMEOUT,exec=PREFIX,file=FILENAME,exec=MODE,args=ARGUMENTS:METRIC where TIMEOUT The time in seconds to wait for a response when the script runs. Optional, but recommended. PREFIX The script prefix, for example, sudo. FILENAME The path and name of script that returns the metric. Mandatory. ARGUMENTS A space-separated list of argument values to pass to the script. METRIC The name of the metric. For example, exec:timeout=10,exec=sudo,file=pdk/scripts/metric_script.pl,args=sda:w/s. Script Plug-in Examples Use these examples to help you create your own script plug-ins. Control Script Example <?xml version="1.0" encoding="UTF-8"?> <plugin name="hqcont-1-script-solution"> <script name="controlscript.bat"> <![CDATA[ echo controlscript called ]]> </script> <script name="controlscript.sh"> <![CDATA[ #!sh echo controlscript called ]]> </script> <server name="HQCONT-1 My Control Server"> <property name="PROC_QUERY" value="State.Name.eq=firefox"/> <config> <option default="State.Name.eq=firefox" Endpoint Operations Management Agent Plug-in Development Kit VMware, Inc. 13
Endpoint Operations Management Agent Plug-in Development Kit name= process query description= y for singleprocess"/> n type= autoinventor class="org. hyperic hq- product. Daemon Detector"/ plugin type="measurement class="org. hyperic hq. product. MeasurementPlugin"/: <option name="progr description="control program default="controlscript. bat"/> </confi <plugin type= "control class="org. hyperic hq. product. Script ControLPlugin"/> <property name="DEFAULT_PROGRAM" value="controlscript bat"/> actions include="start"/> </plugin> iostat Script Example property name="version I/0 Device <option name="script description="Collector default="pdk/scripts/device_iostat. pl"/> <option name="device rescript <filte alue="exec: file=%script%, args=device%/ <metric name="Availability plate="Template]: Availability indi <metric name="Read Requests Merged per Second ategory="THROUGHPUT e: rrom/s/>
name="process.query" description="Process Query for singleprocess"/> </config> <plugin type="autoinventory" class="org.hyperic.hq.product.DaemonDetector"/> <plugin type="measurement" class="org.hyperic.hq.product.MeasurementPlugin"/> <config> <option name="program" description="control program" default="controlscript.bat"/> </config> <plugin type="control" class="org.hyperic.hq.product.ScriptControlPlugin"/> <property name="DEFAULT_PROGRAM" value="controlscript.bat"/> <actions include="start"/> </server> </plugin> iostat Script Example <pluginname="IoDevice"> <property name="version" value="1.0"/> <service name="I/O Device"> <config> <option name="script" description="Collector script" default="pdk/scripts/device_iostat.pl"/> <option name="device" description="Device name" default="sda"/> </config> <filter name="template" value="exec:file=%script%,args=%device%"/> <metric name="Availability" template="${template}:Availability" indicator="true"/> <metric name="Read Requests Merged per Second" category="THROUGHPUT" template="${template}:rrqm/s"/> Endpoint Operations Management Agent Plug-in Development Kit VMware, Inc. 14
Endpoint Operations Management Agent Plug-in Development Kit <metric name=Write Requests Merged per Second category="THROUGHPUT" template="Sitemplate]: wrqm/s"/> <metric name="Read Requests per Second indicator= true template="Template: r/s"/> <metric name="Write Requests per Second category= " THROUGHPUT indicator= true template="Template]: W/s"/> <metric name="Sectors Read per Second category="THROUGHPUT template="Template: rsec/s"/> metric name="Sectors Writen per Second category="THROUGHPUT Template] s"/> <metric name="Average Sector Request size cegory="THROUGHPUT template="Sitemp late]: avgrq-SZ"/ <metric Average Queue Length category="PERFORMANCE template="Sitemp late]: avgqu-5z"/: ge wait category="PERFORMANCE" indicator= true template="Sitemp late]: await"/> <metric name="Average Service Time category="PERFORMANCE category="PERFORMANCE emplate="Sitemp late]: %util"/> /service> /plugin> re. Inc
<metric name="Write Requests Merged per Second" category="THROUGHPUT" template="${template}:wrqm/s"/> <metric name="Read Requests per Second" category="THROUGHPUT" indicator="true" template="${template}:r/s"/> <metric name="Write Requests per Second" category="THROUGHPUT" indicator="true" template="${template}:w/s"/> <metric name="Sectors Read per Second" category="THROUGHPUT" template="${template}:rsec/s"/> <metric name="Sectors Writen per Second" category="THROUGHPUT" template="${template}:wsec/s"/> <metric name="Average Sector Request Size" category="THROUGHPUT" template="${template}:avgrq-sz"/> <metric name="Average Queue Length" category="PERFORMANCE" template="${template}:avgqu-sz"/> <metric name="Average Wait Time" category="PERFORMANCE" indicator="true" units="ms" template="${template}:await"/> <metric name="Average Service Time" category="PERFORMANCE" units="ms" template="${template}:svctm"/> <metric name="CPU Usage" category="PERFORMANCE" units="percent" template="${template}:%util"/> </service> </plugin> Endpoint Operations Management Agent Plug-in Development Kit VMware, Inc. 15