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:

Plugin Classpath

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

• The -plugin.jar itself.
• lib/*.jar embedded within the plugin jar.
• Items specified using the <classpath> tag.

Plugin Tags

Available Tags

Top-level <plugin> Tag

<plugin> Attributes:

• name - Name of this plugin.
  Defaults to the name of the plugin jar or xml file, stripped of -plugin.xml or -plugin.jar.
• package - Override default package name.
  The default value is net.hyperic.hq.product.name. Where name is value value of the name attribute. This value is used as a prefix to the <plugin> Tag class attribute.
• class - Name of the ProductPlugin implementation.
  This is only needed if one wishes to override methods in the ProductPlugin.

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:

• type - The plugin type.
  • measurement
  • control
  • responsetime
  • autoinventory
• class - The plugin Class name

<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:

• type - The plugin type.
  • product
  • measurement
  • control
  • responsetime
• name - Valid at the top-level, to be used by the include attribute in other config tags.
• platform
  Certain config schemas have different options depending on the platform. For example, Unix platforms generally use scripts for control actions, where the same product on Win32 may use the Windows service manager.
• include - Include options from another <config> tag.

<option> Tag Attributes:

• name - Property name, used by plugins to auto-configure during auto inventory.
• description - Text description, shown in the UI and CLI.
• default - Default value used in the UI.
• type
• string - Default type, arbitrary string value.
• int - Value validated using Integer.parseInt
• double - Value validated using Integer.parseDouble
• secret - Value is not displayed in the UI or CLI.
• hidden - Option is not displayed in the UI or CLI.
• yesno - Boolean option.
• ipaddress - Value must be a valid IP address.
• enum - Drop-down list displayed in the UI.
• optional - If true, user is not required to enter a value for this option in the UI.

<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 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 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.

• name - Name of the server type.
• version - Version of the server type.
• platforms - Supported platform types.
• description - Description for UI.
• include - Include another server type.

<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>
    <include name="/**/server/*/conf/jboss-service.xml"/>
  </scan>

Example registry scan config from the 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.

• name - Name of the service type.
• description - Description for UI.
• server - Valid only for top-level service tag.
• version - Valid only for top-level service tag.

<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.