TIBCO Hawk® JMX Plug-in User’s Guide
Software Release 5.2.0 November 2016
Two-Second Advantage® Important Information SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE. USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE) OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE “LICENSE” FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE BOUND BY THE SAME. This document contains confidential information that is subject to U.S. and international copyright laws and treaties. No part of this document may be reproduced in any form without the written authorization of TIBCO Software Inc. TIBCO, Two-Second Advantage, TIBCO Hawk, TIBCO Rendezvous, TIBCO Runtime Agent, TIBCO ActiveMatrix BusinessWorks, TIBCO Administrator, TIBCO Designer, TIBCO ActiveEnterprise and TIBCO Repository are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries. Enterprise Java Beans (EJB), Java Platform Enterprise Edition (Java EE), Java 2 Platform Enterprise Edition (J2EE), and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle Corporation in the U.S. and other countries. All other product and company names and marks mentioned in this document are the property of their respective owners and are mentioned for identification purposes only. THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALL OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAME TIME. SEE THE README FILE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON A SPECIFIC OPERATING SYSTEM PLATFORM. THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME. THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES. Copyright © 2004 - 2016 TIBCO Software Inc. All rights reserved. TIBCO Software Inc. Confidential Information | iii Preface
TIBCO Hawk® JMX Plug-in extends the managing and monitoring capabilities of TIBCO Hawk into applications instrumented using Java™ Management Extensions (JMX) standard interfaces. Via the TIBCO Hawk JMX Plug-in, the TIBCO Hawk agent can connect to JMX Agents, introspect them, and expose the JMX MBeans to the TIBCO Hawk infrastructure as microagents. From there, they can be utilized with TIBCO Hawk rulebases or accessed by any number of TIBCO Hawk console applications.
Topics
• Related Documentation, page iv • Typographical Conventions, page v • Connecting with TIBCO Resources, page vii
TIBCO Hawk JMX Plug-in User’s Guide iv | Related Documentation
Related Documentation
This section lists documentation resources you may find useful.
TIBCO Hawk JMX Plug-in Documentation
Documentation for TIBCO products is not bundled with the software. Instead, it is available on the TIBCO Documentation site. To directly access documentation for this product, double-click the following file: TIBCO_HOME/release_notes/TIB_hawkjmx_version_docinfo.html The following documents form the TIBCO Hawk JMX Plug-in documentation set: • TIBCO Hawk JMX Plug-in Installation Guide: Read this manual for instructions on site preparation and installation. • TIBCO Hawk JMX Plug-in User’s Guide: Read this manual to gain an understanding of installing and using TIBCO Hawk JMX Plug-in. • TIBCO Hawk JMX Plug-in Release Notes: Read this manual for information on the current release of TIBCO Hawk JMX Plug-in.
Other TIBCO Product Documentation You may find it useful to read the documentation for the following TIBCO products: • TIBCO Hawk® Installation and Configuration Guide: This manual contains step-by-step instructions for installing TIBCO Hawk software on various operating system platforms. • TIBCO Hawk® Admistrator’s Guide: This manual includes basic descriptions of TIBCO Hawk concepts, instructions for using TIBCO Hawk Display, monitoring strategies with examples, a comprehensive FAQ, and a glossary. • TIBCO Rendezvous™ documentation: This is TIBCO’s real-time transport layer that is used by Product software. • TIBCO Enterprise Message Service ™ documentation: TIBCO Enterprise Message Service software allows you to send messages from your applications in a format that conforms to the Java Messaging Service (JMS) protocol.
TIBCO Hawk JMX Plug-in User’s Guide Preface | v
Typographical Conventions
The following typographical conventions are used in this manual.
Table 1 General Typographical Conventions Convention Use
ENV_NAME TIBCO products are installed into an installation environment. A product installed into an installation environment does not access components in other TIBCO_HOME installation environments. Incompatible products and multiple instances of the same product must be installed into different installation environments. An installation environment consists of the following properties: • Name Identifies the installation environment. This name is referenced in documentation as ENV_NAME. On Microsoft Windows, the name is appended to the name of Windows services created by the installer and is a component of the path to the product shortcut in the Windows Start > All Programs menu. • Path The folder into which the product is installed. This folder is referenced in documentation as TIBCO_HOME. TIBCO Hawk JMX Plug-in installs into a directory within a TIBCO_HOME.
code font Code font identifies commands, code examples, filenames, pathnames, and output displayed in a command window. For example:
Use MyCommand to start the foo process.
bold code Bold code font is used in the following ways: font • In procedures, to indicate what a user types. For example: Type admin. • In large code samples, to indicate the parts of the sample that are of particular interest. • In command syntax, to indicate the default parameter for a command. For example, if no parameter is specified, MyCommand is enabled: MyCommand [enable | disable]
TIBCO Hawk JMX Plug-in User’s Guide vi | Typographical Conventions
Table 1 General Typographical Conventions (Cont’d) Convention Use
italic font Italic font is used in the following ways: • To indicate a document title. For example: See TIBCO ActiveMatrix BusinessWorks Concepts. • To introduce new terms For example: A portal page may contain several portlets. Portlets are mini-applications that run in a portal. • To indicate a variable in a command or code syntax that you must replace. For example: MyCommand PathName
Key Key name separated by a plus sign indicate keys pressed simultaneously. For combinations example: Ctrl+C. Key names separated by a comma and space indicate keys pressed one after the other. For example: Esc, Ctrl+Q.
The note icon indicates information that is of special interest or importance, for example, an additional action required only in certain circumstances.
The tip icon indicates an idea that could be useful, for example, a way to apply the information provided in the current section to achieve a specific result.
The warning icon indicates the potential for a damaging situation, for example, data loss or corruption if certain steps are taken or not taken.
TIBCO Hawk JMX Plug-in User’s Guide Preface | vii
Connecting with TIBCO Resources
How to Join TIBCOmmunity TIBCOmmunity is an online destination for TIBCO customers, partners, and resident experts. It is a place to share and access the collective experience of the TIBCO community. TIBCOmmunity offers forums, blogs, and access to a variety of resources. To register, go to http://www.tibcommunity.com.
How to Access TIBCO Documentation Documentation for this and other TIBCO products is available on the TIBCO Documentation site: https://docs.tibco.com Documentation on the TIBCO Documentation site is updated more frequently than any documentation that might be included with the product. To ensure that you are accessing the latest available help topics, visit the Documentation site.
How to Contact TIBCO Support For comments or problems with this manual or the software it addresses, contact TIBCO Support as follows: • For an overview of TIBCO Support, and information about getting started with TIBCO Support, visit this site: http://www.tibco.com/services/support • If you already have a valid maintenance or support contract, visit this site: https://support.tibco.com Entry to this site requires a user name and password. If you do not have a user name, you can request one.
TIBCO Hawk JMX Plug-in User’s Guide viii | Connecting with TIBCO Resources
TIBCO Hawk JMX Plug-in User’s Guide | 1 Contents
Preface ...... iii Related Documentation ...... iv TIBCO Hawk JMX Plug-in Documentation ...... iv Other TIBCO Product Documentation ...... iv Typographical Conventions ...... v Connecting with TIBCO Resources ...... vii How to Join TIBCOmmunity ...... vii How to Access TIBCO Documentation...... vii How to Contact TIBCO Support ...... vii
Chapter 1 Introduction...... 1 JMX Overview ...... 2 About JMX architecture ...... 2 TIBCO Hawk JMX Plug-in ...... 5 Supported Application Servers...... 6
Chapter 2 Using TIBCO Hawk JMX Plug-in ...... 7 Overview ...... 8 Mapping MBeans to Microagents ...... 10 Using Notifications ...... 13 Available Microagent Methods ...... 14 JmxPluginMicroAgent:getMBeanCount ...... 15 JmxPluginMicroAgent:onNotification ...... 16 JmxPluginMicroAgent:onMBeanServerNotification ...... 17 JmxPluginMicroAgent:onConnectionNotification ...... 18 JmxPluginMicroAgent:getLoadedMBeans ...... 19 JmxPluginMicroAgent:getReleaseVersion ...... 20 onMBeanNotification ...... 21
Chapter 3 Using The Sample Application ...... 23 Overview ...... 24 Registering an MBean ...... 25 Unregistering an MBean ...... 27 Building a Rulebase...... 28
TIBCO Hawk JMX Plug-in User’s Guide 2 | Contents
Viewing the Results ...... 31
Appendix A Sample Configuration Files ...... 35 JMXServiceMA.hma ...... 36 JMXPluginConfig.xml ...... 37
Appendix B Error Messages ...... 41 TIBCO Hawk JMX Plug-in Error Messages ...... 42
TIBCO Hawk JMX Plug-in User’s Guide | 1
Chapter 1 Introduction
TIBCO Hawk JMX Plug-in extends the functionality of TIBCO Hawk by exposing JMX MBeans to the TIBCO Hawk infrastructure as microagents. This chapter provides a brief overview of JMX and TIBCO Hawk JMX Plug-in software.
Topics
• JMX Overview, page 2 • TIBCO Hawk JMX Plug-in, page 5
TIBCO Hawk JMX Plug-in User’s Guide 2 | Chapter 1 Introduction
JMX Overview
As software applications grow, managing them becomes a complex task. So far, Java applications had to write their own applications to monitor and manage their applications. JMX (Java Management eXtenstions) is a developing standard that allows Java application developers to integrate their applications with existing management solutions. JMX defines an architecture and API for writing JMX objects, also called MBeans, which live inside a container that is defined by the standard. The JMX standard additionally defines a standard method for dynamically augmenting Java objects with management attributes and operations allowing to become dynamically manageable. Functionally, JMX provides similar instrumentation capabilities to TIBCO Hawk's Application Management Interface (AMI) and TIBCO Hawk Console API. In addition to providing interfaces for application developers, JMX has also been adopted by many of the application server and web server vendors to provide visibility and control into the processes.
About JMX architecture JMX is designed around a three-level architecture. This design promotes an optimized development framework by enabling different segments of the developer community to focus on the level that best fits their strengths. The three levels of JMX are defined as: • Instrumentation Resources, such as applications, devices, or services, are instrumented using MBeans. MBeans expose their management interfaces, composed of attributes and operations, through a JMX agent for remote management and monitoring. •Agent The main component of a JMX agent is the MBean server. This is a core managed object server in which MBeans are registered. A JMX agent also includes a set of services for handling MBeans. JMX agents directly control resources and make them available to remote management applications. All interactions with an MBean must be performed through interfaces on the MBean server. • Distributed services (Remote Management) Protocol adaptors and standard connectors make a JMX agent accessible from remote management applications outside the JMX agent’s Java Virtual Machine (JVM).
TIBCO Hawk JMX Plug-in User’s Guide JMX Overview | 3
MBeans An MBean is a Java class that meets certain naming and inheritance standards of the JMX specification. The Java class of an MBean exposes the resource to be managed directly through its attributes, operations, and notifications. The management interface of an MBean consists of: • Named and typed attributes that can be either read, write, or both. • Named and typed operations that can be invoked • Notifications that can be emitted by the MBean MBeans resides with the MBean server, which is a special MBean that manages a group of MBeans.
JMX Agent A JMX agent is a Java process that provides a set of services for managing a set of MBeans. It is the container for an MBean server. JMX agents provide services for creating MBean relationships, loading classes (M-Let service), simple monitoring services and timers.
JMX Remote API and JMX Connectors The JMX Remote API allows remote access to a JMX API MBean server by means of a JMX connector. The protocol used for the standard connector defined by the JMX Remote API is based on Remote Method Invocation (RMI). The JMX Remote API allows remote access to a JMX API MBean server by means of a JMX connector. The JMX Remote API specification describes how you can advertise and find JMX API agents using existing discovery and lookup infrastructures. The JMX specification defines a connector as an object that makes a Java Management Extensions (JMX) API MBean server accessible to remote Java clients. The client end of a connector exports essentially the same interface as the MBean server. A connector consists of a connector client and a connector server. A connector server is attached to an MBean server and listens for connection requests from clients. A connector client is responsible for establishing a connection with the connector server. A connector client will usually be in a different Java Virtual Machine (JVM) from the connector server, and will often be running on a different machine. A connector server can establish many concurrent connections with different clients. A connector client is connected to only one connector server. A client application can contain many connector clients connected to different connector servers. There can be more than one connection between a given client application and a given server.
TIBCO Hawk JMX Plug-in User’s Guide 4 | Chapter 1 Introduction
Generic Connector An optional part of the JMX Remote API is a generic connector. The JMX Messaging Protocol (JMXMP) connector is a configuration of the generic connector where the transport protocol is based on TCP.
RMI Connector This standard RMI protocol must be supported by every implementation that conforms to the JMX Remote API standard. The RMI connector provides a simple mechanism for securing and authenticating the connection between a client and a server. This mechanism provides a basic level of security for environments using the RMI connector. Note that the generic JMXMP connector provides a more advanced level of security.
TIBCO Hawk JMX Plug-in User’s Guide TIBCO Hawk JMX Plug-in | 5
TIBCO Hawk JMX Plug-in
TIBCO Hawk software is a tool for monitoring distributed systems and applications. In a TIBCO Hawk environment, agents on each local computer perform the monitoring work. TIBCO Hawk agents use microagents to represent and interact with managed objects, such as an application or operating system component. The TIBCO Hawk JMX Plug-in (plug-in), which is deployed as a Microagent Plug-in in a TIBCO Hawk Agent, is a RMI client which is responsible for establishing connection with the connector server component of the MBean server. The MBeans belonging to the accessed MBean server are exposed to the TIBCO Hawk environment as microagents. TIBCO Hawk Agents use microagents to represent and interact with managed object, which in the case of the plug-in are MBeans. The plug-in maps the MBean’s interfaces to the corresponding microagent’s methods. Microagent methods can be accessed and invoked from TIBCO Hawk WebConsole or Console API applications. They are also used with the agent's rules engine to provide autonomous monitoring. The following diagram shows the interaction between TIBCO Hawk, the JMX container, and other TIBCO applications.
The TIBCO Hawk WebConsole application is a web application that provides a central view of all the distributed components interacting within TIBCO Hawk System. It is a pictorial view of each of the infrastructure component that is being monitored with the help of Hawk components.. Each MBean is represented by a TIBCO Hawk microagent on the local TIBCO Hawk agent.
TIBCO Hawk JMX Plug-in User’s Guide 6 | Chapter 1 Introduction
Supported Application Servers TIBCO Hawk JMX Plug-in supports the following application servers: • Oracle WebLogic Application Server • JBoss Application Server Uses RMI over jnp to connect to an MBean server. •Tomcat •IBM WebSphere •JVM For a list of supported versions, refer to the Readme.
TIBCO Hawk JMX Plug-in User’s Guide | 7
Chapter 2 Using TIBCO Hawk JMX Plug-in
This chapter describes how to use the plug-in software. Additionally, methods exposed by the microagent which represent the plug-in are described. These methods can be used to monitor the plug-in.
Topics
• Overview, page 8 • Mapping MBeans to Microagents, page 10 • Using Notifications, page 13 • Available Microagent Methods, page 14
TIBCO Hawk JMX Plug-in User’s Guide 8 | Chapter 2 Using TIBCO Hawk JMX Plug-in
Overview
The TIBCO Hawk JMX Plug-in uses the information contained in the JMXPluginConfig.xml configuration file to connect to the MBeanServer(s). If the plug-in is not able to connect to the MBean server, it indefinitely attempts to make the connection. On successfully connecting to the MBean server, the plug-in uses the filters set in the configuration file to access MBeans belonging to the container. Each MBean that is accessed is exposed as a TIBCO Hawk microagent along with the MBean’s interfaces. See Mapping MBeans to Microagents, page 10 for more details. The following diagram show in details the interaction between TIBCO Hawk and the JMX environment.
Whenever a new MBean is loaded in the MBean server and meets the filter criteria, the corresponding TIBCO Hawk microagent and methods are created dynamically. Similarly, all TIBCO Hawk microagent and methods created for a MBean are removed when that MBean is unloaded. If the plug-in looses connection to the MBean server, all TIBCO Hawk microagent and methods created for MBeans belonging to the MBean server are removed and are re-created when the connection is re-established. The plug-in continues to keep track of the MBean server after loosing connection to the MBean server.
TIBCO Hawk JMX Plug-in User’s Guide Overview | 9
The plug-in can be configured to access several instances of each supported application server by specifying multiple instances of the
TIBCO Hawk JMX Plug-in User’s Guide 10 | Chapter 2 Using TIBCO Hawk JMX Plug-in
Mapping MBeans to Microagents
The TIBCO Hawk JMX Plug-in uses information contained in the configuration file to connect to the MBeanServer(s). Using the filters set in the configuration file, MBeans within the container are accessed and each MBean is converted into a microagent. The microagent is given the same name as the MBean.
MBean Attributes MBean attributes can be of two types: • read-only attributes For each read-only attribute, the plug-in creates a corresponding synchronous get method. • read-write attributes For each read-write attribute, the plug-in creates two corresponding methods, a get method and a set method. The names of the methods follow the convention:
_
where
For example, for a read-write attribute acceptCount, the two methods created are:
• _getacceptCount
• _setacceptCount
MBean Operations Each MBean operation is mapped into a synchronous method which has the same name as that of the operation. Unlike microagent methods which are derived from MBean attributes, microagent methods corresponding to MBean operations do not have a _ (underscore) prefix.
Working with CompositeType and TabularType
When an MBean operation that accepts CompositeType as an input parameter, the individual elements of the input parameter are mapped to the input parameter list of the associated microagent method.
TIBCO Hawk JMX Plug-in User’s Guide Mapping MBeans to Microagents | 11
Similarly, the TabularType data returned by an MBean operation are mapped to Hawk TabularData of the microagent method. The individual elements of the TabularType are mapped to the Hawk CompositeData.
However, parameter lists with multiple CompositeType or TabularType types are not supported. For example, MBean operations with the following signatures are not supported:
• public void addFoo (CompositeType arg1, String arg2); Multiple input parameters, ones of which is of type CompositeType.
• public void addFoo(CompositeType arg1, CompositeType arg2);
Multiple parameters of type CompositeType
• public void addFoo(TabularType arg1)
MBean operations that accept data of type TabularType are not supported.
When an MBean operation accepts CompositeType, the order of the elements may not match the order of elements in the associated Hawk microagent method. For example, if an input argument, newBook, is defined as CompositeType newBook(bookType, itemNames, itemValues)
where itemNames = {"Author", "Publisher", "Genre"} When the corresponding microagent method is viewed using Hawk WebConsole, the order of the elements may be Author, Genre, Publisher.
The same hold true for TabularType. If an MBean operation returns TabularType, the sequence of the elements of the return data will not match the sequence of the elements of the Hawk microagent method that corresponds to the MBean operation.
The JmxPluginMicroAgent Microagent In addition to creating microagents for each of the accessed MBeans, the plug-in creates another microagent, the JmxPluginMicroAgent. JmxPluginMicroAgent is the JMX service plug-in microagent which acts as a wrapper for all the microagents created by the plug-in. This microagent helps keep track of the MBean servers monitored by TIBCO Hawk. The microagent methods provided by the plug-in can be used to monitor the MBean servers. For details about the methods, see Available Microagent Methods on page 14.
TIBCO Hawk JMX Plug-in User’s Guide 12 | Chapter 2 Using TIBCO Hawk JMX Plug-in
MBeanServerDelegate
MBeanServerDelegate is a special MBean created by the MBean server and represents the MBean server from the management point of view. The Plug-in registers itself as a listener with the MBeanServerDelegate. The MBeanServerDelegate MBean emits MBeanServerNotifications each time an MBean is registered or unregistered. In addition to providing notification information, this MBean provides information pertaining to the implementation of the MBean server. The microagent corresponding to this MBean is not created by default.
TIBCO Hawk JMX Plug-in User’s Guide Using Notifications | 13
Using Notifications
MBeans communicate with registered listeners using notifications. These notifications communicate changes in the state of the MBeans or the occurrence of certain events. In addition to these notifications, the plug-in sends notifications each time an MBean is added to or removed from the MBean server that is being monitored and if there is a change in the status of the connection to the MBean server. The TIBCO Hawk microagent for any MBean that is capable of broadcasting notifications (by implementing the javax.management.NotificationBroadcaster interface) has an additional TIBCO Hawk microagent method, onMBeanNotification. See onMBeanNotification, page 21 for details of this microagent method. All notifications sent by the MBean are mapped to this asynchronous method. The notifications sent when a MBean is added or removed are sent for all MBeans within the container regardless of the filters used. These notifications are useful in monitoring applications for which no microagent is created. For example, you could have an application A which depends on application B, but application B does not have a corresponding TIBCO Hawk microagent. In case application B goes down, the notification sent communicating this condition could be used to by a rulebase to set an alert condition.
TIBCO Hawk JMX Plug-in User’s Guide 14 | Chapter 2 Using TIBCO Hawk JMX Plug-in
Available Microagent Methods
This section describes the methods exposed by the JMXPluginMicroagent. These methods can be used as any other TIBCO Hawk method. They can be invoked directly from TIBCO WebConsole or used within a rulebase. The following methods are available for monitoring and managing the plug-in.
Method Description JmxPluginMicroAgent:getMBean Returns a table listing the MBean Server and it's Count MBean Count
JmxPluginMicroAgent:onNotifica Sends an asynchronous message when a new tion MBean is registered or unregistered. This method has been deprecated.
JmxPluginMicroAgent:onMBeanS Sends an asynchronous message when a new erverNotification MBean is registered or unregistered.
JmxPluginMicroAgent:onConnect Sends an asynchronous message when there is a ionNotification change in the status of the connection to the MBeanServer(s).
JmxPluginMicroAgent:getLoaded Returns a table listing all loaded MBeans from the MBeans MBean Server.
JmxPluginMicroAgent:getRelease Returns version information about the current Version plug-in release.
TIBCO Hawk JMX Plug-in User’s Guide JmxPluginMicroAgent:getMBeanCount | 15
JmxPluginMicroAgent:getMBeanCount Method
Returns a table listing the MBean Server and its MBean count.
Type Synchronous, IMPACT_INFO
Arguments Parameter Type Description MBeanServerName String The user specified MBean server name. If the MBeanServerName is not specified, information for all loaded MBeans is returned.
Returns Parameter Type Description MBeanServer String The JNDIUrl for the MBean server. Connection URL
MBeanServerName String The user specified MBean server name. This name is specified in the configuration file.
MBeanCount Integer The number of MBeans loaded from the specified MBean server.
TIBCO Hawk JMX Plug-in User’s Guide 16 | Chapter 2 Using TIBCO Hawk JMX Plug-in
JmxPluginMicroAgent:onNotification Method
Sends an asynchronous message when a new MBean is registered or unregistered.
This method has been deprecated.
Type Asynchronous, IMPACT_INFO
Arguments None.
Returns Parameter Type Description MBeanServer String The MBean server name
Name String The name of the MBean
Type String The type of notification
Message String The MBean message
SeqNum Long The sequence number
Source String The source
TimeStamp String The time stamp
TIBCO Hawk JMX Plug-in User’s Guide JmxPluginMicroAgent:onMBeanServerNotification | 17
JmxPluginMicroAgent:onMBeanServerNotification Method
Sends an asynchronous message when a new MBean is registered or unregistered.
Type Asynchronous, IMPACT_INFO
Arguments Parameter Type Description MBeanServerAliases String The list of MBean servers separated by ";", from which you want to receive messages when a new MBean is either registered or unregistered. If the MBeanServerAlias is not specified, messages are sent for all MBeans registered and unregistered with all accessed MBean servers.
ObjectNameFilter String The list of ObjectName/ObjectName prefixes separated by ";". If the ObjectNameFilter is not specified, send all notifications.
Returns Parameter Type Description MBeanServerAlias String The MBean Server Name
MBeanName String The name of the MBean
TimeStamp String The time stamp of the notification.
Type String The type of notification
UserData String The user data
SeqNum Long The sequence of the notification
Message String The message
Source String The source of the notification.
TIBCO Hawk JMX Plug-in User’s Guide 18 | Chapter 2 Using TIBCO Hawk JMX Plug-in
JmxPluginMicroAgent:onConnectionNotification Method
Sends an asynchronous message when there is a change in the status of the connection to the MBeanServer(s).
Type Asynchronous, IMPACT_INFO
Arguments Parameter Type Description MBeanServerAlias String The list of MBean servers separated by ";", from which you want to receive messages when there is a change in the status of the connection. If the MBeanServerAlias is not specified, status change messages are sent for all MBeans servers.
TypeFilter String The list of Types or Type prefixes separated by ";" used to filter notifications. If no filter is supplied, all notifications are sent.
Returns Parameter Type Description MBeanServerAlias String The MBeanServer Alias
MBeanName String The name of the MBean
TimeStamp String The time stamp of the notification.
Type String The type of Notification
UserData String The user data
SeqNum Long The sequence of the notification
Message String The message
ConnectionID String The connection id
Source String The source of the message
TIBCO Hawk JMX Plug-in User’s Guide JmxPluginMicroAgent:getLoadedMBeans | 19
JmxPluginMicroAgent:getLoadedMBeans Method
Returns a table listing all loaded MBeans from the MBean Server.
Type Synchronous, IMPACT_INFO
Arguments Parameter Type Description MBeanServerName String The user specified MBean server name.
Returns Parameter Type Description Name String The name of the MBean.
Display name String The display name of the MBean.
MBeanServer String The connection URL for the MBean server. Connection URL
MBeanServerName String The user specified MBean server name.
TIBCO Hawk JMX Plug-in User’s Guide 20 | Chapter 2 Using TIBCO Hawk JMX Plug-in
JmxPluginMicroAgent:getReleaseVersion Method
Returns version information about the current release of the plug-in.
Type Synchronous, IMPACT_INFO
Arguments None
Returns Parameter Type Description Name String The release name.
Version String The release version. Same as the concatenation of the major, minor and update fields with periods (.) between.
Date String The release date.
Major String The version major number.
Minor String The version minor number.
Update String The version update number.
TIBCO Hawk JMX Plug-in User’s Guide onMBeanNotification | 21 onMBeanNotification Method This method is created for each microagent whose corresponding MBean is capable of emitting notifications.
Type Asynchronous, IMPACT_INFO
Arguments Parameter Type Description TypeFilter String Send notifications for given type/type prefixs separated by ";". If the type is not supplied, all notifications are sent.
Returns Parameter Type Description TimeStamp String The time stamp.
Type String The type of notification.
UserData String The user data.
SeqNum Long The sequence of the notification
Message String The notification message.
Event String The notification class name.
Source String The source of the notification.
TIBCO Hawk JMX Plug-in User’s Guide 22 | Chapter 2 Using TIBCO Hawk JMX Plug-in
TIBCO Hawk JMX Plug-in User’s Guide | 23
Chapter 3 Using The Sample Application
This chapter describes the sample application packaged with the plug-in.
Topics
• Overview, page 24 • Registering an MBean, page 25 • Unregistering an MBean, page 27 • Building a Rulebase, page 28
TIBCO Hawk JMX Plug-in User’s Guide 24 | Chapter 3 Using The Sample Application
Overview
The sample application contains a servlet for registering and unregistering MBeans. The sample application can be used only with Tomcat application server. Before invoking the servlets, use TIBCO Hawk WebConsole to subscribe to the JMXPluginMicroAgent:onMBeanServerNotification method. Subscribing to this method brings up a Subscription Results window. Initially this window is empty, but each time an MBean is either registered or unregistered, the corresponding message is displayed here. 1. Stop the Tomcat Server.
2. Copy the jmxweb.war file from TIBCO_HOME/hawk/
— RMIConnServerPortNum: RMI Connection Server Port Number
— RMIRegistryPortNum: RMI Registry Port Number
— HttpHostName: Http Adaptor Host Name
— HttpAdaptorPortNum: Http Adaptor Port Number For details on updating the configuration file used by the plug-in, see section "Customising the MBeanServer Element" of the TIBCO Hawk JMX Plug-in Installation Guide.
TIBCO Hawk JMX Plug-in User’s Guide Registering an MBean | 25
Registering an MBean
This section describes the sample application which when invoked registers an MBean MyDomain:name=index
http://
TIBCO Hawk JMX Plug-in User’s Guide 26 | Chapter 3 Using The Sample Application
A microagent for this MBean is dynamically created. If the filters set in the configuration file includes the above named MBean, it can be accessed using TIBCO Hawk WebConsole. The following figure shows the microagent corresponding to the MBean created by the servlet.
TIBCO Hawk JMX Plug-in User’s Guide Unregistering an MBean | 27
Unregistering an MBean
Follow these steps to use the sample application to unregister an MBean: 1. Open a brower and type the following address: http://
TIBCO Hawk JMX Plug-in User’s Guide 28 | Chapter 3 Using The Sample Application
Building a Rulebase
This section describes the steps involved in creating a rulebase called MBean_Registration which lists MBean servers with an MBean count greater than or equal to 0. A TIBCO Hawk alert is generated by the MBean_Registration rulebase when the MBean count is greater than or equal to 0.
Create a new rulebase To create a new rulebase in TIBCO Hawk WebConsole: 1. Click an agent listed in the Agents portlet on the Hawk Dashboard. The Agent tab opens. The name of the Agent tab is same as the selected agent name
4. Enter the other fields, as required.
TIBCO Hawk JMX Plug-in User’s Guide Building a Rulebase | 29
5. Click Apply Changes to save the current changes. 6. Click Apply & Add Rule to save the changes and proceed to the rule building process.
Create a new rule 1. On the Rule Editing screen, choose a microagent and then select the corresponding method.
2. Select the JMXPluginMicroAgent microagent. The Methods panel displays the methods for the microagent. 3. Select the getMBeanCount method. The Description panel displays a detailed description of the method, including arguments and return values. The Arguments panel displays the fields for method arguments and a data interval.
TIBCO Hawk JMX Plug-in User’s Guide 30 | Chapter 3 Using The Sample Application
4. In the MBeanServerName field, specify the name of the MBean server. The getMBeanCount method returns a table listing the MBean server and its MBean count. If an MBean server name is not specified, it returns a list of all the MBean server names and the MBean count for each server. 5. Click Apply Changes to save the current changes. 6. Click Apply and Add Test to save the changes and proceed to defining the test process. The rule is now configured to use the getMBeanCount() method of the JMXPluginMicroAgent microagent.
Create a test Build a test expression by specifying a test parameter and test operator in the Test screen. To create a new test in the current rule: 1. Go to the Test screen.
2. You can specify if you want to match all, match any, or match none.
TIBCO Hawk JMX Plug-in User’s Guide Building a Rulebase | 31
3. Specify the test expression as MBeanCount greater than or equal 0. 4. Click Apply Changes to save the test expression. 5. Click Apply and Add Action to save the changes and proceed to defining the action process.
Create Action 1. Go to the Action screen.
2. Select Alert as the action type from the radio buttons across the top of the screen. 3. For Alert Level, select High. 4. Click Save and Deploy to save changes and deploy it to the agent. The MBean_Registration rulebase is included in the Rulebase tree.
Viewing the Results Follow the steps outlined in Registering an MBean on page 25 to register a new MBean.
TIBCO Hawk JMX Plug-in User’s Guide 32 | Chapter 3 Using The Sample Application
When the MBean count is greater than or equal to 0, an alert message is generated by the MBean_Registration rulebase. To view this alert: 1. Click on the Alerts tab. The Alert Display window shows the alert generated by the MBean_Registration rulebase:
2. Click the arrow to display Alert Details.
TIBCO Hawk JMX Plug-in User’s Guide Building a Rulebase | 33
TIBCO Hawk JMX Plug-in User’s Guide 34 | Chapter 3 Using The Sample Application
TIBCO Hawk JMX Plug-in User’s Guide | 35
Appendix A Sample Configuration Files
This appendix lists sample JMXService.hma and JMXPluginConfig.xml configuration files.
Topics
• JMXServiceMA.hma, page 36 • JMXPluginConfig.xml, page 37
TIBCO Hawk JMX Plug-in User’s Guide 36 | Appendix A Sample Configuration Files
JMXServiceMA.hma
TIBCO Hawk JMX Plug-in User’s Guide JMXPluginConfig.xml | 37
JMXPluginConfig.xml
TIBCO Hawk JMX Plug-in User’s Guide 38 | Appendix A Sample Configuration Files
TIBCO Hawk JMX Plug-in User’s Guide JMXPluginConfig.xml | 39
TIBCO Hawk JMX Plug-in User’s Guide 40 | Appendix A Sample Configuration Files
TIBCO Hawk JMX Plug-in User’s Guide | 41
Appendix B Error Messages
This appendix list the error messages used by TIBCO Hawk JMX Plug-in.
Topics
• TIBCO Hawk JMX Plug-in Error Messages, page 42
TIBCO Hawk JMX Plug-in User’s Guide 42 | Appendix B Error Messages
TIBCO Hawk JMX Plug-in Error Messages
Please check argument for Server type for MBeanServerElement %1 %2 is not a Valid Server Type. WebLogic, JBoss3, WebSphere and JSR160 is a valid MBeanServer type. Ignoring this MBean Server Role: Error Resolution: Please specify a valid MBean server type in the configuration file and re-start TIBCO Hawk Agent.
’AddMBeanServerName' should be set to 'true' to avoid naming conflict. Role: Warning Resolution: Please make sure the specified file exists.
File: %1 does not exists. Please check location. Role: Error Resolution: Please make sure the specified file exists.
Exception caught in IntializeMicroAgent : %1 %2 Role: Error Resolution: Please contact TIBCO Support.
Exception in setMicroAgentContainer: %1 Role: Error Resolution: Please contact TIBCO Support.
Error setting AsyncDataHandler for Worker Thread for start of subscription. Role: Error Resolution: Please contact TIBCO Support.
Error setting AsyncDataHandler for Worker Thread for stop of subscription. Role: Error Resolution: Please contact TIBCO Support.
TIBCO Hawk JMX Plug-in User’s Guide TIBCO Hawk JMX Plug-in Error Messages | 43
Attribute not found Exception: %1 Role: Error Resolution: Make sure the MBean to which this attribute belongs to exists. If the problem persists, contact TIBCO Support.
Invalid Attribute Value Exception: %1 Role: Error Resolution: Please contact TIBCO Support.
Instance not found Exception: %1 Role: Error Resolution: Make sure the MBean to which this attribute belongs to exists. If the problem persists, contact TIBCO Support.
Reflection Exception: %1 Role: Error Resolution: The signature of the MBean may have changed. If this is the case, re-start TIBCO Hawk Agent.
Runtime Error Exception: %1 Role: Error Resolution: Please contact TIBCO Support.
Remote RMI Exception : %1 Role: Error Resolution: Check the connection to the application server.
IO Exception : %1 Role: Error Resolution: Check the connection of the plug-in with the MBean sever. If the problem persists, please contact TIBCO Support.
TIBCO Hawk JMX Plug-in User’s Guide 44 | Appendix B Error Messages
Error removing MicroAgents from Agent attached on Thread:%1 Role: Error Resolution: Re-start TIBCO Hawk Agent. If the problem persists, contact TIBCO Support.
Exception caught in Filtering MBean: %1 Role: Error Resolution: Check the syntax of the MBean filter specified in the configuration file and re-start TIBCO Hawk Agent.
Security Exception Decrypting password %1 Please check the password entered and restart the Hawk Agent. Role: Error Resolution: Please check the password and re-start TIBCO Hawk Agent.
Ignoring MBean: %1 because it has No Attribute and No Operation. Role: Info
Ignoring MBean %1 due to the following error: %2. Role: Error Resolution: Depends on the content of the exception.
Waiting for 2 Seconds before contacting %1 connection server at: %2 Role: Info
TIBCO Hawk JMX Plug-in User’s Guide