JMX Overview

JMX is a Java standard for monitoring and managing applications written in the Java development language. JMX supports distributed monitoring and management capabilities and allows access to JMX attributes and operations via a variety of access protocols.

Firescope leverages the access capabilities made available in JMX to deliver the ability to monitor or manipulate many JMX data attributes or operations. In order to deliver these capabilities several configurations must be initiated. The following document is intended to guide the user through the necessary configurations required to enable JMX capabilities for use with the FireScope appliance.

Firescope JMX Monitoring Architecture

The figure below details a simple FireScope appliance monitoring 2 host each of which houses 2 Java applications.

The following points highlight the necessary steps required for JMX monitoring with FireScope:
• Configure your Java JVM to allow access to its MbeanServer.
• Use JConsole if necessary to discover deployed Mbean names, attribute names and operation names.
• Create new UserParameters in your remote FireScope agent which will in turn make invocations through the jmxclient.jar file to interact with your targeted JMX beans.
• Create items on the FireScope server which reference the newly created UserParameters.

Java Virtual Machine (JVM) configuration

Each Java virtual machine that will be monitored must be configured to allow access to the JMX server that runs inside of each monitored Java virtual machine. Configuration is accomplished by providing a few system parameters to the Java virtual machine upon application startup. The parameters are listed below along with their description.

Example:
/ /java -Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=3306 -Dcom.sun.management.jmxremote.authenticate=false

Warnings:
• Each configured Java virtual machine must use a separate port configuration.
• Configured ports must not conflict with any ports currently in use on the system being configured.
• Use netstat to ensure valid selection of configured ports.
• On Unix / Linux systems use ports > than 1000

JMX Discovery

JConsole is a JVM monitoring application that has been in existence since the release of Java JDK 1.5.x. With JConsole it is possible to explore all JMX managed beans in a virtual machine once the JVM is configured to allow JMX remote access as described above. The JConsole executable can be found in the bin directory for your JDK1.5.x or greater installation.

Launch JConsole and select the "Remote Process" option button. Enter "localhost: " in the entry text box, where the port is the configured JMX listener port. Then select the "Connect" button.

Once started, JConsole will display several tabs. Select the "Mbeans" tab. Along the left hand side is a tree view that lists each deployed Mbean in the JMX Managed Bean Server. The treeview allows exploring down to each Mbean and displays each Mbean attribute or operation. Once you have navigated down to the bean level JConsole will display the Mbean name in the display on the right hand side.

Notes:
• JConsole is not required for use with the FireScope monitoring. It is described here for the user's understanding and for exploring beans deployed to your Mbean server.
• JConsole is part of the JDK download, not the JRE.
• All Mbeans are uniquely identified by name.
• In order to access the attributes or operations of an Mbean you must reference the bean using its unique name.
• In order to maintain uniqueness in names servers such as Tomcat and JBoss, use complex nested names.

Individual JMX attribute access

FireScope makes available a client access tool called jmxclient for querying and setting individual Mbean attributes and invoking Mbean operations. As described above, the JConsole utility can be used to determine the names and attributes of Mbeans deployed in a particular java virtual machine. The bean names, attributes names and operation names are passed to the jmxclient tool for access.

First deploy the jmxclient.jar file to an appropriate location on your monitored system. The following example uses a bean names from a system that has a default Tomcat version 6.0.13 deployed running and configured for JMX access.

The jmxclient tool uses the following command format:
/java -Dhost= -Dport= -DbeanName= -Dattribute= -Dparameters= -DnestedResult= -jar /jmxclient.jar

The following example command line will retrieve the “requestCount� attribute from the deployed tomcat manager application that comes as a part of the standard Tomcat deployment:

/java -Dhost=localhost -Dport=3306 -DbeanName= Catalina:j2eeType=Servlet,name=HTMLManager,WebModule=//localhost/manager,J2EEApplication=none,J2EEServer=none -Dattribute=requestCount -jar jmxclient.jar

Note the nested / complex bean name created by Tomcat shown again as follows:
Catalina:j2eeType=Servlet,name=HTMLManager,WebModule=//localhost/manager,J2EEApplication=none,J2EEServer=none

Invoking the above command returns the current requestCount.

Now invoke the manager via a web browser as follows:
http://localhost:8080/manager/html

Example of FireScope JMX Managed Beans

The FireScope solution is delivered with an application called SyslogListener. The SyslogListener application receives syslog messages over TCP/IP and transfers these messages to the FireScope database. The SyslogListener application contains a few managed beans which expose some data points which may be of interest to FireScope users. The exposed beans are described in the following table:

/java -Dhost=localhost -Dport=3306 -DbeanName=com.firescope.sysloglistener:name=ReceiveMessageCount -Dattribute=PerMinuteMessageCount -jar jmxclient.jar /java -Dhost=localhost -Dport=3306 -DbeanName=com.firescope.sysloglistener:name=ReceiveMessageCount -Dattribute=DailyMessageCount -jar jmxclient.jar /java -Dhost=localhost -Dport=3306 -DbeanName=com.firescope.sysloglistener:name=PersistedMessageCount -Dattribute=PerMinuteMessageCount -jar jmxclient.jar /java -Dhost=localhost -Dport=3306 -DbeanName=com.firescope.sysloglistener:name=PersistedMessageCount -Dattribute=DailyMessageCount -jar jmxclient.jar /java -Dhost=localhost -Dport=3306 -DbeanName=com.firescope.sysloglistener:name=MessageExecutionTime -Dattribute=DurationMilliSeconds -jar jmxclient.jar /java -Dhost=localhost -Dport=3306 -DbeanName=com.firescope.sysloglistener:name=DatabaseRefresher -Dattribute=ForceDatabaseRefresh -jar jmxclient.jar

FireScope JMX agent configuration

The following list outlines prerequisites for enabling FireScope JMX monitoring on remote hosts:
• A valid Java runtime (JRE) must be deployed and available on the remote host
• The jmxclient.jar file must be deployed and executable on the remote host.
• UserParameters must be defined and added to the agent configuration file on the remote host.
• The remote agent must be restarted
• It is recommended that the new UserParameter be tested on the remote host

For the purposes of this example we shall assume each of the following has been configured as described below:
• A Java VM has already been configured for JMX access on port 4900
• A Java executable exists in the path
• The jmxclient.jar file has been deployed to /jars directory
• Our new user parameter shall be called “java.application.monitored.valueâ€�
• Our JMX bean name is called “application.MBeanâ€�
• The property of interest on this Mbean is called “propertyâ€�

To configure our new user parameter we edit the agent configuration file by adding the following line:
UserParameter=java.application.monitored.value,java -Dhost=localhost -Dport=4900 -DbeanName=application.MBean -Dattribute=property -jar /jars/jmxclient.jar

JMX enabling your own Java applications

The code listed below describes the steps necessary to make your applications JMX capable. The process covered outlines only standard Mbeans. For more information regarding other typs of Mbeans such as MXBeans, or DynamicBeans refer to the following JMX API documentation or Java tutorial: http://java.sun.com/javase/6/docs/api/

http://java.sun.com/javase/6/docs/technotes/guides/jmx/tutorial/tutorialTOC.html.

For any class that you wish to make available to JMX you must write an Mbean interface that lists the available JMX methods. The Mbean interface name must have the same prefix name as the implementing class.

public interface ExecutionMessageCounterMBean { public long getPerMinuteMessageCount(); public long getDailyMessageCount(); }

Then provide an implementation for the above interface such as the following:

import java.util.Calendar; 
public class ExecutionMessageCounter implements ExecutionMessageCounterMBean 
{ 
private int lastIndex; 
private long[] perMinuteMessageCount; 

public ExecutionMessageCounter() 
{ 
super(); 
lastIndex = 0; 
perMinuteMessageCount = new long[1440]; 
} 

public long getPerMinuteMessageCount() 
{ 
int perMinuteMessageCountIndex = getMinuteIndexNow();
return perMinuteMessageCount[perMinuteMessageCountIndex]; 
} 

public long getDailyMessageCount() 
{ 
long dailyMessageCount = 0; 
for(long oneMinuteCount : perMinuteMessageCount) 
{ dailyMessageCount += oneMinuteCount; }
 return dailyMessageCount; }

private synchronized int getMinuteIndexNow() 
{ 
Calendar calendar = Calendar.getInstance(); 
int resultIndex = calendar.get(Calendar.HOUR_OF_DAY) * 60 + calendar.get(Calendar.MINUTE); return resultIndex; 
} 
}

ExecutioinMessageCounter counter = new ExecutionMessageCounter(); 
MBeanServer mBeanServer = ManagementFactory.getPlatformMBeanServer(); 
try { ObjectName objectName = new ObjectName(“example:name=MessageCounterâ€); mBeanServer.registerMBean(counter, objectName); } 
catch(Exception exception) 
{ // Add appropriate exception handling }