Java Applications

Topics marked with * relate to features available only in vFabric Hyperic.

Auto-Discovery of Custom MBeans

The HQ Agent can auto-discover and manage Java application services via Model MBeans that adhere to a specified ObjectName naming convention and expose a specified set of service data. This enables you to monitor application services along with the hosting application server and its internal services.

Prerequisites and Supported Environments

This section specifies requirements for HQ auto-discovery and management for Java application services.

Java Version

Auto-discovery of services exposed as ModelMBeans requires a version 1.5 or later JRE or JDK.

Supported Containers

The capability is supported for applications running in:

Enable Discovery of a Stand-Alone Instrumented Java Application

To enable MBean discovery in a stand-alone Java Application, you must:

  • Instrument your code as specified in Model MBean Naming and Descriptor Data, or be using Spring Framework instrumented jar files, and

  • Start the application with the spring.managed.application.name system property. For example:
    java -Dcom.sun.management.jmxremote -Dspring.managed.application.name="MyApplicationName" com.sample.MyApp

The application name will be set as the name of the discovered resource — in this example, MyApplicationName.

MBeanServer

The application servers listed in Supported Containers generally have an existing MBeanServer. If your container does not have an MBeanServer - as is the case with Tomcat if you haven't previously set it up - you must configure one along with a JSR-160 connector. See the directions below.

Create a MBeanServer in Tomcat

If you wish to monitor applications running on Tomcat, make sure it has a MBeanServer.  If it doesn't, you can create an MBeanServer and associated
connector by setting the appropriate system properties at JVM startup.

You can add the system properties to the Tomcat start script, $TOMCAT_HOME/bin/catalina.sh:

[ $1!= "stop" ] && JAVA_OPTS="-Dcom.sun.management.jmxremote \
-Dcom.sun.management.jmxremote.port=6969 \
-Dcom.sun.management.jmxremote.ssl=false \
-Dcom.sun.management.jmxremote.authenticate=false $JAVA_OPTS"
export JAVA_OPTS

For more information, visit:

Create an MBeanServer for Stand-Alone Apps or Other Container

To create a MBeanServer for an application than runs stand-alone or a container other than those listed Supported Containers, set the JMX remote system properties in the application or container start script. These system properties create a local MBeanServer and remote connector:

-Dcom.sun.management.jmxremote \
-Dcom.sun.management.jmxremote.port=6969 \
-Dcom.sun.management.jmxremote.ssl=false \
-Dcom.sun.management.jmxremote.authenticate=false \

Enable ModelMBean Export in JBoss Containers

There is a known issue with HQ discovery of services running in JBoss - when the JBoss interceptor publishes the MBeans for the services, it does not export them as type "Model", preventing HQ from detecting them. You can work around this issue by commenting out the following entry in
JBOSS_HOME/server/default/deploy/jmx-invoker-service.xml:

<!-- Interceptor that deals with non-serializable results -->
     <!--><interceptor code="org.jboss.jmx.connector.invoker.SerializableInterceptor"
      policyClass="StripModelMBeanInfoPolicy"/> -->

Step 1 - Set Up Resources to Export ModelMBeans

Each Java class or service must instantiate Model MBeans that meet the requirements described in Model MBean Naming and Descriptor Data.

There are multiple methods for creating Model MBeans. The process is not documented here. A variety of information is available on the Sun site. Introductory material and examples are available in:

Note: Redeploy your application after enabling export of Model MBeans.

Applications with SpringSource Instrumented Jars

If your applications run with Spring instrumented JARs, they should automatically export Model MBeans with the required name format and descriptors.

Applications using Spring 3.0 JMX Annotations

If your applications expose MBeans using the Spring 3.0 JMX annotations (@ManagedResource, @ManagedMetric, @ManagedAttribute, @ManagedOperation), they should automatically be exported with the required descriptors.

Step 2 - Verify Model MBean Export to MBeanServer

To verify that your your application services have instantiated ModelMBeans, you can use a JMX client to browse the MBeanServer.

Step 3 - Verify Service Application Auto-Discovery

The HQ Agent managing the server instance where your application runs should discover Model MBeans in the MBeanServer that meet the requirements specified in Model MBean Naming and Descriptor Data.

The server instance that hosts the application will appear in the Auto-Discovery portlet on the Dashboard of the HQ user interface. After you import the new or changed server instance to inventory, you can browse to the application services, which will appear as children of the host server.

Solving Problems with Service Auto-Discovery

If your application services were not discovered, verify that:

  • The hosting application server is enabled for remote JMX remote access.

  • The JMX properties (the JMX URL, username, and password) for the server were auto-discovered by the HQ Agent, or entered manually, if necessary. If the HQ Agent auto-discovered the JMX properties, they appear on the Configuration Properties page for the server instance. If the agent did not discover the JMX properties, an authorized HQ user must specify them on the server instance's Configuration Properties page.

For information on how to configure JMX remote see Sun's website (hhttp://download.oracle.com/javase/1.5.0/docs/guide/management/agent.html).

Step 4 - Configure App Services as an Application in HQ

You may find it useful to configure an HQ application that groups the discovered services for an application.

  1. Click Resources->Browse in the HQ user interface.

  2. Select New Application from the Tools menu.

  3. Enter a name for the application in the Name text box and click OK.

  4. Click Add to List in the "Services" section of the page.

    • The left column on the Edit page for the application lists all of the services in HQ that you have permission to view. The name of a discovered application service contains the name of the application, as specified in the associated ModelMBean's ObjectName. (This is true only if the application name was specified in the ObjectName.)

  5. To filter the list by its application name or another identifying string, enter the string in the Filter By Name text box, and click the green arrow.

  6. Place a checkmark next to each service that belongs to the application, click the right arrow to move the services into the right column, and click OK to add selected services to the application.