Prerequistes

This document describes the necessary steps to install the RHQ WebSphere plug-in and to add WebSphere instances to the RHQ inventory. It assumes that both the RHQ server and the RHQ agent(s) have already been installed.

Downloading and installing the plug-in

Binary distributions for the plug-in can be found here. The plug-in has two parts, one running in the RHQ agents and one running in the server. Refer to the sections titled Adding or Updating Agent Plugins and Adding or Updating Server Plugins in the RHQ documentation to install these two plug-in files.

To deploy the plug-in on the agents, they will need to be restarted. However, the configuration of the agents that will be used to monitor WebSphere instances needs to be changed as described in the next section, and that configuration change also requires a restart. Therefore, it is not necessary to restart the agents at this point.

On some RHQ 4.x versions, it may also be required to restart the RHQ server before being able to add WebSphere servers to the inventory. See BZ 861058.

Preparing the agent(s)

The RHQ agents are usually configured to use a Sun/Oracle JVM. To use the RHQ WebSphere plug-in, the agents must be reconfigured to run on an IBM JDK. In addition, several WebSphere libraries need to be added to the classpath of the agent. All necessary files are provided by the WebSphere Application Server product. If the agent is expected to connect to local WebSphere instances, then all files are already present on the host system. If the agent will be configured to monitor WebSphere instances remotely and the WebSphere product is not yet installed on the host where the agent runs, then you need to install it before proceeding. Note that it is not necessary to create a WebSphere profile. In the following, we will assume that WebSphere has been installed under $WAS_HOME. Typically this would be something like /opt/IBM/WebSphere/AppServer.

Now modify $RHQ_AGENT_HOME/bin/rhq-agent-env.sh to change the value of the RHQ_AGENT_JAVA_HOME environment variable to $WAS_HOME/java. At the same time you may also want to adjust the -Xms and -Xmx options specified in the RHQ_AGENT_JAVA_OPTS environment variable, especially if you are planning to monitor a larger number of remote WebSphere instances. E.g. 512 MB of heap should be enough to monitor about 30 WebSphere instances.

Next, the libraries required to connect to WebSphere must be added to the classpath of the agent. This can be done by creating symbolic links in the $RHQ_AGENT_HOME/lib directory. The following JARs from the WebSphere server runtime must be included:

• $WAS_HOME/runtimes/com.ibm.ws.admin.client_7.0.0.jar
• $WAS_HOME/plugins/com.ibm.ws.security.crypto.jar

To use the DB2 monitoring features, it is also necessary to include the DB2 JDBC driver (db2jcc.jar) in the class path.

If there are servers that host SIBus messaging engines, then a couple of classes from $WAS_HOME/plugins/com.ibm.ws.runtime.jar are required as well. However, when adding that JAR to the classpath, logging no longer works correctly (because the JAR contains a commons-logging.properties file). To avoid this, create a $RHQ_AGENT_HOME/conf/commons-logging.properties file with the following content:

org.apache.commons.logging.Log=org.apache.commons.logging.impl.Log4JLogger

Finally, if the WebSphere servers to be monitored are configured with Tivoli Access Manager, then you also need to add $WAS_HOME/plugins/com.tivoli.pd.amwas.core_6.1.0.jar to $RHQ_AGENT_HOME/lib.

After changing the configuration and class path, restart the agent so that the new settings are taken into account. Note that restarting the agent by scheduling a Restart Agent operation on the corresponding resource in RHQ will not work because the class path is not updated. Instead restart the agent from the command line using $RHQ_AGENT_HOME/bin/rhq-agent-wrapper.sh restart.

Creating the SSL trust store

To monitor WebSphere instances that have security enabled, it is necessary to create a trust store with the relevant server certificates. This can be done entirely through the RHQ GUI; using keytool should not be necessary. The required steps depend on the type and version of the WebSphere instances:

