Foglight for Java EE Technologies 5.9.13


	IMPORTANT: Foglight for Java EE Technologies version 5.9.11 is the last major release that supports JBoss AS (all versions), JBoss EAP 4.x, and JBoss EAP 5.x.

For an overview of the installation and integration process, see Installing the agents .

To integrate with JBoss on UNIX® or Windows®:


	IMPORTANT: Ensure that the target application server has an active Foglight Agent Manager of a compatible version installed and running.

On the navigation panel, under Dashboards, click 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 an integration configuration .

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

The wizard refreshes, indicating that it will use the JBoss Startup Scripts. This option integrates the JBoss run.bat or run.sh startup scripts.

Click Next.

On the New Integration — Details page, specify any additional information required to integrate with the application server.

Type or select the absolute path to the JBoss Home directory. This is the JBoss installation location on the remote file system.

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.

For example, if the JBoss .jar files are located in a lib/endorsed directory, add the following option in the Agent Options box:
‑Dquest.agent.instrument.bootstrap=true


	NOTE: 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 in the pre-instrumentor Options box.

For example, to set the memory limit for the pre-instrumentor to 256MB, 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 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, 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 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 monitored host where the JBoss application server 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 for the agent to use. This agent configuration defines the requests to monitor and collect details.


	TIP: You can create 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 empty.


	IMPORTANT: If you have previously configured the host for agent installation, the existing installation directory is used.

To specify a custom directory, type a path in the Directory name box.

Click Next.

On the Review page, verify the details of the integration.

By default, the instrumentation script is assigned a name based on the integration type. For example: JBoss on Windows: ServerRunScript. If you want to customize this name, type the new value in the Name box.

Click Finish.

The Application Servers Administration dashboard refreshes, and the integration task appears in the Task History list, where you can monitor its progress.

Restart your application server.

The agent starts collecting data after the application server has restarted and the agent is successfully integrated.

Next steps:

•

If you are running JBoss with Jetty, see Running JBoss with Jetty .

•

If you are integrating with the Java Service Wrapper, see Integrating a Java Service Wrapper Windows Service with a Java EE agent .

•

Use the Application Servers Monitor dashboard to view the application servers status. For more information about the Application Servers Monitor dashboard, see the Foglight for Application Servers User Guide.

•

If for any reason you need to manully integrate a JBoss agent, see JBoss remote agent integration from the command-line .

Running JBoss with Jetty

Jetty is a pure Java-based HTTP server and servlet container (application server). If you are running JBoss® with Jetty, 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.11 is the last major release that supports JBoss AS (all versions), JBoss EAP 4.x, and JBoss EAP 5.x.

The following table lists the <version> names:

Table 1. Application Server version names.
Application Server	Version
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.

On the Application Servers Administration dashboard, click the Java tab.

On the Java view, click the Agent Configurations tab.

In the Agent Configurations 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 filename 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 that the Java EE Integration Agent creates 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. The path 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 that the service uses.

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 filename 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 Apache Tomcat

Use the application server agent setup wizard to configure and integrate the Java EE agent and the Java EE Integration Agent with Apache 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 server 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 integrate manually. Extra 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 this 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.

Integrating with Tomcat

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

On the navigation panel, under Dashboards, click 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 Set up a new application server integration (the default selection).


	TIP: For other integration methods, Reusing an 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 integrate manually see Manual integration 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, first install your Tomcat server to run as a Windows Service.


	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 that you are running, type the desired VM options in the pre-instrumentor Options box.

For example, to set the memory limit for the pre-instrumentor to 256MB, 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 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, 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 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.