Plugin XML Descriptor

Plugins are supported in the following formats:

This document describes the XML descriptor in detail. For a complete syntax, see the Plugin XML Descriptor Syntax

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.

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"/>

Config Schema

n 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 UI in the Inventory Properties tab for each resource type instance. The Config Schema controls how the configuration is rendered in the UI as well as validation of property values.

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

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.

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

<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");
    ...

<metrics> Tag

The <metrics> tag is used for grouping metric tags, using a name which can be included elsewhere in the file.

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

<help> Tag

The <help> tag is intended for products which require changes for enabling monitoring. The help text will be displayed on the Edit Inventory Properties page for the resource type it is associated with. For example, 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 and 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>

<server> Tag

The <server> tag defines a server resource type.

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

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

<service> Tag

The <service> tag defines a server resource type.

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