Foglight for Java EE Technologies 5.9.7.5


	NOTE: Foglight for Java EE Technologies version 5.9.x is the last major release that supports JBoss AS 4.2. Support for this versions of JBoss will be discontinued after this release.

To allow the Java EE agent to collect JTA statistics:

Locate the jbossjta-properties.xml file in your JBoss server/<profile>/conf directory and open it in a text editor.

Add the following line to the <properties> element.

Restart your JBoss application server.

Running JBoss with Jetty

Jetty is a pure Java-based HTTP server and servlet container (application server). If you are running JBoss with Jetty, you must make the following changes to the property file agent_type_jboss-<version>.config before you start recording.


	IMPORTANT: Foglight for Java EE Technologies version 5.9.x is the last major release that supports JBoss AS 4.2 and 5.0, and JBoss EAP 4.3. Support for these versions of JBoss will be discontinued after this release.

The following table lists the <version> names:

Table 1. Application Server version names.
Application Server	Version
Application Server 4.2.[0-3]	agent/java/plugins/jboss-420.config
Application Server 5.0.[0-1] or 5.1.0	agent/java/plugins/jboss-5.config
Application Server 6.0.0 or 6.1.0	agent/java/plugins/jboss-6.config
Application Server 7.0.[0-2]	agent/java/plugins/jboss-7.config
EAP 6	agent/java/plugins/jboss-eap-6.config

To edit the agent .config file:

On the navigation panel, under Dashboards, click Application Servers > Administration > Application Servers Administration.

On the Application Servers Administration dashboard, click Java Administration.

On the Java Administration page, click the Agent Configurations tab.

In the Agent Configuration view, click Advanced Configurations.

The Advanced Configuration view opens.

Select the version of the Java EE agent that you want to edit. Click Version x.x.x to open a list of compatible versions.

Click the name of the agent/java/plugins/jboss-<version>.config for the JBoss version you want to edit, and select Edit.


	TIP: Click Show fully qualified names to see the directory location for the files. Type all or part of the file name in the Search box (for example, jboss-) to locate the file.

In the text editor, scroll down to locate and comment out the following line:

"com.quest.pas.agent.plugin.instrumentor.method.ServletInstrumentor",

Uncomment the following lines:

#"com.quest.pas.agent.plugin.instrumentor.method.HttpServletInstrumentor",
#"com.quest.pas.agent.plugin.instrumentor.ServletRequestInstrumentor",

Click Save.

Restart your application server.

Integrating a Java Service Wrapper Windows Service with a Java EE Agent

Foglight for Java EE Technologies supports the use of Windows Services configured using the Java Service Wrapper (JSW) application by Tanuki Software.

The JSW uses configuration files to control how your Java application is started and stopped as a Windows Service. To integrate the Java EE agent with your JSW, the JDK must be pre-instrumented (using the Java EE Integration Agent) and then the JSW configuration file needs to be manually modified to include Java EE agent configuration settings.

To integrate the Java Server Wrapper with a Java EE agent:

Create an installation, as described in Creating a Generic Installation for Manual Java EE Agent Integration .

After the generic installation is complete, a new file appears in the following directory on the machine where you ran the pre-instrumentation.

Windows: <VERSIONED_SUBDIRECTORY>\bootstrap\<INTEGRATIONID>

Unix: <VERSIONED_SUBDIRECTORY>/bootstrap/<INTEGRATIONID>

You can find the <INTEGRATIONID> in the file created by the Java EE Integration Agent in step 1.

Run the integration bat/sh file that was created by the manual installation.

Open the JSW configuration file in a text editor, and add the following code before the first wrapper.java.additional code:

#include <INSTALLATION DIRECTORY>\jee_builds.properties

#set.JAVA_HOME=<JVMPath>

set.QUEST_INTEGRATIONID=<INTEGRATIONID>

set.PERFORMASURE_BOOTSTRAP=-Xbootclasspath/p:%QUEST_AGENT_HOME%\bootstrap\%QUEST_INTEGRATIONID%\<BOOTSTRAP.JAR FILENAME>

set.PERFORMASURE_JAVAAGENT=-javaagent:%QUEST_AGENT_HOME%\lib\performasure-agent.jar

Replace <INSTALLATION DIRECTORY> with the absolute path of the Installation Directory. This can be found on the Installations tab of the Java Administration page (accessible from the Applications Servers Administration dashboard). 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.

If set.JAVA_HOME is not specified earlier in the JSW configuration file, uncomment the second line in the code block above and set <JVMPath> to the absolute path for the JVM used by the service.

For example: set.JAVA_HOME=C:\work\jvms\jdk1.5.0_12

Or, if the path is set in a different variable, such as JRE_HOME:
set.JAVA_HOME=%JRE_HOME%

Replace <INTEGRATIONID> with the value determined in step 2.

Replace <BOOTSTRAP .JAR FILENAME> with the file name of the bootstrap JAR file created in the <VERSIONED_SUBDIRECTORY>/bootstrap/<INTEGRATIONID> directory by the pre-instrumentation task in step 1.

In the JSW configuration file, add the following code after the last existing wrapper.java.additional entry:

wrapper.java.additional.<N>=%QUEST_INTEGRATIONID%

wrapper.java.additional.<N>=%PERFORMASURE_JAVAAGENT%

wrapper.java.additional.<N>=%PERFORMASURE_BOOTSTRAP%

and replace <N> with incremented numbers starting after your highest wrapper.java.additional number.

