Plugin XML Descriptor

Plugin XML Descriptor

This page presents a limited syntax for the plugin XML descriptor. Most of what you'll need when writing an XML descriptor is described here. For a complete syntax, see the Plugin XML Descriptor Syntax.

Plugin Formats

Plugins are supported in the following formats:

Format Description
*-plugin.jar Standard jar format, containing etc/hq-plugin.xml as the XML descriptor and any number of class files.
*-plugin.xml Standalone xml descriptor. Plugin implementation classes are either in the hq-product.jar or other *-plugin.jar plugins.

Plugin Classpath

Each plugin.jar has its own ClassLoader which includes the following in its classpath:

Plugin Tags

Available Tags

Tag Use
Top-level <plugin>  
Server and service <plugin> Invokes existing plugins at the right inventory level
<config> and <option> Specifies configuration properties to enable the plugin to monitor, measure, and control a resource
<filter> Use variables to efficiently assign values to elements in the file, often to metrics
<property>  
<metrics> and <metric> Groups and defines metrics to be collected
<help> Displays help instructions in the UI for products that require changes for enabling monitoring
<server> Defines a server resource type
<scan> Specifies file name patterns and registry keys used for server autodiscovery
<service> Defines a service resource type

Top-level <plugin> Tag

<plugin> Attributes:

back to tag

Server and Service <plugin> Tag

The <plugin> tag at the server or service level defines which classes implement each plugin type, if any. If class attribute is omitted at the service level, its value is inherited from the enclosing server type.

<plugin> Attributes:

<plugin> Example
<server name="MsSQL"
          version="2000"
          platforms="Win32">

    <plugin type="measurement"
            class="MsSQLMeasurementPlugin"/>

    <plugin type="autoinventory"
            class="MsSQLDetector"/>

    <plugin type="control"
            class="net.hyperic.hq.product.Win32ControlPlugin"/>

back to tag

Configuration Schema

In order to implement measurement, control and the like, most resource types require configuration properties. For example, connecting to a JBoss server requires a JNP url. Getting metrics for a JBoss service, such as an EJB, requires the name of the J2EE Application and EJB name. The properties are displayed in the "Resource Configuration" screen for each resource. The configuration schema determines what properties are displayed in the UI and what default values they have, and it validates property values.

Many configuration property values are populated automatically by HQ through auto-discovery. Configuration properties such as password, for example, must be provided by a user.

<config> Tag Attributes:


<option> Tag Attributes:

<option> Example
<option name="jdbcDriver" type="enum"
        description="JDBC Driver Class Name"
        default="org.postgresql.Driver">
   <include name="org.postgresql.Driver"/>
   <include name="oracle.jdbc.driver.OracleDriver"/>
   <include name="com.microsoft.jdbc.sqlserver.SQLServerDriver"/>
</option>

back to tag

<filter> Tag

The <filter> tag is used to define variables which are replaced with the xml file.
Example:

<filter name="imap4" value="MSExchangeIMAP4"/>

<metric name="Login Total"
        template="win32:Object=${imap4},Instance=Global:${name}"
        ...

Is filtered to result in:

<metric name="LOGIN Total"
        template="win32:Object=MSExchangeIMAP4,Instance=Global:LOGIN Total"
        ...

Note that metric attributes are also treated as filters, in this case the name attribute is expanded to LOGIN Total.

back to tag

<property> Tag

The <property> tag acts like a <filter>, but is also saved for use within the plugin code itself. For example, the property named template-config is used by the MeasurementPlugin to append connection properties to the template attribute of every <metric>:

<property name="template-config"
            value="java.naming.provider.url=%java.naming.provider.url%"/>

The <property> tag can be attached to a specific resource type by using it within a <server> or <service> tag. For example:

