Managing the inventory

Keeping the inventory in sync with the WebSphere configuration

TODO

Creating groups for WebSphere clusters

To be able to efficiently monitor WebSphere servers that are cluster members, you need to create groups in RHQ that match the WebSphere topology. This can either be done by creating these groups manually or by using the Dynagroup feature to let RHQ create the groups automatically.

If you choose to create the groups manually, make sure that they are configured as containing compatible resources (of type WebSphere Server) and that the recursive option is enabled:

If you choose to configure a Dynagroup definition to let RHQ create the groups automatically, use the following expression:

groupby resource.resourceconfiguration[clusterKey]
resource.type.plugin = WebSphere
resource.type.name = WebSphere Server

The clusterKey is constructed from the cell and cluster name. If your WebSphere topology is designed with a naming convention that ensures that cluster names are unique acress cells, then you can use clusterName instead. Note that clusterKey doesn't exist in version 1.0.0 of the RHQ WebSphere plug-in.

Important: If your inventory contains WebSphere instances that are not cluster members, then the group calculation will fail because of a bug in RHQ. In that case, don't use Dynagroups and create the groups manually.

Setting up DB2 monitoring

Introduction

For every data source that is configured with the DB2 JDBC driver, the RHQ WebSphere plug-in creates an additional DB2 Monitor resource as a child of that data source. That resource is used to directly monitor the availability of the database and to collect metrics from DB2, without going through the application server. By default (starting with version 1.1.0) the plug-in connects to the database with the credentials found in the data source configuration.

By default the plug-in only checks the availability of the database and collects traits identifying the current primary and alternate servers (which is useful for DB2 instances that use ACR). Advanced metrics can be enabled, but this requires additional configuration as described in the next section.

Advanced metrics

The RHQ WebSphere plug-in is able to collect per connection statistics from DB2 and to aggregate these metrics per data source configured in WebSphere. For this to work, two conditions must be satisfied:

• The plug-in must be able to identify the connections belonging to a each data source instance. This is done by configuring the clientProgramName property on the data sources to be monitored. The clientProgramName property specifies the value of the CURRENT CLIENT\_APPLNAME special register for all connections created by the data source. Since this information is available in the data collected from DB2, it will allow the RHQ WebSphere plug-in to correlate DB2 connections with data sources configured in WebSphere.
• Access to the monitoring data collected by the DB2 instance requires at least SYSMON authority. In general the application user configured on the data source doesn't have this authority. Therefore the plug-in must be configured with an appropriate user for the monitoring connection.

Configuring the clientProgramName

There is nothing fundamentally difficult about configuring the clientProgramName on a data source in the WebSphere configuration. Just add a new custom property or edit the existing clientProgramName property. However, there are several things to keep in mind. This first is that the configuration must be done in such a way that each data source instance gets a unique value for that property. This is important for data sources that are defined at a scope other than server. For example, a data source defined on a cluster will be instantiated on each member of that cluster, and the value of the clientProgramName property must be different for each of these instances. This can be achieved by using WebSphere variables in the definition of the clientProgramName property. The other important thing to keep in mind is that values longer than 20 characters (after expansion of the WebSphere variables) will be truncated by the DB2 server. Taking these two constraints into account, the following approach is recommended:

• If the WebSphere server names are unique and the length of these names is reasonable (less than 10 characters), then use the predefined WAS_SERVER_NAME variable in the definition of the clientProgramName property. Obviously this variable needs to be concatenated with a fixed string that identifies the data source. E.g. for a data source with JNDI name jdbc/myds you may choose ${WAS_SERVER_NAME}:myds as the clientProgramName.
• In all other cases, define a new WebSphere variable RHQ_DB2MON_SERVER_IDENTIFIER at server scope and assign it a unique value for each server (that should not be longer than 10 characters). You can then use this variable in the data source configuration, e.g. ${RHQ_DB2MON_SERVER_IDENTIFIER}:myds. Note that the binary distribution contains a wsadmin script called client_program_name_config.py that can be used to automate the configuration of the individual data sources. It detects if a RHQ_DB2MON_SERVER_IDENTIFIER variable has been defined and constructs the clientProgramName accordingly.

Configuring the monitoring user

The monitoring user can be set manually by changing the connection settings of the DB2 Monitor resource:

In large WebSphere topologies, configuring the monitoring user manually may not be practical. Starting with version 1.1.0 the plug-in offers the possibility to automate that configuration. To use this feature, log in as administrator, open the configuration of the WebSphere Application Server server plugin and define a set of rules that determine which monitor user to configure depending on the DB2 instance and/or database:

By default, the job that updates the monitor users runs every 15 minutes. This can be changed in the Scheduled Jobs section of the plug-in configuration.