• If you are planning to use a single agent to monitor multiple WebSphere instances that are running on different nodes and that belong to the same WebSphere 7.0 cell, then the most efficient way to build the trust store is to import the cell certificate.
• In all other cases, import the server certificate. This applies to the following situations: monitoring WebSphere 6.1 instances (in any kind of topology), monitoring stand-alone WebSphere application servers (locally or remotely), monitoring WebSphere instances locally. Note that the server certificate is shared by all WebSphere instances running on the same WebSphere node. Therefore, the procedure needs to be executed only once per node, by choosing any of the WebSphere application servers on the node or by retrieving the certificate from the node agent.

Note that there are other possible options to create the trust stores that may be more efficient in some topologies. E.g. if you are planning to monitor the WebSphere instances locally (i.e. to install an RHQ agent on every host where a WebSphere instance is running) and all these instances belong to the same WebSphere 7.0 cell, then it may be more efficient to import the cell certificate into the trust store of one agent and propagate that file manually to the other agents. The location of the file is $RHQ_AGENT_HOME/data/WebSphere/trust.jks.

Configuring WebSphere

The minimum required configuration for a WebSphere instance to be monitored is that PMI is enabled on that instance. Otherwise the RHQ WebSphere plug-in will not be able to collect metrics from the server. Note that since the plug-in is able to activate individual PMI metrics automatically, it is not necessary to change the instrumentation level configuration of the server (with one exception described below).

To leverage all features of the plug-in, it is recommended to apply the following configurations as well:

• Install the XM4WAS plug-in on the WebSphere instances to be monitored. This is required to use the following features of the RHQ WebSphere plug-in:
  • JVM metrics.
  • Class loader leak statistics.
  • Advanced remote log event collection, including correlation of log events with applications/modules that triggered them.
  • JAX-RPC and JAX-WS connection cache metrics.
  • UNIX process statistics.
• The RHQ WebSphere plug-in will enable PMI metrics automatically as required. However, some particular metrics may return invalid values if they are switched on while the server is running. This is the case for all metrics that measure concurrency, such as the number of active threads in a thread pool or the number of concurrent requests on a servlet or EJB. These metrics are always set to 0 when they are first enabled, even if there are active requests. This means that the measurements are incorrect and may return negative values. To avoid this, it is recommended to enable these metrics in the WebSphere configuration so that they will be switched on when the server is started. The binary distribution contains a wsadmin script called pmi_config.py that can be used to automate this configuration.

Adding WebSphere instances to the RHQ inventory

If RHQ agents are colocated with WebSphere instances, then these WebSphere instances should have been detected automatically and appear in the auto-discovery queue, as shown in the following screenshot:

Select the servers to add to the inventory and click Import. Note that you may still need to adjust the connection properties to establish the connection to the newly imported server, in particular if security is enabled. The connection properties can be modified in the tab shown in the following screenshot (see below for the meaning of the various properties):

If you want to monitor WebSphere instances remotely, then you need to add them manually. The resource type is WebSphere Server. The following screenshots shows the connection properties to enter:

Most of the properties correspond to the parameters that are also needed when connecting to a WebSphere instance with wsadmin. If you are unsure about the protocol, use RMI. The port number depends on the chosen protocol. It can be determined from the WebSphere configuration as follows:

Protocol	Port name in the WebSphere configuration
RMI	BOOTSTRAP_ADDRESS or ORB_LISTENER_ADDRESS. If ORB_LISTENER_ADDRESS is 0, use BOOTSTRAP_ADDRESS. Otherwise, use ORB_LISTENER_ADDRESS
SOAP	SOAP_CONNECTOR_ADDRESS

If security is enabled on the WebSphere instance, then it is mandatory to specify a user name and password. The user must have operator role in WebSphere.

Finally, the Logging Provider property determines if and how log events are collected from the server:

• None: No log events will be collected.
• RasLoggingService: Collects log events using JMX notifications emitted by the RasLoggingService MBean which is registered on any WebSphere server. This mechanism is supported out of the box.
• XM4WAS LoggingService: This option requires deployment of the XM4WAS plug-ins to WebSphere (see above). It adds support for stack traces and correlating events with application components. In addition, it uses polling instead of JMX notifications.