vFabric Hyperic Product Plug-in Development v.5.7 June 2013 EN-000963-01 Legal Notice Copyright © 2013 VMware, Inc. All rights reserved. This product is protected by U.S. and international copyright and intellectual property laws. VMware products are covered by one or more patents listed at http://www.vmware.com/go/patents. VMware is a registered trademark or trademark of VMware, Inc. in the United States and/or other jurisdictions. All other marks and names mentioned herein may be trademarks of their respective companies. VMware, Inc. 3401 Hillview Ave. Palo Alto, CA 94304 www.vmware.com 2 Contents About vFabric Hyperic Product Plug-in Development ..................................................... 4 Introduction to Plugin Management Functions ....................................................................... 5 Introduction to Plugin Development ..................................................................................... 23 Writing Plugins .................................................................................................................... 26 Running and Testing Plugins from Command Line .............................................................. 75 Plugin Descriptors ............................................................................................................... 94 Plugin Support Classes ..................................................................................................... 200 Plugin Tutorials ................................................................................................................. 243 3 About vFabric Hyperic Product Plug-in Development vFabric Hyperic Product Plug-in Development documents the XML plug-in descriptor that is the basis of every plug-in, Hyperic support classes for auto-discovery, measurement, control, and other management functions. It provides information about developing VMware® vFabric™ Hyperic® product plug-ins to manage new resource types. Intended Audience This guide is intended for developers who build or customize Hyperic plug-ins. 4 Introduction to Plugin Management Functions Using Auto-Discovery Support Classes in Plugins This is a developer's introduction to using Hyperic's built-in auto-discovery functionality in a custom plugin. As most platform types are discovered by Hyperic's system plugin, custom plugins discover server and service types. Auto-discovery rules for a resource type are defined in the XML descriptor of the plugin that manages the type. For each resource type managed by the plugin, you specify: Auto-discovery implementation — The auto-discovery class that performs the discovery process. For many resource types, you can reference one of Hyperic's built-in auto-discovery classes. If necessary, you can write a custom auto-discovery class that extends a Hyperic auto- discovery class. Most of Hyperic's auto-discovery implementations discover two levels of resources — servers, and the services that run in them, so typically, in which case you only specify a single implementation in the descriptor. Parameters required by the implementation — In addition to specifying the auto-discovery class, the plugin descriptor must define the parameters that the class requires. Auto-Discovery Class Hierarchy Hyperic's auto-discovery class hierarchy is shown below: org.hyperic.hq.product.GenericPlugin org.hyperic.hq.product.ServerDetector org.hyperic.hq.product.PlatformServiceDetector org.hyperic.hq.product.DaemonDetector org.hyperic.hq.product.MxServerDetector org.hyperic.hq.product.SunMxServerDetector org.hyperic.hq.productSNMPDetector Overview of Auto-Discovery Classes The table below describes each of the classes in the auto-discovery class hierarchy. Class Description When to Use ServerDetector Abstract class. ServerDetector and must be inherited, rather than used ServerDetector is the base directly. It may be extended by a auto-discovery class. custom auto-discovery class. PlatformServiceDetector Abstract class. Intended for use by platform types with service types, but no server types. 5 Class Description When to Use DaemonDetector Discovers server types via a Sigar query of system process table. MxServerDetector Discovers JMX server types viq a Sigar query of system process table. Discovers JMX services by MBean query. SunMxServerDetector Detector for Sun 1.5+ JVMs with remote JMX enabled. Note, JVM resource must be explicitly configured. SNMPDetector Discovers SNMP server types viq a Sigar query of system process table. Discovers SNMP services view SNMP request. Auto-Discovery Interfaces Hyperic's built-in auto-discovery classes each implement one or more of the following interfaces: org.hyperic.hq.product.AutoServerDetector — This interface is used by the default scan, which discovers servers by scanning the process table or Windows registry. org.hyperic.hq.product.FileServerDetector — This interface is used by the file system scan. Plugins specify file patterns to match in etc/hq-server-sigs.properties When a file or directory matches one of these patterns, this method will be invoked. It is up to the plugin to use the matched file or directory as a hint to find server installations. org.hyperic.hq.product.RuntimeDiscoverer — This interface is used by the run-time scan. This differs from the default and filesystem scan, which do not necessarily require a server to be running to detect it. Classes that implement the RuntimeDiscoverer interface communicate directly with a running target server to discover resources. How to Specify Auto-Discovery Implementation for a Resource Type You specify the class that performs auto-discovery for a resource type in a <plugin> element of type "autoinventory." For example, the following <server name="Java Server Name" version ="version #"> ... <plugin type="autoinventory" class="org.hyperic.hq.product.jmx.MxServerDetector"/> ... </server> 6 How to Supply Parameters for Auto-Discovery Implementation All auto-discovery implementations discover server types by scanning the process table or Windows registry for processes that match a Sigar process query. You specify the process query in an option element named "process.query" (inside a <config> element) in the <server> element for a server type. Data that you define in an option element appear on the Configuration Properties page for a resource, and can be edited, as necessary. Data defined in a property element cannot be edited for a resource in the Hyperic user interface. The parameters required to discover services vary by plugin implementation. Discovery of JMX services requires ObjectNames, discovery of SNMP services requires an OID. Dynamic Service Type Detection Introduction to Dynamic Service Type Detection Most service types are defined in the XML descriptor for the plugin that manages the host server. This works well for services whose name, configuration options, related plugin implementations, and metrics structures are known in advance and can be specified when you develop the plugin. Dynamic service type detection is a method of auto-discovery that can detect supports runtime creation of new resource types. ServerDetector, Hyperic's base autodiscovery class, contains the discoverServiceTypes(ConfigResponse):Set function, which is called during runtime discovery operation. This method is called prior to discoverServices(ConfigResponse):List which usually handles runtime service discovery. A custom discovery class that extends a Hyperic auto-discovery support class discovers service types before the service instances. The service structure is then reported to the Hyperic server. Structures on server are updated from multiple sources, hence the services of the same type must have the same configuration schema. Dynamic service type creation does support the run-time definition of resource configuration option (the resource data defined as <option> elements for a resource type, and presented and updated on the Configuration Properties page for a resource instance). The template attribute for a metric for a service that will be created at runtime must be specified explicitly rather than by reference to a configuration <option>. The instructions assume a plugin whose resource structure is defined in the XML descriptor like this: 7 <plugin name="myplugin"> ... <server name="MyServer"> ... </plugin> Note: No service types are defined for the server type. Because we are about to define these services dynamically, we expect similar result as if these services would be hard coded into the plugin descriptor: <plugin name="myplugin"> ... <server name="MyServer"> ... <!-- --> <service name="Service A"> ... </service> <service name="Service B"> ... </service> <service name="Service C"> ... </service> </plugin> Implement discoverServiceTypes method This method has to return a Set containing ServiceType objects. The method skeleton would look something like this: @Override protected Set<ServiceType> discoverServiceTypes(ConfigResponse serverConfig) throws PluginException { Set<ServiceType> serviceTypes = new HashSet<ServiceType>(); // Do your magic... return serviceTypes; } The function should perform all operations required to to discover and build your service types structures. You might choose to create a separate factory class to perform these operations --- regardless of your implementation, you must pass the appropriate data to the factory methods, unless you decide to hard code the service type names. At a minimum, you must define the managed product name, which corresponds to the plugin name, and the server type