Manage your JMX-enabled applications with jManage 1.0

An introduction to jManage 1.0 using J2SE 5.0 platform MBeans as examples

If you have worked with first-generation Java Management Extension consoles (like HTML Adaptor or the JBoss JMX console) in a distributed environment, you have not really seen the power of JMX client technology. Managing a clustered application by going to every application's JMX console is a highly manual and error-prone process. A distributed or clustered applications environment needs a centralized JMX console.

Then there are questions of access control: Who should be allowed to access the information exposed via MBeans (managed beans)? Who should be allowed to make changes during runtime? A clear need for fine-grained access control is prevalent. Administrators should be able to give just read-only access to development and quality assurance teams while retaining full access in the administration/operations group.

In the past, you might have used log files to figure your application's runtime behavior. Or you might have written custom management interfaces to get runtime information, perform runtime administrative operations, or for sending alerts when something goes wrong. JMX makes it easy to instrument applications using MBeans, Java objects that represent manageable resources. With MBeans, JMX-enabled applications can be managed and monitored using JMX clients.

jManage is an open source, Web and command line-based JMX client that has been built based on the real needs of production environments. It offers a centralized console for managing application clusters and distributed-application environments. The tool also provides alerts, graphs, security, SNMP (Simple Network Management Protocol) support, and fine-grained access control. jManage supports custom remoting protocols for Weblogic 6+, JBoss 3.2+, Websphere 5+, along with the standard JMX Remote API protocol (Java Specification Request (JSR) 160).

Let's first look at what J2SE 5.0 MBeans have to offer.

J2SE MBeans

With J2SE 5.0, you can now monitor the JVM via MBeans. MBeans are available for threading, memory, classloading, etc., allowing you to:

  • Get thread dumps using a JMX client
  • Graph your heap or nonheap memory usage
  • See how garbage collection is working for you, or run GC if you like
  • Turn on verbose classloading logs
  • Look at configured JDK loggers and change log level without restarting the application

Now, we will set up jManage to look at these MBeans.

Setting up jManage

jManage is a Struts-based application that runs on an embedded Jetty server. You can download either jmanage-1.0.1.zip or jmanage-1.0.1.tar.gz and extract the files to a folder named jmanage-1.0.1. Please see Resources for the link to the download page. The jManage scripts are in the bin folder. If you are running in a Unix environment, you will need to make the .sh files executable by running the chmod +x *.shcommand.

If you run jManage in a secure environment (e.g., production), you should generate a key using the keygen script. Running this script also sets up the "admin" user password and writes an encrypted key in the jmanage-key file under the config folder.

If you have not generated the key, you can use the default key that is part of the jManage distribution. In this case, the admin user's password is 123456.

Start jManage server by running the startup script. You will be asked for the admin user password. You can avoid the prompt by passing the password as an argument to the startupscript. You can later use the shutdownscript to stop the jManage server.

The jmanage script runs the command line interface. You can get a list of available commands by typing the helpcommand.

jManage runs on port 9090 by default. You can now use the Web interface by going to http://localhost:9090 and logging in as admin user. You then add your application by using the Add Application link.

Configure a J2SE 5.0 application for management

To enable your J2SE 5.0 application for remote management, add the following system properties to your application:

                    com.sun.management.jmxremote.port=9999
com.sun.management.jmxremote.authenticate=false
com.sun.management.jmxremote.ssl=false
             

For example:

                    java -Dcom.sun.management.jmxremote.port=9999 
   -Dcom.sun.management.jmxremote.authenticate=false 
   -Dcom.sun.management.jmxremote.ssl=false mypackage.MyClass
             

Add this application in jManage as a JSR 160 application with the following URL: service:jmx:rmi:///jndi/rmi://localhost:9999/jmxrmi

Choose your management interface

Applications configured in jManage can be managed using one of the following interfaces:

  • Web interface:This interface is the easiest to use. Just point your browser to the jManage server, log in with your username and password, and use the simple WYSIWYG interface.
  • Command line interface:If you like to set up automated scripts, this is the interface for you.
  • Java API:You can access jManage via a set of Java APIs, which allows jManage to be used as a backend system and also allows applications to register themselves as they come online. This interface is new in the 1.0 release and still experimental.

In most cases, you will use the Web interface, which is used to illustrate this article's examples. Figure 1 shows a screenshot of the MBeans available in J2SE 5.0:

Figure 1. Platform MBeans in J2SE 5.0. Click on thumbnail to view full-sized image.

Simple MBean operations

To illustrate jManage's functionality, let's start by configuring the garbage collector to produce verbose output. Do that by setting the Verbose attribute of the java.lang:type=MemoryMBean to True, as Figure 2 illustrates.

Figure 2. Memory MBean. Click on thumbnail to view full-sized image.

After pressing the Save button, you will see the following output in the application console:

                    [GC 30604K->27980K(39968K), 0.0002749 secs]
[GC 30604K->27979K(39968K), 0.0003070 secs]
[GC 30603K->27979K(39968K), 0.0002981 secs]
[GC 30603K->27980K(39968K), 0.0003026 secs]
             

You can then turn off GC logging by setting the Verboseattribute to False.

Now, let's get some thread dumps. A thread dump can be produced by executing the getThreadInfo operation on the java.lang:type=ThreadingMBean. Figure 3 shows how to dump thread IDs 1 through 4.

Figure 3. Thread dump. Click on thumbnail to view full-sized image.

The first argument of the getThreadInfo operation is the array of thread IDs, and the second argument is the stack trace depth.

Let's draw some graphs

