Chat now with support
Chat with Support

Foglight for Java EE Technologies 5.9.7.5 - Installation Guide

Installing and Configuring Foglight for Java EE Technologies Integrating with JBoss Integrating with Tomcat Integrating with WebLogic Domain Startup Scripts Integrating with WebSphere Integrating with Oracle AS Creating a Generic Installation for Manual Java EE Agent Integration Managing Java EE Agent Installations, Integrations, and Configurations Managing Java EE Agent Configurations Managing Java EE Installations Foglight for Java EE Integration Configuration FAQ and Troubleshooting Performing Manual Application Server Integrations Appendix: Managing Permissions for the Java EE Integration Agent Appendix: Foglight for Java EE Application Methods

Manually Integrating with Tomcat

This section contains instructions for integrating the Java EE agent with a Tomcat Application Server versions 5.5 and 6.0 on Unix and Windows operating systems:
* 
TIP: Make a backup copy of your original Tomcat startup script before proceeding with the steps listed in this section.
The manual integration instructions are OS-specific. See either the Unix Integration Instructions or the Windows Integration Instructions as appropriate for the OS on the target system.

Unix Integration Instructions

The following exceptions are not mutually exclusive. If all apply to your environment, you must complete all exceptions listed below.
Exception List — Unix
•
If you have spaces in the Unix Installation directory path:
Edit the startup script and insert the following code in the Java command line before org.apache.catalina.startup.Bootstrap “$@” start:
"${PERFORMASURE_BOOTSTRAP}" "${PERFORMASURE_JAVA5}" ${PERFORMASURE_OPTIONS}
The catalina.sh script uses six different versions of the startup command line. In some cases, you must modify all of these scripts.
•
If either of the following conditions are true:
•
You are using JRockit
•
The Java command line includes
-Djava.endorsed.dirs=...<tomcat_home>\bin
Then this exception applies and you must perform the following:
Edit the startup script and insert the following code in the Java command line before org.apache.catalina.startup.Bootstrap “$@” start:
${PERFORMASURE_BOOTAGENT}
The catalina.sh script uses six different versions of the startup command lines. In some cases, you must modify all of these commands.
•
If you want to set pre-instrumentor options that are specific to the JVM you are running:
Set the environment variable QUEST_PREINST_OPTS with the desired VM options. The environment variable QUEST_PREINST_OPTS is passed to the Java EE Agent pre-instrumentor script.
For example, to set the memory limit for the pre-instrumentor to 256 MB, specify the following: QUEST_PREINST_OPTS="-Xms256m"
Integrating on a UNIX Operating System
To integrate the Java EE agent with Tomcat on Unix:
1
Make a copy of your original catalina.sh script.
By default, you can find this script in the <tomcat_home>/bin/ directory.
2
Perform a Generic installation only on Windows, as described in Creating a Generic Installation for Manual Java EE Agent Integration .
3
Open the catalina.sh script in a text editor and make the changes described in this step:
Immediately before the line:
if [ "$1" = "debug" ] ; then
Insert the following block of code:
# QUEST_PREINST_OPTS=* OPTIONAL pre-instrumentor Options *
# export QUEST_PREINST_OPTS
QUEST_DEPLOYMENT_DIRECTORY=* SET JavaEE Installation Directory *
if [ "$1" != "stop" ]; then
if [ -f "$QUEST_DEPLOYMENT_DIRECTORY/<integrate.sh>" ]; then
QUEST_JAVA_ENV_OPTS=TOMCAT
. "$QUEST_DEPLOYMENT_DIRECTORY/<integrate.sh>"
else
echo Java EE agent not enabled
fi
fi
4
Set <integrate.sh> to the name of the integration task you created in step 2. For example: integrate-Generic_installation_only_on_UNIX_Install_Configs_and_pre-instrument.cmd.
5
Set the QUEST_DEPLOYMENT_DIRECTORY variable to the Deployment Directory specified by the Java EE Integration Agent instance that is activated on this host.
* 
IMPORTANT: Enclose this path in double quotes if it contains spaces.
6
Save the startup script.
7
If it is not already running, start the Foglight Management Server. The instrumented Tomcat Server attempts to connect to the Foglight Management Server when the Tomcat Server is launched using the modified script.
8
Use the modified script to launch Tomcat.
The Foglight console confirms that a Tomcat Agent has connected by displaying a message similar to:
INFO Accepted connection from Tomcat Agent on <hostname>
In addition, the log file for the Tomcat Agent contains an INFO message stating that it has connected to the Foglight Management Server.
* 
IMPORTANT: By default, Agent log files are created in the logs subdirectory of the Foglight home directory on the Agent machine.

