Foglight for Java EE Technologies 5.9.11 - Installation Guide

Java EE Integration Configuration FAQ and Troubleshooting

This section discusses potential issues when configuring application servers for integration with Java EE Integration Agent.

To help determine the level of metrics that are being collected for your JVM version, see the following table.

If you specify the wrong Java Home location during the creation of the Java EE Integration Agent, you can correct it from the Java Administration dashboard.

Users start their servers in various ways. Some of these ways may be different enough from the standard approaches described in this guide to cause the Java EE agent to be unable to determine the correct type for the application server. For example, if you are using a custom class to do some preliminary setup before starting the WebLogic® server, and you are passing weblogic.Server as a parameter to this class rather than calling weblogic.Server directly in the Java startup line, the Java EE agent gets the wrong name for the application server.

If the Java EE agent is unable to detect the application server type, it disables the associated agent and logs a fatal error.

The workaround is to set the application server name and type explicitly as a system property in the Java command line that starts the application server. Add a -D option to the Java startup line that has this format:

There are four fields, each separated by a colon-character.

The <server-name> and <type> are required parameters. The <version> and <cluster-name> are optional; if they are not supplied, the Management Server attempts to auto-detect the missing information. Valid application server type parameters are Generic, WebLogic, WebLogicNodeManager, WebSphere, WebSphereDmgr, WebSphereNodeAgent, WebSphereAdminAgent, OracleAS, and JBoss. The Java EE agent uses the server type and server version that are set in the command line to configure itself for that specific application server.

CAUTION: Specifying an incorrect application server type or version number results in errors later in the startup sequence. Application server type parameters are case-insensitive. The format for setting the version parameter differs based on the application server that you are configuring to work with Management Server. Consult the examples below for the correct server-specific and version-specific format to use to set the version parameter. This example specifies all four fields for a WebSphere® 6.1 application server named server3 in a cluster named my_cluster: -Dquest.agent.appserverinfo=server3:WebSphere:6.1.0.27:my_cluster This example specifies only 3 of the fields, leaving the agent to determine the application server version number for a WebLogic server named myserver in a cluster named my_cluster: -Dquest.agent.appserverinfo=myServer:WebLogic::my_cluster

When configuring agents, the user that is running the server must have read, write, and execute permissions on all directories under and including the Installation directory (QUEST_DEPLOYMENT_DIRECTORY). The installation directory is specified for the Java EE Integration Agent agent that is activated on the same host.

If you have manually integrated an application server with Management Server on AIX 5.3 with JVM 1.4, and the server is taking a long time to start up, it is due to a problem with JVM 1.4 on AIX 5.3.

Add -Djava.net.preferIPv4Stack=true to the Java command line that starts the server.

See ibm.com for more information about the problem with JVM 1.4 on AIX.

This error occurs because the Foglight Management Server does not allow duplicate agent names. Agent names are duplicated when multiple servers with the same name on the same host try to connect. If multiple Java EE agents reside on the same machine with the same server name, only one is permitted to connect.

The workaround is to uniquely identify the agent name by using the following server startup line:

-Dquest.config.agent.agentname=<unique_name>

For example, if you have two administrative servers for two different WebLogic domains running on the same host, the startup lines can be modified to include the following (one per server):

Since the agent names are unique, they will connect to the Foglight Management Server but do not modify the server name.

For more detailed information, see Java EE Integration Agent installation directory .

The Java EE agent is designed to monitor and collect valuable diagnostic detail out-of-the-box with minimal impact on application server heap. The agent configuration can be tuned to reduce (or increase) the amount of detail collected which in turn will reduce (increase) the agent memory usage.

The Java EE agent runs on the application server JVM and uses CPU resources to collect data about the application server. Two types of data are collected: periodic metrics (JMX) and request metrics (instrumentation).

Both types of data are transmitted to the Nexus running on the Foglight Management Server.

The memory usage is proportional to:

The metric collection memory usage impact is typically fixed, while the instrumentation memory usage impact varies considerably according to the application, workload, and the agent instrumentation and collection configuration.

Consider increasing the heap size of the instrumented application server.

The Java EE agent runs in the same JVM as the application server. As a result, the memory usage behaviors of the Java EE agent can impact the memory usage behaviors of the Application Server, which in turn can impact the memory usage behavior of the operating system.

One major contributor for the change is that objects are allocated for a cache that stores instrumented class information so the agent does not need to examine it every time. This optimization is made to improve the startup time performance. These are soft references, so the Garbage Collector can collect these objects if needed.

As a result, you may notice memory usage characteristic changes after enabling the Java agent.

A few different strategies can be used to minimize the changes to memory usage characteristics, as follows:

IMPORTANT: By disabling the class caching, the startup time of the instrumented application server increases.

When creating agent profiles or adding configuration file overrides to an agent profile, the Management Server may log the following error messages:

SQL Error: 1105, SQLState: HY000

Parameter of prepared statement which is set through mysql_send_long_data() is longer than 'max_long_data_size' bytes

Increase the value for the max_long_data_size or the max_allowed_packet system variable in your MySQL configuration. The recommended value is 8388608.

If you still encounter the error when using the recommended value, increase the value further or reduce the number of agent profiles.

IMPORTANT: The largest usable value is 1073741824, however it is recommended you increase the value in increments, by 50% at a time.

In order for the Agent Manager (FglAM) support bundle to include the log files from the Java EE agent, the Java EE Integration Agent (JavaIntegrator) must be active when the support bundle is collected.

If the Java EE Integration Agent is not active, the support bundle contains logs from the Java EE Integration Agent, but not from the Java EE agent.

Manually Integrating Application Server

You can use the application server agent setup wizard to configure and integrate the Java EE agent and the Java EE Integration Agent to work with most application servers. If for any reason you need to manually integrate, follow the instructions in this section that are specific to the application server you want to integrate with.

JBoss remote agent integration from the command-line

As an alternative to configuring agent integration through the agent setup wizard in the Foglight browser interface, you can use the fglcmd command-line scripts that are available on the Management Server.

If you are using the command-line interface and

NOTE: Use a single space to separate options on the command line. Do not use quotes.

Manual integration with Wildfly, JBoss AS and EAP

This section contains instructions for manually integrating the Java EE agent with a Wildfly, JBoss® Application Server (AS) or Enterprise Application Platform (EAP).

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

IMPORTANT: Review the following exceptions before configuring your server.

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

IMPORTANT: Use a single space to separate multiple options. Do not use quotes.