You can create named graphs in jManage using MBean attribute values. The attribute values can be scaled up or down. For example, in the case of the Heap Usage graph, the MBean attribute values in bytes are converted to megabytes by applying a scale-down factor of 1048576 (1024 x 1024). Figure 4 shows the Heap Usage graph configuration.

Figure 4. Heap Usage graph configuration. Click on thumbnail to view full-sized image.

And Figure 5 illustrates this graph.

Figure 5. Heap Usage graph. Click on thumbnail to view full-sized image.

The Thread Count graph shown in Figure 6 is configured using the DaemonThreadCount, PeakThreadCount, and ThreadCountattributes of the java.lang:type=ThreadingMBean.

Figure 6. Thread Count graph. Click on thumbnail to view full-sized image.

Get notified via alerts

You can configure alerts in jManage for MBean notifications and also for MBean attribute value thresholds. Alerts can be delivered to the jManage console or to an email address. Figure 7 shows an example of an alert for the java.management.memory.threshold.exceedednotification.

Figure 7. Alert configuration

Alert delivery can be customized by extending the org.jmanage.core.alert.AlertDeliveryinterface and configuring this interface in alert-config.xml. See org.jmanage.core.alert.delivery.EmailDelivery for an example.

Cluster management

Cluster management is a unique feature of jManage and has been available since the 0.1 version.

Traditional JMX consoles work on a single application at a time. If you need to perform an operation across a cluster of n servers, you must do it n times. With jManage, MBeans can be viewed at the cluster level, allowing attributes to be updated and operations to be performed from a single Webpage (or a single command from a command line interface).

For example, if you have a cache instrumented via a CacheMBean, with the clear() operation to clear the cache, jManage allows this cache to be cleared throughout the cluster using any of the available interfaces (Web, command line, or Java API).

Figure 8 shows a cluster view of the java.lang:type=MemoryMBean for two applications. You can change the Verbose attribute for both applications just from this page. You can also execute the gc operation to run the garbage collector in both applications.

Figure 8. Cluster view of Memory MBean. Click on thumbnail to view full-sized image.

Let's now understand the authentication and access control features provided by jManage.

Production environment needs control

jManage provides a simple authentication module with users stored in the jmanage-users.xml file. Though this module is sufficient for most installations, a custom authentication module can be configured via the JAAS (Java Authentication and Authorization Service) configuration file (jmanage-auth.conf). The username is specified in NameCallbackand password in PasswordCallback. See the org.jmanage.core.auth.LoginModule as an example.

jManage, by default comes with administrator and userroles, where administrator is configured with full access and user with read-only access. New roles can be added by modifying jmanage-user-roles.xml.

The access rights for these roles are defined in acl-config.properties. This properties file allows fine-grained access control. Access can be controlled even at the MBean attribute or operation level. For example, to only allow the users in the administrator group to execute the gc operation in the java.lang:type=Memory MBean, add the following line in acl-config.properties:

                    acl.execute.jmanage.mbean.operations@*/java.lang:type=Memory/
   gc=Administrator
             

For more information on access control, please read the jManage access control document.

jManage can be extended by adding custom data formatters. Let's see how.

Format display of your custom data

jManage comes with a set of default data formatters configured in html-data-format.properties (for Web interface) and text-data-format.properties(for command line interface). You can configure your custom data formatters in these files. The compiled custom data formatters should be placed as a jar file under the jManage lib directory.

Data formatters for data types are specified as:

                    format.mypackage.MyData=mypackage2.MyDataFormat
             

For example:

                    format.javax.management.openmbean.CompositeData=org.jmanage.core.
   management.data.HtmlCompositeDataFormat
             

You can also specify custom data formatters based on the result of CompositeType.getTypeName(). These formatters are specified as:

                    CompositeTypeFormat.
             

<compositetypename/>

=mypackage.MyDataFormat

For example:

                                       CompositeTypeFormat.java.lang.management.ThreadInfo=org.jmanage.core.
   management.data.jdk.ThreadInfoFormat
                    
             

The custom data format classes extend the following interface:

                    

package org.jmanage.core.management.data;

public interface DataFormat { public String format(Object data); }

SNMP support

jManage 1.0 features basic SNMP support. It is still experimental and only allows for viewing simple attributes. The tool's SNMP support can potentially be used for monitoring devices like firewalls, load balancers, or operating systems.

jManage 1.5 release

The jManage team is now working on the 1.5 release. This release will transform jManage from a JMX client to a management platform, with features like:

  • Easy-to-use dashboards framework
  • Connector framework for non-JMX applications
  • Improved SNMP support
  • Support for database management (Oracle, MySQL)

jManage 1.5 is scheduled to be released in the second quarter of 2006.

Conclusion

jManage 1.0 provides a production-level JMX client for managing distributed applications and clusters. It provides advanced features like graphs, alerts, and fine-grained access control. The ability to customize jManage for your needs makes it even more powerful.

The jManage mission is to provide an open source management platform that can be used to manage and monitor a complete production environment. The tool is already being used by different users in development, quality assurance, and production environments. The 1.5 release will enable the management and monitoring of a large part of your production environment.

Rakesh Kalrahas more than seven years of experience in the software industry, most of it in the Java and enterprise Java space. Currently, he is working as a senior systems analyst at a large-scale financial services company based in the Boston area. Kalra started his software career in Bangalore, India, and moved to the U.S. in 2000. He spends his free time leading the jManage.org community.

Learn more about this topic

Join the discussion
Be the first to comment on this article. Our Commenting Policies