Foglight for Java EE Technologies 5.9.9

On the Installations tab, look at the Upgradeable column for the installation you are interested in. If the word “Yes” appears, you can upgrade the installation.

Click the name of the installation you want to upgrade.

In the menu that opens, select Upgrade.

The dashboard refreshes, and the task appears in the Task History list, with a description such as: Upgrade Installation (<installation name>).

A progress indicator appears in the Result column while the task is in progress. The indicator is replaced by the text Success or Failure when the task is complete.

Java EE Integration Configuration FAQ and Troubleshooting

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

Table 6. List of FAQs/Issues
FAQ / Issue
What are the supported JVM versions and what are the levels of metrics collected?
My integration task was a partial failure because the Java Home location was wrong. How do I correct it?
Why is the Java EE agent sometimes unable to detect the correct type for the application server?
Why does my application server take so long to start up after integrating it with the Management Server?
I have multiple application servers with the same name that reside on the same host. When the Java EE agents connect to the Management Server, why does only the first agent connect?
I received an error message about heap space shortage from the instrumented Java EE agent. What should I do?
Why do I see memory usage characteristic changes after enabling the Java EE agent?
I received an error message about the max_long_data_size. What should I do?
Why does the Agent Manager support bundle not contain logs from the Java EE agent?

What are the supported JVM versions and what are the levels of metrics collected?

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

Table 7. JVM versions and collected metrics.
JVM Version	Level of Metrics Collected
IBM® 1.4.2 Oracle® JRockit 1.5.0_[05-07]	Limited
Oracle 1.4 Oracle JRockit 1.4 Oracle JRockit 1.5.0_[01-04]	Many
IBM 1.5, 1.6 Oracle 1.5, 1.6 Oracle JRockit 1.5.0_08 (R27.1.0) and higher Oracle JRockit 1.6	Full
OpenJDK 1.7 Oracle JDK 1.7	Full

My integration task was a partial failure because the Java Home location was wrong. How do I correct it?

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.

On the Integration Configurations tab of the Java Administration dashboard, click the name of the integration configuration (not the target) that you want to edit.

In the menu that opens, click Properties.

Type the correct value in the Java Home box.

Click Save.

Click OK to close the confirmation message box.

Click the name of the integration configuration again, and select Reintegrate targets.

In the Reintegrate dialog box that opens, select one or more targets and click Reintegrate.

Why is the Java EE agent sometimes unable to detect the correct type for the application server?

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.

Workaround

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:

-Dquest.agent.appserverinfo=<server-name>:<type>[:[<version>][:<cluster-name>]]

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

Why does my application server take so long to start up after integrating it with the Management Server?

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.

Workaround

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.

I have multiple application servers with the same name that reside on the same host. When the Java EE agents connect to the Management Server, why does only the first agent connect?

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.

Workaround

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):

-Dquest.config.agent.agentname=test_domain.admin

-Dquest.config.agent.agentname=prod_domain.admin

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 .

I received an error message about heap space shortage from the instrumented Java EE agent. What should I do?

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).

•

The Java EE agent collects JMX metrics, such as heap usage, and thread count, regularly by calling standard JVM and application server MBean methods.

•

The agent collects request metrics as the application server processes requests that match the filters specified in the agent configuration.

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

The memory usage is proportional to:

•

The number of metrics collected and the frequency at which they are collected

•

The number of service requests monitored, the level of detail captured about those requests, and the complexity of the requests

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.

Workaround

Consider increasing the heap size of the instrumented application server.

Why do I see memory usage characteristic changes after enabling the Java EE agent?

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.

Workaround

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

•

The environment may benefit from some basic heap size tuning. For example, reducing the maximum size of the heap when it is unnecessarily large may not only improve garage collection performance, but it limits the size of the process. This tuning can help alleviate problems that may arise from the JVM heap growing beyond typical or past levels.

•

Turning off class caching during instrumentation greatly reduces the number of allocated objects during instrumentation and causes memory usage to more closely match the behavior that was exhibited before the Java EE agent was integrated. However, it also causes instrumentation to take longer.

To turn off class caching, add the following to the JVM startup command line of the application server:

-Dquest.agent.class.cache.disable=true


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

I received an error message about the max_long_data_size. What should I do?

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

Could not synchronize database state with session

Workaround

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.