Monitoring Memory with the EM4J MBeans

The EM4J Java library, Balloon.jar, includes four MBeans you can access through JMX to view the state of EM4J in a JVM.

You can use vFabric Hyperic Server or JConsole, a JMX client included with the Java HotSpot JDK, to view the MBeans.

Viewing EM4J MBeans with Hyperic Server

To view MBeans in the Hyperic user interface, you first need to add the target JVM as a server. Follow this procedure for each JVM with EM4J MBeans you want to view.

Procedure

  1. In the Hyperic user interface, click the Resources tab.

  2. Click Platforms.

  3. Click the name of the platform (VM) where the target JVM is running.

  4. Select Tools Menu > New Server.

  5. In the Name field, enter a name for the JVM.

  6. Under Type & Host Properties, choose Sun JVM 1.5 for the Server Type.

    Although EM4J requires Java 1.6, you can use the Hyperic Sun JVM 1.5 server type to define the server, since the JMX interface is compatible.

  7. In the Install Path field, enter the path to the Java installation directory.

  8. Click OK. The server is added and a message appears:

    This resource has not been configured. Please set it's Configuration Properties.

  9. Click Configuration Properties.

  10. In the jmx.url field, enter the JMX URL:

    service:jmx:rmi:///jndi/rmi://localhost:6969/jmxrmi

    The JMX port, 6969 by default, is configured in the server.xml file for the tc Server.

  11. In the jmx.username and jmx.password fields enter the JMX username and password. The defaults are admin and springsource.

  12. Click OK.

The JVMs you add appear in the Servers list on the Resources tab. Follow this procedure to view MBeans in the Hyperic user interface.

Procedure

  1. In the Hyperic user interface, click Resources.

  2. Click the Servers link.

  3. Click the name of the JVM you added.

  4. Click the Views tab.

  5. Click the JMX MBean Query button.

  6. In the Object Name Pattern field, enter a query string like the following to select the EM4J MBeans:

    com.springsource.balloon:type=com.springsource.balloon.jmx.*
  7. Click Query MBeans.

Viewing EM4J MBeans with JConsole

The Java HotSpot JDK includes JConsole, a GUI JMX client, you can use to view MBeans in tc Runtime. JConsole is not included in the JRE; you need the JDK.

JMX must be configured in the tc Server instance. The base template configures JMX for local access by default. To enable remote JMX access, you must edit CATALINA_HOME/conf/server.xml and change the bind attribute of the JMX Listener element from 127.0.0.1 to the computer's IP number or host name so that JMX is addressable from the network. If you have disabled JMX, you can re-enable it by adding a Listener to your tc Runtime Server.xml configuration file as shown in "Simple tc Runtime Configuration" in VMware vFabric tc Server Administration.

To connect to an EM4J-enabled JVM, you need to know the JMX port and, if authentication is enabled for the JMX listener, the username and password. By default, JMX listens on port 6969, the username is admin, and the password is springsource.

Procedure

  1. Open a terminal window on the VM running the JVM you want to connect to.

  2. Start jconsole with a command like the following:

    prompt$ $JAVA_HOME/bin/jconsole
  3. In the New Connection window select Remote Process and enter localhost:port, where port is the JMX management port, 6969 by default:

  4. Enter the JMX Username and Password. The defaults are admin and springsource, respectively.

  5. Click Connect.

  6. Click the MBeans tab to display the MBeans.

The next sections describe and illustrate the EM4J MBeans.

BalloonConfig

The attributes of the BalloonConfig MBean report whether the prerequisites for EM4J are met. If all three attributes are true, EM4J is enabled in the VM. If any of the three is false, EM4J is disabled. The other EM4J MBeans do not exist unless these attributes are true. If ballooning does not occur in a VM when expected, you can check this MBean first to see if misconfiguration is the reason.

Table 13. Attributes of the com.springsource.em4j.BalloonConfig MBean

AttributeDescription
GuestToolsInstalledThis value is true if the VMware Tools are installed in the VM.
EsxVersionCompatibleThis value is true if the VM is running on an EM4J-capable ESXi host. Hosts running ESXi 5.0 are compatible with EM4J.
VmxOptionSetThis value is true if the sched.mem.pshare.guestHintsSyncEnable parameter is set to true in the VM's .vmx file.

VmBalloonState

The VmBalloonState MBean reports the actual and target balloon sizes for the entire VM. This is the same balloon data reported in the vSphere Client.

Table 14. Attributes of the com.springsource.jmx.VmBalloonState MBean

AttributeDescription
BalloonSizeThe composite size of all EM4J balloons in the VM.
BalloonTargetThe ESXi balloon target for this VM.

When an attribute has a numerical value, in JConsole you can double-click the value to begin graphing the value over time, as shown in the following illustration.

JvmBalloonState

The JvmBalloonState MBean reports information about the potential size of the balloon in the JVM. The potential size is the total size of all of the objects in the heap owned by EM4J. Each of these objects can form part of the balloon in the JVM. The potential size can be larger than the balloon target, in which case EM4J maintains objects that are not part of the balloon. When the balloon target drops, the excess objects are not immediately released because recreating them is unnecessarily expensive.

Table 15. Attributes of the com.springsource.jmx.JvmBalloonState MBean

AttributeDescription
MaxPotentialBalloonSizeThe maximum theoretically possible balloon size for the JVM. It is a percentage of the tenured part of the Java heap.
PotentialBalloonSizeTotalThe total size of all objects in the heap owned by EM4J.
PotentialBalloonSizeTenuredThe total size of all objects owned by EM4J in the tenured portion of the heap. Balloon objects are created in the Eden generation and become tenured soon after. The objects are not useful for ballooning until they have been tenured.

BalloonInternals

The attributes of the BalloonInternals MBean report the composition of heap memory allocated for ballooning by reference type, as well as the number of bytes locked. Potential sizes are the numbers of bytes of heap memory allocated and potentially available to satisfy the ESX balloon target for the VM. Objects allocated with weak or soft references allow the Java application to reclaim memory from the pool allocated for the balloon, if needed.

Table 16. Attributes of the com.springsource.balloon.jmx.BalloonInternals MBean

AttributeDescription
PotentialBalloonSizeHardThe total of the sizes of strongly referenced balloon objects.
PotentialBalloonSizeSoftThe total of the sizes of softly referenced balloon objects in the heap.
PotentialBalloonSizeWeakThe total of the sizes of weakly referenced balloon objects.
LockedBalloonBytesThe number of locked bytes in balloon; this is memory reclaimed by ESX.
TenuredBalloonBytesPerSecThe rate at which balloon bytes are tenured.