Windows Integration Instructions

Follow the instructions below to integrate Tomcat with Foglight by modifying your Tomcat startup script.
Review the exception listed below before you configure your server. If this exception applies to your environment, you must complete the instructions listed below.
Exception List — Windows
•
If you want to set pre-instrumentor options that are specific to the JVM you are running:
Set the environment variable QUEST_PREINST_OPTS with the desired VM options. The environment variable QUEST_PREINST_OPTS is passed to the Java EE agent pre-instrumentor script.
For example, to set the memory limit for the pre-instrumentor to 256 MB, specify the following: QUEST_PREINST_OPTS=-Xms256m.
Integrating on a Windows Operating System
To integrate the Java EE agent with Tomcat on Windows:
1
Make a copy of the catalina.bat script.
By default, you can find this script in the <tomcat_home>\bin\ directory.
2
Perform a Generic installation only on Windows, as described in Creating a Generic Installation for Manual Java EE Agent Integration .
3
Open the catalina.bat script in a text editor and make the changes described in this step:
Immediately before the line:
if ""%1"" == ""debug"" goto doDebug
Insert the following block of code:
@rem set QUEST_PREINST_OPT=* OPTIONAL pre-instrumentor Options *
set QUEST_DEPLOYMENT_DIRECTORY=* SET JavaEE Installation Directory *
if ""%1"" == ""debug"" set QUEST_JAVA_ENV_OPTS=TOMCAT
if ""%1"" == ""run"" set QUEST_JAVA_ENV_OPTS=TOMCAT
if ""%1"" == ""start"" set QUEST_JAVA_ENV_OPTS=TOMCAT
if defined QUEST_JAVA_ENV_OPTS (
call "%QUEST_DEPLOYMENT_DIRECTORY:"=%\<integrate.cmd>"
)
if ERRORLEVEL 1 echo Quest Agent NOT enabled for Tomcat server
4
Set <integrate.cmd> to the name of the integration task you created in step 2. For example: integrate-Generic_installation_only_on_Windows_Install_Configs_and_pre-instrument.cmd.
5
Set the QUEST_DEPLOYMENT_DIRECTORY variable to the Installation directory specified by the Java EE Integration Agent instance activated on this host.
* 
IMPORTANT: Do not place quotation marks around the directory name even if it contains spaces. Doing so causes a conflict with existing quotation marks in commands that use the QUEST_DEPLOYMENT_DIRECTORY variable.
6
Save the modified startup script.
7
If it is not already running, start the Foglight Management Server. The instrumented Tomcat Server attempts to connect to the Management Server when the Tomcat Server is launched using the modified script.
8
Use the modified script to launch Tomcat.
The Foglight console confirms that a Tomcat Agent has connected by displaying a message similar to:
INFO Accepted connection from Tomcat Agent on <hostname>
In addition, the log file for the Tomcat Agent contains an INFO message stating that it has connected to the Management Server.
* 
IMPORTANT: By default, agent log files are created in the logs subdirectory of the Foglight home directory on the agent machine.

Configuring a Tomcat Windows Service that Requires Manual Integration

