Install the vSphere Web Client EM4J Plug-in

To monitor virtual machine memory and Java workloads in the vSphere Web Client, make sure you have installed and configured the following components.

Prerequisites

vCenter Server 5.0 or 5.1. See Installing vCenter Server.
vSphere Web Client. See lnstall and Start the vSphere Web Client.
vSphere Web Client EM4J plug-in. See Download and Install the vSphere Web Client EM4J Plug-in.
Virtual machines, VM Version 7 or higher, with VMware Tools installed.
To monitor detailed Java heap usage on a per-JVM basis, the sched.mem.pshare.guestHintsSyncEnable VM configuration property must be set to true, and Java must be started with the required EM4J and JMX properties specified on the java command line. See Enable EM4J in the Virtual Machine and Setting the JVM Properties.
CGC installed and running. See Running the Console Guest Collector.

Download and Install the vSphere Web Client EM4J Plug-in

You can install the EM4J plug-in in an instance of the vSphere Web client running on Windows or in the VMware vCenter Server Appliance, a Linux virtual machine. The plug-in version depends on whether you are using vCenter Server 5.0 or vCenter Server 5.1.

Procedure

Browse to the VMware Downloads Web page at http://downloads.vmware.com.
Under Application Platform, click VMware vFabric.
Click the Driver & Tools tab.
Click View Download next to "VMware vFabric EM4J Console UI 1.2.0".
In the Product Downloads section, locate the file that corresponds to your vSphere version, either 5.0 or 5.1, and click Download Manager or Manually Download.
When prompted, log in with your VMware account and accept the license agreement.
Save the file to your computer. If you are installing the plug-in in an instance of the vSphere Web client running on Windows, proceed to step 9.
If you are using the vCenter Server Appliance, copy the plug-in ZIP file to the server. For example:
```
% scp em4j-plugin-1.2-vsphere51-bin.zip root@<appliance-ip-address>:/tmp
```
Then log in to the appliance as root to complete the remaining steps.
Change to the vSphere Web Client plugin-packages directory. If you installed vSphere Web Client on Windows in the default location, use the following command:
```
> cd C:\Program Files\VMware\Infrastructure\vSphere Web Client\plugin-packages
```
If you are using the vCenter Server Appliance, use the following command:
```
# cd /usr/lib/vmware-vsphere-client/plugin-packages
```
Check whether the em4j-client directory exists. If it exists, delete it and all of its contents.
On Windows:
```
> dir
> del /S/Q em4j-client
```
On the vCenter Server Appliance:
```
# ls
# rm -rf em4j-client
```
Create the em4j-client directory.
On Windows:
```
> mkdir em4j-client
```
On the vCenter Server Appliance:
```
# mkdir em4j-client
```
On Windows, double-click the EM4J Console UI plug-in file in Windows Explorer and extract it into the em4j-client directory.
On the vCenter Server Appliance, use the unzip command to extract the plug-in, for example:
```
# unzip -d /usr/lib/vmware-vsphere-client/plugin-packages/em4j-client \
  /tmp/em4j-plugin-1.2-vsphere51-bin.zip
```
You should now have the following directory structure in the VMware vSphere client directory:
```
plugin-packages/
    em4j-client/
        help/
        legal/
        pluginPackage.xml
        plugins/
```
Restart the vSphere Web Client.
On Windows:
- Choose Start > Control Panel > Administrative Tools > Services.
- Right-click vSphere Web Client and choose Restart.
On vCenter Server Appliance 5.0:
- Browse to the vCenter Service Appliance administration web page, for example https://<appliance-ip-address>:5480, and log in as root.
- Click the Services tab.
- Click Stop vSphere Web Client and wait for the vSphere Web Client Status to changed to Stopped.
- Click Start vSphere Web Client.
On vCenter Server Appliance 5.1:
- Browse to the vCenter Server Appliance administration web page, for example https://<appliance-ip-address>:5480, and log in as root.
- In the Services section, click the Stop button next to "vSphere Web Client" and wait for the status to change to "Stopped".
- Click the Start button next to "vSphere Web Client".

Setting JVM System Properties

If you create a tc Runtime instance using the elastic-memory template, the system properties that enable EM4J are added to the java command line for you. The EM4J MBeans in the EM4J-enabled JVM provide detailed information about Java heap memory usage, including the state of the EM4J balloon. To make this information available to the vSphere Web Client, the Console Guest Collector (CGC) looks for a set of JMX properties on the Java command line and, if found, uses them to establish a JMX connection to the JVM.

If the JMX properties are missing or the connection cannot be established, the vSphere Web Client displays an alert to make you aware that the CGC could not make a JMX connection. Without JMX, the CGC can only monitor Java memory at the VM level, tracking committed heap memory and maximum heap size (-Xmx). This may be sufficient information if your goal is to use the vSphere Web Client to help size VMs with Java workloads. But for more insight into the Java heap and the EM4J balloon, configure the JVM with the JMX properties described in this section.

Note

The CGC connects to a JVM on localhost using JMX and is configured by the system properties specified to the Java command. Each JVM on the virtual machine must be configured with a unique JMX port number. The CGC does not support authenticated or encrypted JMX connections, so unless the network is secure, setting thecom.sun.management.jmxremote.* properties is not recommended.

A tc Server instance is also configured with a JmxSocketListener in the conf/server.xml configuration file. This is a different listener than the one specified on the Java command line for the CGC and should be configured with a different, unique port number. The JmxSocketListener provides secure access to the JMX service with support for authentication and SSL, and is used by the Hyperic agent and other JMX clients to monitor and manage the tc Server instance.

The following table lists the command line JVM properties required to enable EM4J and allow the CGC to connect to the JVM with JMX.

Table 2. EM4J Java System Properties

Property	Description
`-javaagent=/path/to/Balloon.jar`	Points to the Balloon.jar EM4J Java library, which can be found in the lib directory of the tc Runtime instance. This property is added for you when you create a tc Runtime instance using the `elastic-memory` template.
`-agentpath=/path/to/native/library`	Points to the native EM4J library, which is in an architecture-specific subdirectory of the `lib` directory in the tc Runtime instance directory. This property is added for you when you create a tc Runtime instance using the `elastic-memory` template.
`-Dcom.sun.management.jmxremote=true`	Enables JMX remote agent and local monitoring. You must manually add this property to the tc Runtime instance.
`-Dcom.sun.management.jmxremote.port=portno`	Creates a JMX connector listening on the specified port. You must manually add this property to the tc Runtime instance.
`-Dcom.sun.management.jmxremote.authenticate=false`	Disables authentication for JMX. The CGC does not support authenticated connections. You must manually add this property to the tc Runtime instance.
`-Dcom.sun.management.jmxremote.ssl=false`	Disables JMX monitoring via SSL. The CGC does not support SSL. You must manually add this property to the tc Runtime instance.

If you use the tcruntime-instance command with the elastic-memory template to create the tc Runtime instance, the -javaagent and -agentpath system properties are set up and the required Java and native libraries are copied into the tc Runtime instance.

For example, this command, executed in the tc Server installation directory, creates an EM4J-enabled tc Runtime instance named myInstance:

prompt$ ./tcruntime-instance.sh create myInstance -t elastic-memory

Once the tc Runtime instance is created, edit the $CATALINA_HOME/bin/setenv.sh file and add the JMX system properties to the JVM_OPTS variable:

Note

Lines are wrapped for readability.

The default JMX port is 6969; if you use 6969, when tc Server starts up an exception is written in the catalina.<date>.log file indicating that port 6969 is already in use. The exception does not affect the operation of JMX or the CGC, so it can be ignored. To prevent the message, specify a port other than 6969.

JVM_OPTS="-Dcom.sun.management.jmxremote=true 
          -Dcom.sun.management.jmxremote.port=6979 
          -Dcom.sun.management.jmxremote.authenticate=false 
          -Dcom.sun.management.jmxremote.ssl=false"

Disabling the vSphere Web Client EM4J Plug-in

You can disable the EM4J plug-in in the vSphere Web Client Plug-in Management console. The plug-in remains installed, but is inoperative. You can re-enable the plug-in later using a similar procedure.

Procedure

From the Applications menu, choose System Administration > Plug-in Management.
Right-click Elastic Memory for Java Client and choose Other > Disable from the context menu.
Click Yes. A Reload vSphere Web Client dialog box appears.
Click Yes.