vFabric Elastic Memory for Java (EM4J) 1.2 Release Notes

vFabric EM4J 1.2 | 16 OCT 2012, updated 6 DEC 2012

What's in the Release Notes

These release notes cover the following topics:

What's New in vFabric EM4J 1.2

The VMware® vFabric™ Elastic Memory for Java (EM4J) 1.2 release brings vSphere administrators improved visibility into memory usage on ESXi virtual machines running Java workloads. The EM4J Console UI displays detailed graphs of virtual machine and Java heap memory usage over time, eliminating the guess work in right-sizing virtual memory and Java heap memory. This release includes usability enhancements to the EM4J plug-in for the vSphere Web Client (also known as the Console UI) and improved memory usage statistics from the Console Guest Collector (CGC).

The helper scripts that enable the EM4J agent with Apache Tomcat are updated to use the EM4J 1.2.0 agent. See Knowledge Base Article 2011244 and Knowledge Base Article 2011243 for information about using this feature. The setenv.sh script selects the correct shared library for the machine architecture automatically, so it is no longer necessary to edit the script to specify the library.

The EM4J 1.2 release includes performance enhancements and bug fixes to all components, including the EM4J ballooning agent, CGC, Console UI, and documentation.

EM4J Console UI 1.2.0 Update

The EM4J 1.2 December 6, 2012 update adds a vSphere 5.1-compatible EM4J Console UI plug-in for the vSphere Web Client. The product download page now offers two ZIP files, one for vSphere 5.0 and another for vSphere 5.1. You must install the correct plug-in for your version of vSphere.

See Install the vSphere Web Client EM4J Plug-in for updated installation instructions. See vSphere 5.1: Monitoring Memory with the vSphere Web Client for updated instructions for the new plug-in.

Known Issues

The following issue has been identified in this release of vFabric EM4J.

Large memory pages may not be correctly detected (JEM-470)

The OS manages large page memory separately from regular free memory. Memory is allocated to the large page pool at startup and is available only to applications authorized to use it. A JVM must specifically request large page memory by including the -XX:+UseLargePages command-line option.

The EM4J plug-in for the vSphere Web Console displays large page memory in the "Other memory" category until it is allocated to JVM heap. This behavior is described in the Large Pages section of the EM4J user guide. When a JVM configured to use large pages starts up, the graph on the Workloads > History tab shows the Other memory line (green) falling as the Committed heap memory line (brown) rises, indicating that the JVM takes heap memory from the large page memory pool. The following graph is an example of how this might appear in the vSphere Web Console.

Large page memory in the EM4J Console UI

A graph displays unexpected results for large pages if a JVM configured to use large pages runs as the root user. A Console Guest Collector (CGC) running as a non-root user cannot detect the large page mapping and reports incorrect data to the Console UI. The following graph is an example of how this situation might appear in the Console UI.

CGC fails to detect large pages

The large page memory pool is correctly shown in the Other memory category, but when the JVM runs, the CGC reports memory taken from free memory instead of the large memory pool. Therefore, the green line stays relatively constant and the Potential Heap Size line (light blue) rises by the amount of heap consumed, exceeding the vRAM Size line (dark blue).

It is best practice to run tc Server as an unprivileged user, so this problem should be rare. If it is necessary to run the JVM as root, the problem can be avoided by also running the CGC as root.

Resolved Issues

The following issues have been resolved in this release of vFabric EM4J.

Issue Description
JEM-189 The CGC now prints a NullPointerException and stack trace when a process is not found.
JEM-332 When the user resets historical data, the Console UI should wait for the CGC to reset the data on the VM before refreshing the graph. The UI now waits for up to approximately 15 seconds for the data to reset before refreshing the graph.
JEM-338 The cgc.sh script has some misleading behavior and feedback. The CGC script now has a --help option and a new, service-like command syntax.
JEM-348 In the Console UI, the sequence in which graph lines are drawn has changed to prevent confusion when the balloon size is 0 and the vRAM and Effective vRAM lines coincide. Alerts for Effective Memory violations are now issued only when the balloon size is greater than 0.
JEM-381 An Apache Tomcat process was identified in the EM4J Console UI as "tc Server, Tomcat". vFabric tc Server and Apache Tomcat processes are now identified with the string "Apache Tomcat-based Server".
JEM-384 The release 1.1 Console "EM4J Agent Enabled" field displays "No" when JMX is not configured, although the agent may actually be active in the JVM. In release 1.2, the field displays Yes, No, or Unavailable. If the value is No or Unavailable, messages in the alerts pane provide details of the problem.
JEM-387 The Console UI no longer displays an incorrect roll-up status for a workload if the CGC or Agent have any error or warning messages.
JEM-397 The Console UI now recognizes the special "cleared" value the CGC saves when it exits.
JEM-401 The JMX committed heap value now equates to committed pages.
JEM-404 The CSV export function in the Console UI now outputs EM4J Balloon history instead of Guest Balloon history.
JEM-411 When a Java process with no main class runs on a VM, selecting the Workloads tab in the Console UI no longer displays a DataRequestEvent error.
JEM-412 Regression no longer occurs during recording of historic data to file.
JEM-415 CGC heap size estimation, using /proc -Xmx, was broken with recent version of Java 7 due to a change in heap mappings. This issue is resolved.
JEM-419 JMX options on the command line conflicting with options in the tc Server configuration caused incorrect graphing in the Console UI. This issue is resolved.
JEM-425 The Console UI graphs exhibited spiking behavior when a JVM started or stopped due to the timing of CGC samples taken during memory allocation and deallocation. This has been resolved.
JEM-435 In the Console UI, the Other Memory, Committed Size, and Balloon Size for EM4J ballooning now displays correctly.
JEM-436 On the Console UI Workloads tab, when History graph lines are highlighted or greyed out using the legend, the graph now updates correctly when switching to another VM.
JEM-443 The CGC no longer exits due to unexpected failure when writing to Guest Variables.
JEM-478 The EM4J Agent now passes the current EM4J version when registering for a vFabric license.