Endpoint Operations Management Agent Plug-in Development Kit vRealize Operations Manager 6.1 This document supports the version of each product listed and supports all subsequent versions until the document is replaced by a new edition. To check for more recent editions of this document, see http://www.vmware.com/support/pubs.
Endpoint Operations Management Agent Plug-in Development Kit You can find the most up-to-date technical documentation on the VMware Web site at: http://www.vmware.com/support/ The VMware Web site also provides the latest product updates. If you have comments about this documentation, submit your feedback to: docfeedback@vmware.com Copyright © 2015 VMware, Inc. All rights reserved. Copyright and trademark information. VMware, Inc. 3401 Hillview Ave. Palo Alto, CA 94304 www.vmware.com 2 VMware, Inc.
Contents About the Endpoint Operations Management Agent Plug-in Development Kit 5 1 Introduction to Plug-in Development 7 The Role of the Server and Agent in Plug-ins 7 Technical Overview 8 Plug-in Implementations 8 Using Support Classes to Simplify a Plug-in 8 Writing Plug-ins 9 Running and Testing Plug-ins from the Command Line 25 2 Using Auto-Discovery Support Classes in Plug-ins 39 Auto-Discovery Classes 39 Auto-Discovery Interfaces 40 Specifying Auto-Discovery Implementation for a Resource Type 4
Endpoint Operations Management Agent Plug-in Development Kit 4 VMware, Inc.
About the Endpoint Operations Management Agent Plug-in Development Kit The Endpoint Operations Management Agent Plug-in Development Kit documents the XML plug-in descriptor that is the basis of every plug-in. Endpoint Operations Management supports classes for auto-discovery, measurement, control, and other management functions. It provides information about developing VMware vRealize Operations Manager product plug-ins to manage new object types.
Endpoint Operations Management Agent Plug-in Development Kit 6 VMware, Inc.
Introduction to Plug-in Development 1 Plug-ins are the interface between vRealize Operations Manager and products on the network you want to manage. You can develop your own plug-ins to extend the functionality of vRealize Operations Manager coverage to products or parts of products not yet covered. For information about the Endpoint Operations Management source code and the plug-ins provided by VMware, see https://github.com/vmware/ep-ops-management.
Endpoint Operations Management Agent Plug-in Development Kit The server manages metadata, including: n Platform, server, and service resource types and how the plug-in's targeted resources map to the inventory model. n The configuration schema for each resource. Technical Overview vRealize Operations Manager plug-ins are self-contained .jar or .xml files that are deployed on both the server and every agent that you want to run the plug-in.
Chapter 1 Introduction to Plug-in Development Writing Plug-ins While the interface with vRealize Operations Manager plug-ins is straightforward, you also must determine how to retrieve data from a managed resources and how it should appear in the inventory model, and at what level. Plug-in Naming Plug-in names must be in the following formats, where PluginName is the name of the plug-in, as specified in the root plugin element of the plug-in descriptor: n PluginName-plugin.
Endpoint Operations Management Agent Plug-in Development Kit Discovering Custom Properties Discovery of Custom Properties is supported using the OBJECT_NAME and MBeanServer.getAttribute.
Chapter 1 Introduction to Plug-in Development alias="hitCount" collectionType="trendsup" indicator="true"/> tomcat-webapp-cache-plugin.xml PAGE 12Endpoint Operations Management Agent Plug-in Development Kit
Script Plug-ins A script plug-in is a plug-in that runs one or more scripts that return process metrics. 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.
Chapter 1 Introduction to Plug-in Development 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 element in the root element of the descriptor, and specify each of the component services as a child element. Defining Management Functions in a Script Plug-in A script plug-in can perform various management functions, including auto-discovery, measurement and control.
Endpoint Operations Management Agent Plug-in Development Kit 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.
Chapter 1 Introduction to Plug-in Development iostat Script Example
Endpoint Operations Management Agent Plug-in Development Kit PAGE 20Endpoint Operations Management Agent Plug-in Development Kit <agentuser> ALL = NOPASSWD: HQ_SENDMAIL_STAT
]]> SNMP Plug-in SNMP is the standard protocol for monitoring network-attached devices, which is leveraged by several bundled plug-ins and made easy by the Plug-in Development Kit.
Chapter 1 Introduction to Plug-in Development vRealize Operations Manager uses the remote API (http://www.jcp.org/en/jsr/detail?id=160) specified by JSR-160 to manage products that support JMX 1.2/JSR-160, including the ones listed above. For JMX-enabled servers that do not support JSR-160, vRealize Operations Manager uses vendor-specific connectors.
Endpoint Operations Management Agent Plug-in Development Kit You can use the following to reference the jmx schema in a plug-in descriptor. Creating a Custom JMX Plug-in A JMX plug-in consists solely of an XML descriptor. You can include various components in the descriptor. Defining Service Types to Provide Management via Custom MBeans Each server type defines several service types such as EJBs, Connection Pools and JMS Queues.
Chapter 1 Introduction to Plug-in Development description="Path" default="/jsp-examples"/> The values of the instance attributes within the OBJECT_NAME is replaced with the value of the configuration property when used by the plug-in. For example, "Catalina:type=Cache,host=localhost,path=/jsp-examples" Defining and Gathering Metrics Metrics are defined as for other plug-ins but, in the case of custom MBean services, the OBJECT_NAME property is used to compose the metric template attribute.
Endpoint Operations Management Agent Plug-in Development Kit The plug-in must also define the control implementation class, which resides in the hq-jmx.jar file. The control actions are invoked as MBean operations by the plug-in, as follows ObjectName name = new ObjectName("Catalina:type=StringCache"); return MbeanServer.
Chapter 1 Introduction to Plug-in Development By default, auto-discovered service names are composed using the hosting-server name, configuration properties, and service type name. "myhost Sun JVM 1.5 localhost /jsp-examples WebApp String Cache" The naming can be overridden using the AUTOINVENTORY_NAME property. PAGE 26Endpoint Operations Management Agent Plug-in Development Kit dcs-tools-pdk.jar Command Syntax To run a plug-in from the command line, it is important that you understand the syntax and the functions of each of the methods. The command for running a plug-in from the command line is structured as follows: java -jar AgentVersion/bundles/AgentBundle/pdk/lib/dcs-tools-pdk-VERSION.
Chapter 1 Introduction to Plug-in Development The command is required for the following methods. n metric n control n track n lifedata The command is not supported for the following methods. n discover n generate -a MethodAction The MethodAction argument is either supported or required by the method that is called. For example, when you run the track method, you specify whether you want to track log or configuration events by including either -a log or -a config in the command line.
Endpoint Operations Management Agent Plug-in Development Kit Resource Properties Files Generally, plug-ins require the values of one or more resource properties to run. To simplify the process of testing a plug-in, you can supply the properties in a file instead of the command line. For example, to fetch metrics for a PostgreSQL table, the metric method must know the URL and database user credentials for the parent PostresSQL server, and the name of the table.
Chapter 1 Introduction to Plug-in Development The properties file contains: n n The object's resource type name and the product portion of the name of the plug-in that manages it: dumper.plugin Specifies the product portion of the plug-in name. This is equivalent to setting the plug-in name in the command line with -p. dumper.type Specifies the resource type name. This is equivalent to setting the resource type in the command line with -t .
Endpoint Operations Management Agent Plug-in Development Kit n lifecycle Method on page 30 You use the lifecycle method to load a plug-in and report any errors found in the plug-in. n discover Method on page 31 You use the discover method to return key attributes for each discovered object to the terminal window or to a properties file. n metric Method on page 31 You use the metric method to fetch the metric template and the metric value for each metric for objects that are managed by the plug-in.
Chapter 1 Introduction to Plug-in Development discover Method You use the discover method to return key attributes for each discovered object to the terminal window or to a properties file. The method can be run for one or all plug-ins. The returned attributes include the values of the resource's configuration options. If you save discovery results to a file, you can use that file to supply the required resource configuration data when you run another method that requires the resource's configuration data.
Endpoint Operations Management Agent Plug-in Development Kit Syntax for the metric Method When Using a Resource Properties File The syntax for running the metric method using a properties file to supply resource configuration data is as follows. java -jar bundles/agent-VERSION/pdk/lib/dcs-tools-pdk-VERSION.jar -m metric pluginproperties/ResourceTypeDirectory/ResourceName.
Chapter 1 Introduction to Plug-in Development Argument Description -Dmetric-collect=default Limits the results to metrics that have the defaultOn option set to true. -Dmetric-indicator=true Limits the results to metrics that have the indicator option set to true. -Dmetric-cat=CATEGORY Limits the results to metrics of a specific category. The categories that are available are AVAILABILITY , UTILIZATION, THROUGHPUT, or PERFORMANCE.
Endpoint Operations Management Agent Plug-in Development Kit Example: Results Returned by the -metric Method default Action This example is an excerpt from the results of running the default action of the metric method. Both metric templates and metric values are returned. NOTE Colons In metric templates appear as "%3A" in the results. JBoss 4.2 Availability: jboss.system:service=MainDeployer:StateString:java.naming.provider.url=jnp %3A//0.0.0.0%3A2099,java.naming.security.principal=%java.naming.security.
Chapter 1 Introduction to Plug-in Development track Method You use the track method to track log or configuration events. Syntax The syntax for the track method is as follows. ava -jar /bundles/agent-VERSION/pdk/lib/dcs-tools-pdk-VERSION.jar -p PluginName -t "ResourceType" -m track -a TrackAction -Dserver.config_track.files=TrackFiles Argument Description PluginName Identifies the plug-in to run. ResourceType Specifies a resource type managed by the plug-in.
Endpoint Operations Management Agent Plug-in Development Kit Argument Description PluginName Identifies the plug-in to document. If not specified, the action is applied to all plug-ins. GenerateAction Specifies a type of document to generate. Available options are: n metrics-wiki Writes a Confluence Wiki-formatted summary of supported metrics to a file. n metrics-xml Outputs an XML-formatted summary of supported metrics for an object type to stdout.
Chapter 1 Introduction to Plug-in Development n SMTP n FTP n LDAP n DNS n SSH n NTP n DHCP n SNMP n RPC n InetAddress Ping n TCP Socket Example: Run the netservices Plug-in metric Method for a Remote LDAP Server You use the following command to run the netservices plug-in metric method for a remote LDAP server. The value of each configuration option for the LDAP service object is supplied using a -D argument. java -jar bundles/agent-VERSION/pdk/lib/dcs-tools-pdk-shared-VERSION.
Endpoint Operations Management Agent Plug-in Development Kit 38 VMware, Inc.
Using Auto-Discovery Support Classes in Plug-ins 2 You can use the vRealize Operations Manager auto-discovery functionality in a custom plug-in. As most platform types are discovered by the system plug-in, custom plug-ins discover server and service resource types. Auto-Discovery Implementation The auto-discovery class performs the discovery process. For many resource types, you can reference one of the vRealize Operations Manager built-in auto-discovery classes.
Endpoint Operations Management Agent Plug-in Development Kit Overview The table below describes each of the classes in the auto-discovery class hierarchy. Table 2‑1. Auto-Discovery Classes Class Description When to Use ServerDetector Abstract class. ServerDetector is an abstract class and must be inherited, rather than used directly. It may be extended by a custom auto-discovery class. ServerDetector is the base autodiscovery class. PlatformServiceDetector Abstract class.
Chapter 2 Using Auto-Discovery Support Classes in Plug-ins Specifying Auto-Discovery Implementation for a Resource Type You specify the class that performs auto-discovery for a resource type in a element of type autoinventory. The following is an example of an auto-discovery Implementation for a resource type. ... ...
Endpoint Operations Management Agent Plug-in Development Kit org.hyperic.hq.product. JDBCMeasurementPlugin org.hyperic.hq.product. jmx.MxMeasurementPlugin n Sigar n ... Obtains database server and database metrics using JDBC. Measurement classes in Hyperic plug-ins that monitor database servers extend this class. Such plug-ins include: n Mysql n PostgreSQL n Oracle n Sybase Obtains MBean attribute values.
Chapter 2 Using Auto-Discovery Support Classes in Plug-ins A metrics-gathering plug-in must determine availability for every object that it monitors. A single plug-in gathers availability for multiple objects. If availability is not gathered for an object, the object is determined to be unavailable. A plug-in sets the value of availability to 100 if the object is up, and 0 if it is down. These values are displayed in the user interface as available or unavailable.
Endpoint Operations Management Agent Plug-in Development Kit Table 2‑2. metric Tag Attributes (Continued) Metric Attribute Description Required Yes/No Possible Values units The units of measurement for the metric, which affects how metric values are displayed and labelled in the vRealize Operations Manager user interface No None Is not formatted.
Chapter 2 Using Auto-Discovery Support Classes in Plug-ins Example: Complex metric Tag Using Templates to Collect Metric Data Metric templates enable plug-ins to mix and match sources for the data they collect. The measurement template uses an extended form of a JMX ObjectName, domain:properties:attribute:connection-properties. boss.
Endpoint Operations Management Agent Plug-in Development Kit The class name varies by type of plug-in. The class in the code snippet is for a JMX plug-in. For a script plug-in you use the following. Auto-discovering Services Resources You can specify the auto-discovery of a services running on the server by adding another line so that the plug-in recognizes that the server is hosting services that it must discover.
Working with Plug-in Descriptors 3 A plug-in descriptor is an XML file that defines what a plug-in does and how. It defines the object types it manages and, for each object type, specifies the management functions it performs, the resource data it requires and discovers, and the metrics it returns. Every plug-in has a descriptor file. If a plug-in uses Endpoint Operations Management plug-in support classes or a script to perform management functions, the descriptor is the component to develop and deploy.
Endpoint Operations Management Agent Plug-in Development Kit Management Functions and Classes for Object Types A plug-in can perform one or more management function for each object type that it manages. For example, the Tomcat plug-in enables autodiscovery, metric collection, log tracking, control operations for Tomcat 5.5 and 6.0 servers, and one or more management functions for Tomcat connectors and Web applications.
Chapter 3 Working with Plug-in Descriptors Supported Element Relationships Element Structures for Various Object Hierarchies
