Chat now with support
Chat with Support

Foglight for Java EE Technologies 5.9.13 - Installation Guide

Installing and Configuring Foglight for Java EE Technologies Integrating with JBoss Integrating with Apache Tomcat Integrating with WebLogic Domain Startup Scripts Integrating with WebSphere Integrating with WebSphere Liberty Integrating with Oracle AS Integrating with Spring Boot for Embedded Tomcat 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 Installation Java EE Integration Configuration FAQ and Troubleshooting Manually Integrating Application Server Appendix A: Java EE Application Methods AppendixB: Managing Permissions for the Java EE Integration Agent

Manual integration with Tomcat

Manual integration with Tomcat

This section contains instructions for integrating the Java EE agent with a Tomcat Application Server 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 for the target system:

•
Integrating with Tomcat on UNIX
•
Integrating with Tomcat on Windows

Integrating with Tomcat on UNIX

The following exceptions are not mutually exclusive. If all exceptions apply to your environment, complete all of the following exceptions.

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. Sometimes, you must modify all 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 do 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. Sometimes, you must modify all these commands.
•
If you want to set preinstrumentor 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 preinstrumentor to 256MB, 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
Complete 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 change the following:
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 started using the modified script.
8
Use the modified script to start 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.

Integrating with Tomcat on Windows

Integrating with Tomcat on Windows

Follow these instructions to integrate Tomcat with Foglight for Java EE Technologies by modifying your Tomcat startup script.

Review the following exception before you configure your server. If this exception applies to your environment, complete these instructions.

Exception list — Windows®
•
If you want to set preinstrumentor 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 256MB, 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
Complete 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 update the script.
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 started using the modified script.
8
Use the modified script to start 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, or you have set the Startup mode to jvm and Java to Use Default, complete the following procedure after an installation-only setup.

To manually integrate a Tomcat Windows® Service:
1
Complete 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:\Quest Software 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 that the Tomcat service uses. 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 that 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 that the Tomcat Windows Service uses is changed (for example, by installing an updated version of the JRE or JDK on the host), this manual integration must be done again. If Foglight for Java EE Technologies is updated on the Tomcat host, this manual integration must be done again to take advantage of the new release.
Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating