Foglight for Java EE Technologies 5.9.11

JBoss AS 6.x and earlier: <jboss-home>\bin\run.bat (Windows®) or <jboss-home>/bin/run.sh (UNIX®)
Wildfly, JBoss EAP, and JBoss AS 7.1.x: <jboss-home>\bin\standalone.bat (Windows®) or <jboss-home>/bin/standalone.sh (UNIX®)

Domain mode:

Wildfly, JBoss AS, and JBoss EAP: <jboss-home>\bin\domain.bat (Windows®) or <jboss-home>/bin/domain.sh (UNIX®)

Complete a Generic installation only on Windows or a Generic installation only on Solaris, Linux, HP-UX, or AIX, as described in Creating a Generic Installation for Manual Java EE Agent Integration .

Copy the following block of code into your server startup script. Insert the block just before the Java command line that starts the Wildfly or JBoss application server, but after any commands that set or modify the JAVA_HOME and JAVA_OPTS environment variables.

Windows (standalone mode):

set QUEST_DEPLOYMENT_DIRECTORY=* SET JavaEE Installation directory *
set QUEST_JAVA_ENV_OPTS=JBOSS:SERVER:JAVA_OPTS
call "%QUEST_DEPLOYMENT_DIRECTORY:"=%\<integrate.cmd>" %*
if ERRORLEVEL 1 echo Java EE agent NOT enabled

Windows (domain mode):

set QUEST_DEPLOYMENT_DIRECTORY=* SET JavaEE Installation directory *
set QUEST_JAVA_ENV_OPTS=JBOSS:DOMAIN
call "%QUEST_DEPLOYMENT_DIRECTORY:"=%\<integrate.cmd>" %*
if ERRORLEVEL 1 echo Java EE agent NOT enabled

UNIX (standalone mode):

QUEST_DEPLOYMENT_DIRECTORY=* SET JavaEE Installation directory *
if [ -f "$QUEST_DEPLOYMENT_DIRECTORY/<integrate.sh>" ]
then

QUEST_JAVA_ENV_OPTS=JBOSS:SERVER:JAVA_OPTS
. "$QUEST_DEPLOYMENT_DIRECTORY/<integrate.sh>"

else

echo Java EE agent NOT enabled

UNIX (domain mode):

QUEST_DEPLOYMENT_DIRECTORY=* SET JavaEE Installation directory *
if [ -f "$QUEST_DEPLOYMENT_DIRECTORY/<integrate.sh>" ]
then

QUEST_JAVA_ENV_OPTS=JBOSS:DOMAIN
. "$QUEST_DEPLOYMENT_DIRECTORY/<integrate.sh>"

else

echo Java EE agent NOT enabled

Set <integrate.cmd/sh> 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.

Set the QUEST_DEPLOYMENT_DIRECTORY variable to the Installation Directory specified by the Java EE Integration Agent instance activated on this host. In Unix, quote this path if it contains spaces.

Ensure that your environment does not meet any of the exceptions in the Exception list and then save the new script.

If it is not already running, start the Management Server. The instrumented Wildfly or JBoss application server attempts to connect to Foglight for Java EE Technologies when started using the new script.

Start the Wildfly or JBoss application server using the new script.

Foglight for Java EE Technologies starts a Java EE agent for each instrumented server. When the Java EE agent connects to the Management Server, the Management Server console confirms that a Java EE agent has connected by displaying a message , for example:

<timestamp> INFO Accepted connection from agent “<agent name> (JBoss)”, (JBoss <version>) on host: <hostname>

In addition, the log file for the Java EE agent contains an INFO message stating that it has connected to the Management Server.

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:

Make a copy of your original catalina.sh script.

By default, you can find this script in the <tomcat_home>/bin/ directory.

Complete a Generic installation only on Windows, as described in Creating a Generic Installation for Manual Java EE Agent Integration .

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

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.

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.

Save the startup script.

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.

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

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:

Make a copy of the catalina.bat script.

By default, you can find this script in the <tomcat_home>\bin\ directory.

Complete a Generic installation only on Windows, as described in Creating a Generic Installation for Manual Java EE Agent Integration .

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

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.

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.