Installing EM4J with Apache Tomcat

Products

• VMware Tanzu tc Server

Environment

Resolution

Downloading the Helper Scripts

Download em4j-for-tomcat.zip (attached to this article) and extract the contents to your computer. The archive contains four files:

• copy-em4j-to-tomcat.sh
• logging-fragment.properties
• setenv.sh
• readme.txt

These files are explained later in this document. If you require any additional clarification, see the readme.txt file included in the archive.
 

Installing Apache Tomcat

If you have not already done so, install Apache Tomcat 6.0.x or 7.0.x. VMware recommends using a version at or greater than 6.0.35 or 7.0.23.

Note the path to your Tomcat installation as this is required later.
 

Installing EM4J

The downloaded archive contains the script copy-em4j-to-tomcat.sh. This is an automated script that copies the EM4J components from an existing tc Server 2.8 installation and installs them into your Apache Tomcat instance.

Note: When run, the copy-em4j-to-tomcat.sh script modifies your existing Tomcat installation; create a backup of your Tomcat instance prior to running the script.

These steps guide you through configuring and running this script:
 

1. Open a terminal and cd to the directory where you extracted the copy-em4j-to-tomcat.sh script.
    
2. If necessary, set the execute permission on the copy script:
   
   chmod a+x copy-em4j-to-tomcat.sh
    
3. Edit the copy-em4j-to-tomcat.sh script. Instructions for editing the script are included as comments in the script.
   
   You must edit these two variables:
   • TCS_HOME: Set to the full path that identifies your existing tc Server 2.8.x installation.
   • CATALINA_HOME: Set to the full path that identifies your Apache Tomcat installation.
      
4. Run the copy-em4j-to-tomcat.sh script. The script attempts to verify that TCS_HOME and CATALINA_HOME point to valid tc Server and Apache Tomcat installations. If any errors are generated during the script run, ensure that you have correctly configured the script in step three.
    
5. When the copy-em4j-to-tomcat.sh script has run, in addition to installing EM4J, it also installs a new bin/setenv.sh script and modifies the conf/logging.properties file. Review both of these files to examine the settings that were added.
   
   Note: When the script runs, it backs up and overwrites the bin/setenv.sh script. You are responsible for manually migrating any settings from the original (now bin/setenv.sh.original) script to the current (bin/setenv.sh) script. 

Before starting Apache Tomcat

Before you start Apache Tomcat:
 

1. Open the bin/setenv.sh file in your Apache Tomcat installation.
    
2. Ensure there is enough maximum heap specified with the -Xmx argument to accommodate application data and balloon objects.
    
3. Ensure that the remote JMX options, particularly the JMX port, are set appropriately for your Tomcat server. The EM4J CGC, if configured, uses this remote JMX port to report Java memory balloon metrics.

 

Enabling EM4J in the virtual machine

After EM4J is installed, you must enable its use at the virtual machine level.

To enable EM4J at the virtual machine level:
 

1. Shut down the virtual machine.
    
2. Modify the virtual machine's configuration (the .vmx properties) and add the sched.mem.pshare.guestHintsSyncEnable property, and set it to true.
   
   Note: You cannot add the sched.mem.pshare.guestHintsSyncEnable property while the virtual machine is running.

For more information on enabling EM4J, see Enable EM4J in the Virtual Machine in the vFabric tc Server Documentation.
 

Running Apache Tomcat

At this point, EM4J is installed. You can now start the Apache Tomcat server. If everything is working correctly, your applications are accessible and you see these three lines in your logs/catalina.out file:

EM4J agent starting...
EM4J is now running on a supported version of ESX
EM4J 1.2.0 agent initialized

If you experience problems during start-up, review the logs directory for hints at the issue.