If you have chosen not to specify the Java home, and/or you have set the Startup mode to jvm and Java to Use Default, you must complete the following procedure after performing an installation only setup.
To manually integrate a Tomcat Windows Service:
1
Perform a Generic installation only on Windows, as described in Creating a Generic Installation for Manual Java EE Agent Integration . Specify the JVM used by the service in the Java_Home box in the setup wizard.
The generic installation creates a bootstrap.jar file and an integrationid that are needed later in this integration procedure.
2
Set the following Java options:
a
In a command prompt, open the Tomcat installation bin directory.
b
Type ./tomcat#w.exe //ES//<WindowsServiceIDname>.
For example:
./tomcat5w.exe //ES//Tomcat_Toronto_Host3.
c
In the Apache Tomcat Properties dialog box, open the Java tab.
d
Add the following options to the end of the list of existing Java Options:
-Dquest.debug=0
-Dquest.integrationid=<INTEGRATIONID>
-Xbootclasspath/p:<VERSIONED_SUBDIRECTORY>\bootstrap\<INTEGRATIONID>\<BOOTSTRAP_FILENAME>.jar
-javaagent:<VERSIONED_SUBDIRECTORY>\lib\performasure-agent.jar
e
Replace <VERSIONED_SUBDIRECTORY> with the absolute path of the deployment directory and the current agent directory version.
Example of a <VERSIONED_SUBDIRECTORY>:
C:\Dell Inc.\Foglight for Java EE Technologies_Agent_Manager\agents\JavaEE\5.7.0-570-20101210-1400
The Installation Directory is specified in the Java EE Integration Agent Startup Parameters, which you can see in the Edit Properties interface. If the Installation Directory path is specified as a relative path, as it is by default, you may need to examine the agent machine to determine the absolute path.
* 
TIP: The current version of the subdirectory is indicated within the jee_builds.properties file. It is the value of the set.QUEST_AGENT_HOME parameter.This value already includes the installation directory. The version of the subdirectory portion is the last directory specified in the value.
f
Replace both instances of <INTEGRATIONID> with the integrationid produced in Step 1. The integrationid can be found in the integrate scripts generated by the generic installation, which are placed in the Installation Directory. Locate the scripts corresponding to your generic installation, open the .cmd script, and look for a command similar to the following:
@set QUEST_INTEGRATIONID=YourCustomizedId
where the word after the '=' is your integrationid. In this example, the integrationid is YourCustomizedId.
g
Replace <BOOTSTRAP_FILENAME> with the name of the pre-instrumentation .jar filename that was created in step 1. corresponds to the JRE/JDK used by the Tomcat service. This name can be found in your agent machine bootstrap directory, in the <VERSIONED_SUBDIRECTORY>.
Here is an example where <INTEGRATIONID>, <VERSIONED_SUBDIRECTORY> and <BOOTSTRAP_FILENAME> are updated:
-Dquest.debug=0
-Dquest.integrationid=KEo3JDr6ALaybTu
-Xbootclasspath/p:C:\Quest_Software\Foglight_Agent_Manager\agents\JavaEE\5.9.3-20130815-0923\bootstrap\KEo3JDr6ALaybTu\C--Program_Files_-x86--Java-jdk1.6.0_20.jar
-javaagent:C:\Quest_Software\Foglight_Agent_Manager\agents\JavaEE\5.9.3-20130815-0923\lib\performasure-agent.jar
h
Click OK to save the changes to the Windows Service made within tomcat#w.exe.
3
Ensure the Foglight Management Server is started and the Java EE agent is activated.
4
For the changes to take effect, stop and restart the Tomcat Windows Service.
* 
IMPORTANT: If the JVM used by the Tomcat Windows Service is changed (for example, by installing an updated version of the JRE or JDK on the host), this manual integration procedure must be performed again. If Foglight for Java EE Technologies is updated on the Tomcat host, this manual integration procedure must be performed again in order to take advantage of the new release.
Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating