The EM4J Java library,
Balloon.jar, includes four
MBeans you can access through JMX to view the state of EM4J in a
reports whether the prerequisites are met to enable EM4J in the VM.
Each of the MBean's attributes must be true for the other three EM4J
MBeans to be present.
provides balloon target and size information for the entire virtual
provides balloon information for the JVM in which the MBeans
provides information describing internal implementation details of the
heap objects owned by EM4J.
You can use vFabric Hyperic Server or JConsole, a JMX client included with the Java HotSpot JDK, to view the MBeans.
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.
In the Hyperic user interface, click the Resources tab.
Click the name of the platform (VM) where the target JVM is running.
Select Tools Menu > New Server.
In the Name field, enter a name for the JVM.
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.
In the Install Path field, enter the path to the Java installation directory.
Click OK. The server is added and a message appears:
This resource has not been configured. Please set it's
Click Configuration Properties.
In the jmx.url field, enter the JMX URL:
The JMX port,
6969 by default, is configured in
server.xml file for the tc Server.
In the jmx.username and
jmx.password fields enter the JMX
username and password. The defaults are
The JVMs you add appear in the Servers list on the Resources tab. Follow this procedure to view MBeans in the Hyperic user interface.
In the Hyperic user interface, click Resources.
Click the Servers link.
Click the name of the JVM you added.
Click the Views tab.
Click the JMX MBean Query button.
In the Object Name Pattern field, enter a query string like the following to select the EM4J MBeans:
Click Query MBeans.
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
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
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
admin, and the password is
Open a terminal window on the VM running the JVM you want to connect to.
jconsole with a command like the
In the New Connection window
select Remote Process and enter
port is the JMX management port,
Enter the JMX Username and
Password. The defaults are
Click the MBeans tab to display the MBeans.
The next sections describe and illustrate the EM4J MBeans.
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
|GuestToolsInstalled||This value is |
|EsxVersionCompatible||This value is true if the VM is running on an EM4J-capable ESXi host. Hosts running ESXi 5.0 are compatible with EM4J.|
|VmxOptionSet||This value is |
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
|BalloonSize||The composite size of all EM4J balloons in the VM.|
|BalloonTarget||The 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.
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
|MaxPotentialBalloonSize||The maximum theoretically possible balloon size for the JVM. It is a percentage of the tenured part of the Java heap.|
|PotentialBalloonSizeTotal||The total size of all objects in the heap owned by EM4J.|
|PotentialBalloonSizeTenured||The 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.|
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
|PotentialBalloonSizeHard||The total of the sizes of strongly referenced balloon objects.|
|PotentialBalloonSizeSoft||The total of the sizes of softly referenced balloon objects in the heap.|
|PotentialBalloonSizeWeak||The total of the sizes of weakly referenced balloon objects.|
|LockedBalloonBytes||The number of locked bytes in balloon; this is memory reclaimed by ESX.|
|TenuredBalloonBytesPerSec||The rate at which balloon bytes are tenured.|