<service name="Entity Container">

    <property name="OBJECT_NAME"
              value="jboss.j2ee:jndiName=%jndiName%,service=EJB"/>

    <plugin type="control"
            class="net.hyperic.hq.product.jboss.JBossServiceControlPlugin"/>

    <metric name="Cache Size"
            template="${OBJECT_NAME}:CacheSize"
            indicator="true"/>

The value is retrieved within JBossServiceControlPlugin:

protected String getObjectName() {
    String objectName = getTypeProperty("OBJECT_NAME");
    ...

back to tag

<metrics> and <metric> Tags

The <metrics> tag is used for grouping metric tags, allowing you to define metrics in one place and include them elsewhere in the file. This grouping carries over to the UI. In this example, notice how a group of metrics called "mssql-database" is defined initially and then later that same group is include ed.

<metrics> Example
<metrics name="mssql-database">
    <metric name="Active Transactions"
            template="${db.domain}:Platform=Win32:Active Transactions"
            category="THROUGHPUT"
            indicator="true"/>
     ...
  </metrics>

  <server name="MsSQL"
          version="2000"
          platforms="Win32">
    ...
    <metrics>
      <include name="mssql-database"/>
      ...
    </metrics>
    <service name="Database">
      <metrics>
        <include name="mssql-database"/>
        ...
      </metrics>
  </server>

back to tag

<help> Tag

The <help> tag is intended for products ("resource types," in HQ parlance) that require changes for enabling monitoring. The help text is displayed on the "Resource Configuration" screen to notify users of actions they must take before monitoring a particular resource type.

For example, the help text could tell users that Apache requires installation of the SNMP module, iPlanet/SunONE requires configuration changes to enable SNMP monitoring, Tomcat requires a webapp to be installed and configured, or certain databases require a user login to have permissions to query monitoring data.

<help> Example
<help name="MetaFrame XP">
  <![CDATA[
    <h3>Configure MetaFrame ${product.version} for Monitoring</h3>
    <br>
    Monitoring of Citrix MetaFrame XP requires the installation of
    the Citrix Server SDK version 2.3.  These libraries can be
    downloaded from the <a href="http://apps.citrix.com/CDN/">
    The Citrix Developer Network</a>
  ]]>
  </help>

back to tag

<server> Tag

The <server> tag defines a server resource type. Both this and the <service> tag help align the plugin with the HQ Inventory Model.

<server> Example
<server name="MsSQL"
          version="2000"
          description="Microsoft SQL Server"
          platforms="Win32">
    ...
  </server>

The name and version attributes are used to compose the server resource type name, seen in the UI and used by autodiscovery. In the example above, the resource type name will be "MsSQL 2000". The platforms attribute can be used to limit which platforms support the given server type.

back to tag

<scan> Tag

The <scan> tag is a container for specifying file name patterns and registry keys used for server autodiscovery. Example file scan config from the JBoss plugin:

<scan> Example from JBoss plugin
<scan>
    <include name="/**/server/*/conf/jboss-service.xml"/>
  </scan>

Example registry scan config from the MySQL plugin:

<scan> Example from MySQL plugin
<scan registry="SOFTWARE\MySQL AB\MySQL Server 4.1">
    <include name="Location"/>
  </scan>

back to tag

<service> Tag

The <service> tag defines a server resource type. Both this and the <server> tag help align the plugin with the HQ Inventory Model.

<service> Example
<server name="MsSQL"
          version="2000"
          description="Microsoft SQL Server"
          platforms="Win32">
    ...
    <service name="Database">
  </server>

The name attribute is used to compose the service resource type name, seen in the UI and used by autodiscovery. This value is appended to the enclosing server type name. In the example above, the resource type name will be MsSQL 2000 Database.


Browse Space

- Pages
- News
- Labels
- Attachments
- Bookmarks
- Mail
- Advanced
- Activity

Explore Confluence

- Popular Labels
- Notation Guide

Your Account

Log In

or Sign Up  

Other Features

Add Content


System Monitoring Software
SourceForge.net Logo