Save your JSW configuration file and then restart your JSW service.

Integrating with Tomcat

You can use the application server agent setup wizard to configure and integrate the Java EE agent and the Java EE Integration Agent with Tomcat Catalina startup scripts or with Tomcat running as a Windows Service. You must supply the Catalina Home directory or the Windows Service name for one or more application servers with which you want to integrate. Optionally, you can also specify pre-instrumentation options and agent options.

Before You Begin

For most configurations of a Tomcat sever running as a Windows Service, the Java EE Integration Agent automatically integrates the Java EE agent. Read the Important note below to determine if you are required to complete additional steps to integrate the Java EE agent with a Tomcat server running as a Windows Service.

If you are not required to perform the additional steps, complete the integration procedure (Integrating with Tomcat ), then restart your Tomcat application server. No other steps are required.

IMPORTANT: If you are using one of the following configurations, you are required to perform the integration manually. Additional steps are required.

•

On 32-bit or 64-bit Windows: Startup mode is set to Java and you have not specified a Java home using the JavaHome command line option.

•

On 64-bit Windows: Startup mode is set to jvm and the Use Default check box is selected.If you are using one of these configurations, complete the following procedure Configuring a Tomcat Windows Service that Requires Manual Integration .

•

Best Practices:We recommend that you explicitly set the Java home or the Java Virtual Machine when setting up a Tomcat application server that is running as a Windows Service. This prevents the Tomcat server from running with an unexpected JRE and makes the integration easier.

To integrate with Tomcat on Solaris, Linux, HP-UX, or AIX, or on Windows:

On the navigation panel, under Dashboards, click Application Servers > Administration > Application Servers Administration.

On the Application Servers Administration dashboard, in the Monitoring Agents section, click Setup agents.

In the menu that opens, select Java. The Java - Setup New Application Server Integration wizard opens.

On the Setup Options page, select the type of integration. This example describes how to Setup a new application server integration (the default selection).


	TIP: For other integration methods, Reusing a Previous Integration Configuration .

On the New Integration — Type page, select the type of Java application server you want to integrate with. In this case, select Tomcat on Solaris, Linux, HP-UX, or AIX, or Tomcat on Windows.

The wizard refreshes, providing the option to select the Tomcat application server startup method.

Select Catalina Scripts to integrate with Tomcat catalina.sh or catalina.bat startup scripts.

Select Windows Service to instrument Tomcat (procrun) Windows Services.


	NOTE: If for any reason you need to perform a manual integration, see Manually Integrating with Tomcat .

Click Next.

On the New Integration — Details page, provide the details required for integrating with your Tomcat server, including command-line options.

Type or select the absolute path to the Catalina startup script in the Catalina Home box.

Type the Windows Service name in the Service Name box.


	IMPORTANT: You must have a Windows Service defined to proceed with this type of integration. If you do not yet have a Windows Service defined, you should first install your Tomcat server to run as a Windows Service.

Optional — If your application server uses startup scripts with customized names, click the arrow beside Other Options to open a list of script paths and names. Type the custom names in the appropriate boxes.


	NOTE: Always use forward slashes to separate directory names, regardless of whether the application server is running on Windows or UNIX.

Optional — Click the arrow beside Command Line Options to show the agent and pre-instrumentor option boxes. Use these boxes to provide command-line parameters for the agent or pre-instrumentor.

•

To add agent options, type them in the Agent Options box.


	TIP: If you need to add more than one option to the Agent Options, separate them with spaces. Do not use quotes.

•

To add pre-instrumentation options, type them in the pre-instrumentor Options box.

To set pre-instrumentor options specific to the JVM you are running: type the desired VM options, separated by spaces, in the pre-instrumentor Options box.

For example, to set the memory limit for the pre-instrumentor to 256 MB, type the following: ‑Xmx256m


	NOTE: If you need to add more than one option to the pre-instrumentor Options, separate them with spaces. Do not use quotes.


	TIP: For information about pre-instrumentation, see Configuring Java Homes pre-instrumentation .

Click Next.

On the Nexus Connection page, select or create the connection that the agent should use to locate and communicate with a Nexus.


	TIP: For more information about the Nexus, see Understanding the Nexus and Agent-Nexus Connections .

If you are using the default Nexus on the embedded Agent Manager, or if you have created a single remote Nexus, a default Nexus Connection is created and pre-selected for you.

Otherwise, you must select or define at least one Nexus connection. For more information, see Creating or Editing Agent-Nexus Connection Settings.

Click Next.

On the Logging page, select or create a logging configuration to control how logs are written, including retention policies and rollovers.

•

Select an existing log configuration from the list. The default log provides a basic log configuration that you can use to get started.

•

Click New log configuration. The New Log Configuration dialog box opens.


	TIP: If you are uncertain about how to adjust these settings, click Help for an overview of log targets and their purposes. For details, see Creating or Editing Logging Properties .

Click Next.

On the Integration Hosts page, select the host where Tomcat is installed. By default, only eligible hosts (that is, hosts that have an active Foglight Agent Manager of a compatible version installed and running) are listed.

Select the host and click Next.

On the Agent Configuration page, select the configuration that the agent will use. This agent configuration defines the requests to monitor and collect details.


	TIP: You can create new agent configurations or edit existing ones from the Java Administration dashboard. For more information, see Managing Java EE Agent Configurations.

Select a configuration and click Next.

On the Installation Directory page, define the location for the directory that contains all installation components and log files. To accept the default directory, leave the Directory name box blank.