Home

How do I

Soft - is your software and documentation
Asset - is something that must be protected
Management - is what we do
Enterprise - is the capability
Computing - is the power
Services - are what we provide


The ClearQuest web “How do I” covers: (Last updated 9-Oct-09)

Ø  Logonwithout logon window, auto, etc...

Ø  CM Server – utilities, etc....

Ø  Environment -

Ø  Perl Hooks – understanding with CQWeb, etc...

Table of contents

The ClearQuest web “How do I” covers: (Last updated 9-Oct-09) 1

Table of contents. 1

Logon.. 2

1.       How do I – understand the users getting restricted access in ClearQuest Web on Linux/UNIX platforms issue  2

2.       How do I – understand why the Database connections are missing in ClearQuest Web 7.1 login screen. 2

3.       How do I - log on to the ClearQuest Web server without the login window.. 3

CM Server. 4

4.       How do I - force an SSL connection with Change Management Server (CM Server) for ClearQuest Web. 4

5.       How do I – understand the Rational Change Management (CM) Server Administration utility - new in 7.1.0.2  5

Environment. 6

6.       How do I – understand why ClearQuest Web WAS Service errors upon stop/restart 6

7.       How do I – understand why there is no response when trying to create a query on ClearQuest Web. 7

8.       How do I – understand the MustGather: ClearQuest Web 7.1 Server 7

9.       How do I - configure ClearQuest Web 7.1.x to use an alternate HTTP port 11

10.     How do I – understand the Change Management (CM) Server configuration guidelines for ClearQuest Web  12

11.     How do I – understand why the ClearQuest Web Server requires a CM Server 14

12.     How do I – understand the configuring of ClearQuest Web 7.0.x to use an alternate HTTP port 14

13.     How do I – do CQWeb: Performance and Tuning. 15

14.     How do I - run reports when using the ClearQuest Web client 26

15.     How do I – understand using CTRL-A within a text box causes entire page to highlight in ClearQuest Web  27

16.     How do I – understand the CM Server configuration guidelines for ClearQuest Web in ClearQuest version 7.1  27

17.     How do I – understand why the calendar selects the wrong month in Web client 29

18.     How do I – understand the Incorrect date and time formatting on Web client 29

19.     How do I - run Charts and Reports UNIX with ClearQuest Web. 29

20.     How do I - use a custom homepage with ClearQuest Web 7.1. 30

21.     How do I - access a Test Database in ClearQuest Web 7.1. 30

22.     How do I - access a test database from the ClearQuest Web ASP client 31

23.     How do I – access a test database from the ClearQuest Web Java client 31

24.     How do I - configure CQWeb Web Server to redirect to RWP. 32

25.     How do I - set up the cqweb_autologin for use with the ClearCase Remote Client and ClearQuest Integration 32

26.     How do I – understand the could not wsithc database error within ClearQuest Web. 33

27.     How do I – understand the further details regarding the configuration of MAPI on E-Mail notification for ClearQuest Web  34

Perl Hooks. 34

28.     How do I – understand the calling system() from perl hooks under CQWeb is unreliable on perhaps all platforms issue  34

Logon

1.    How do I – understand the users getting restricted access in ClearQuest Web on Linux/UNIX platforms issue

This technote explains a resolution for users getting restricted access errors when attempting to access an IBM® Rational® ClearQuest® Web server on a Linux® or UNIX® platform, even though licenses are available.

 

Cause

The ClearQuest Request Manager is not able to get the license server information. The native client on the server can login without any problems, but when accessing the web server, they get restricted access even though there are licenses available and restricted access is not enabled.

 

Resolving the problem

To resolve this situation, check the following settings on the ClearQuest server:

1.     Go to the <CQ_HOME>/bin/clearquest file.

2.     Look for line that says cq_license=port@host. It should be in the format port@host even when the port is default( e.g. 27000@xyz). Change this parameter if necessary.

3.     Restart the Request Manager using the <CQ_HOME>/cqweb/cqserver_startup script. By default CQ_HOME is /opt/rational/clearquest.

4.     If the previous steps do not work, you can set up the environment variable LM_LICENSE_FILE in the <CQ_HOME>/cqweb/cqserver/start_cqrm.sh file in 2003 versions and <CQ_HOME>/cqweb/cqregsvr/start_cqreg.sh file in 7.0.* and higher versions as follows:
LM_LICENSE_FILE=port@host
export  LM_LICENSE_FILE

Restart Request Manager as stated above.

2.    How do I – understand why the Database connections are missing in ClearQuest Web 7.1 login screen

Users can access the login screen for ClearQuest Web 7.1, but the pull-down menu with schema repository connections is blank. This prevents users from logging into ClearQuest through the web client; local client software can view the available connections without a problem.

 

Cause

This problem might occur if the operating system does not have enough memory to effectively run the CM Server process

 

Diagnosing the problem

Check the CM Server SystemOut.log file for error messages indicating a memory problem. The log file is located in the following directories, by default:

UNIX or Linux
/opt/ibm/RationalSDLC/common/CM/profiles/cmprofile/logs/server1

Windows
C:\Program Files\IBM\RationalSDLC\common\CM\profiles\cmprofile\logs\server1
In the file, search for the following, possible error message regarding memory:

Unable to start server: cqrpc.sh: java.io.IOException: Cannot allocate memory

 

Resolving the problem

Should the CM Server logs contain the error message referencing memory allocation problems, review these items:

3.    How do I - log on to the ClearQuest Web server without the login window

The URL format for automatically logging into ClearQuest has changed in different versions. Refer to the following table for the ClearQuest Web server versions 2003.06.13 and later:

Arguments

Value

<web_server_name>

ClearQuest Web server name

schema=

Your ClearQuest schema repository connection name

contextid=

Logical Database Name of your target ClearQuest database

username=

ClearQuest user name

password=

ClearQuest password

 

ClearQuest versions 7.0, 2003.06.14 - 2003.06.16

For example if you have the following URL that works in ClearQuest Web 2003.06.14 and later:
http://web_server_name/cqweb/main?command=GenerateMainFrame &service=CQ%20&schema=2003.06.00&contextid=SAMPL &username=admin&password=

 

ClearQuest versions 2003.06.13

For example if you have the following URL that works in ClearQuest Web 2003.06.13. This syntax was changed in later versions of ClearQuest.

http://web_server_name/cqweb/main?USE_CASE=GO &service=CQ%20&schema=2003.06.00&contextid=SAMPL &username=admin&password=

 

ClearQuest versions 2003.06.12 and earlier

Type in the address mentioned below, in your Browser, specifying your target the database in ClearQuest Web.

To create a URL that will allow you to login to your ClearQuest database on a ClearQuest Web Server, use the following URL syntax, substituting you values for this example:

http://web_server_name/clearquest_virtual_directory/logon/default.asp? DbSetName=2003.06.00&DatabaseName=SAMPL&user=admin&password=pwd

For example:
http://localhost/CQWeb/logon/default.asp? DbSetName=2003.06.00&DatabaseName=SAMPL&user=admin&password=""

Arguments

Value

web_server_name

Windows server name

clearquest_virtual_directory

ClearQuest virtual directory in IIS. Typically "CQWeb" by default

DbSetName=

Your ClearQuest schema repository connection name

DatabaseName=

Logical Database Name of your target ClearQuest database

user=

ClearQuest user name

password=

ClearQuest password

CM Server

4.    How do I - force an SSL connection with Change Management Server (CM Server) for ClearQuest Web

How do I force an SSL connection with Change Management Server (CM Server) for ClearQuest Web??

 

Cause

There is incorrect path specifications and incomplete information in the ClearCase and ClearQuest 7.1 and 7.1.0.1 help and Information Centers on how to force an SSL connection with Change Management Server for ClearQuest Web.

 

Answer

Forcing an SSL connection with CM Server for ClearQuest Web
You can force the Change Management Server (CM Server) to process non-SSL requests as SSL requests.

The following variables are used in path names in this topic:

yourServerName
CM Server host name

RATIONAL_COMMON
Directory where the Rational common files are installed

To force CM Server to process non-SSL requests as SSL requests:

1. Edit the file
httpd.conf, which is located in the following directory:

a. Add or modify the VirtualHost settings to include the following commands. Replace yourServerName with the name of your CM Server host, and %RATIONAL_COMMON% or $RATIONAL_COMMON with the path specification where the Rational common files are installed:

<VirtualHost *:80>
ServerName yourServerName
RewriteEngine on
RewriteCond %{SERVER_PORT} !^443$
RewriteRule ^(.*)$ https://yourServerName$1 [R]
RewriteLogLevel 0
RewriteLog "drive:\%RATIONAL_COMMON%\IHS\logs\rewrite.log"
</VirtualHost>

<VirtualHost *:80>
ServerName yourServerName
RewriteEngine on
RewriteCond %{SERVER_PORT} !^443$
RewriteRule ^(.*)$ https://yourServerName$1 [R]
RewriteLogLevel 0
RewriteLog "$RATIONAL_COMMON/IHS/logs/rewrite.log"
</VirtualHost>

Attention: Ensure that the commands are placed appropriately in the file so that they run before the WebSphere® Application module and the WebSphere Plug-in module.

b. Include the file
ssl.conf by adding the following command:
# include ssl information
Include conf/ssl.conf


c. Save your changes and close the file.


2. Edit the file
ssl.conf to provide the correct SSL certificate path information. The file ssl.conf is located in the following directory:


Save your changes and close the file.


3. Edit the file
cqServerConn.properties, which resides in the following directory:

a. Change the value of the parameter HELP_SERVER_URL from this:
HELP_SERVER_URL=http://localhost
to this:
HELP_SERVER_URL=https://localhost

b. Save your changes and close the file.


4. Restart the IBM HTTP Server.

5.    How do I – understand the Rational Change Management (CM) Server Administration utility - new in 7.1.0.2

This technical note describes the capabilities of the Rational Change Management (CM) Server Administration utility, introduced in ClearCase and ClearQuest version 7.1.0.2 as part of the Web support installation option.


Installation


The CM Server Administration utility is automatically deployed to the same WebSphere Application Server instance that hosts the CM Server.

You can manually deploy the CM Server Administration utility to another WebSphere Application Server instance. The file TeamAdminWebEAR.ear, which includes the CM Server Administration utility, is installed in the directory $RATIONAL_COMMON\CM\lib.


Getting started


The CM Server Administration utility is a browser-based interface that lets you monitor and configure a single CM Server system.

To start the utility:

1. Enter the following URL in a supported browser window (Microsoft Internet Explorer 6.0 or later, or Firefox 2.0 or later):

http://<cm-server-name>/TeamAdminWeb (if you are using IBM HTTP Server)

or

http://<cm-server-name>:12080/TeamAdminWeb

2. At the log in prompt, enter the following information:

3. Click Connect.


Overall monitoring

Summary information since the last time the CM Server host was started appears in a table.


Monitoring CM Server activity


There are two main monitoring views, each available on a separate tab:

Configuring and controlling the CM Server


To configure and control the CM Server, open the Site Configuration dialog box by clicking Site Administration > Configuration on the toolbar.

Each tab in the Site Configuration dialog box represents a CM Server MBean that controls configuration data:

 


All changes in the Site Configuration dialog box are made in real time. You do not need to restart the CM Server system. Note that some attributes on the CM Server ClearCase Options tab and the CM Server ClearQuest Options tab affect only new backend RPC server processes.


Limitations

1.     If the CM Server host has only the ClearCase or ClearQuest component installed, the configuration options for the product that is not installed still appear.

Setting some attributes to values that are outside the attribute range may not appear as errors until you refresh the Site Configuration dialog box.

Environment

6.    How do I – understand why ClearQuest Web WAS Service errors upon stop/restart

This technote provides steps for troubleshooting IBM® Rational® ClearQuest® Web Service errors when stopping or restarting the service

 

Symptom

ClearQuest Web Websphere Application Server V6 - RWP Servlet Service Errors

 

WAS Server Logs:

Every application server process gets several log files:
<profile>/logs/<server_name>/SystemOut.log
<profile>/logs/<server_name>/ SystemErr.log
<profile>/logs/<server_name>/startServer.log
<profile>/logs/<server_name>/stopServer.log
Where <profile> is
<embexpress_install>/profiles/profile1 (Unix and Windows – CQ Web; Windows only- PjC) On Windows we also install profile2 (for ReqWeb).
<server_name> is server1 for RWP configuration.

 

Diagnosing the problem

Issues with WAS Service Stop/Start Errors:

Stop error
If this happens, check that the IBM HTTP Server Service is stopped first. It must be stopped for a WAS Stop and started before a WAS Start.

Start error
Is the WASServer.exe process actually running, even after you stop it? Look in the task manager and kill the process and then do a "WAS - Stop" and then a "WAS Start".

Link to reference for creating WAS service commands:
http://publib.boulder.ibm.com/infocenter/wasinfo/v6r0/index.jsp?topic=/com.ibm.websphere.express.doc/info/exp/ae/rins_wasservice.html.

Note: wasservice commands are case sensitive, so you will need to run each as specified in the Infocenter. For Example:


WASService -add name_of_the_application_server_service
-serverName application_server_name
-profilePath profile_root
-wasHome app_server_root

 

Resolving the problem

Further troubleshooting WAS:

1.     Recreate issue with WASService commands.

2.     Verify client creating service commands properly (see example above).

3.     Issue either the start or stop command.

Review the log files for the point of failure.

`

7.    How do I – understand why there is no response when trying to create a query on ClearQuest Web

This happens when no default record type is defined in your schema. This issue has been identified as a product defect under APAR PK78422.

 

Environment

This problem occurs in ClearQuest Web version 7.1.x.

 

Diagnosing the problem

Determine whether a default record type has been selected. In ClearQuest Designer, you can right-click on each record type to see if it has been designated a default record type.

 

Resolving the problem

This defect is under investigation. There is no permanent fix at this time.

 

WORKAROUND

To workaround this problem, designate one of your record types as a default record type.

 

8.    How do I – understand the MustGather: ClearQuest Web 7.1 Server

What steps can you follow to gather additional information for IBM Rational ClearQuest Support in resolving issues with the ClearQuest Web 7.1.x?

 

Answer

Default Installation Locations

These are the default installation directories for Rational home and Rational common components. If you are using a non-default installation path, keep that in mind when reviewing these instructions.


RATIONAL_HOME refers to the location where Rational products are installed.

Windows: C:\Program Files\IBM\RationalSDLC

Linux/UNIX: /opt/IBM/RationalSDLC

RATIONAL_COMMON refers to the location where common components are installed.

Windows:  C:\Program Files\IBM\RationalSDLC\common

Linux/UNIX: /opt/IBM/RationalSDLC/common

Note: On some UNIX operating systems, the path might have a lowercase "ibm" directory. You can also access the Rational home and common directories using these symbolic paths:

/opt/rational

/opt/rational/common

Basic Verification Information


Note: With steps 2 through 5, if you do not receive the expected verification that the software is running correctly, take a screenshot or save the message to file for IBM Support.

1. Check that the system requirements are met. For more information, see technote 1294762.

2. Verify that IBM HTTP Server is running by accessing this URL:


http://<server_name>

If the service is running correctly, you will see this welcome message:

Rational Web Platform: If you see this page, it means that Rational Web Platform was installed and is running on this system.

3. Verify that CM Server is running by accessing this URL:

http://<server_name>/TeamWeb/services/Team

If the service is running correctly, you will see this welcome message:

Hi there, this is a Web service!

4. Verify that the ClearQuest Web application is running by accessing this URL:

http://<server_name>/cqweb

If running, you will see the ClearQuest Web interface and login screen appear.

5. Verify that the RPC services are running. Refer to the Checking RPC servers topic in the ClearQuest Information Center for details.

 

Gathering Diagnostic Logs for ClearQuest Web on Microsoft Windows


1. Login to ClearQuest Web as a Super User. Access the Site Administration > Site Configuration screen. Under the Application Options tab, set the Enable Diagnostics value to
full.

2. If requested by a ClearQuest Support Engineer, refer to the CM Server Diagnostic Logging and Information section for instructions on increasing the CM Server logging levels.

3. Stop the CM Server and ClearQuest Web services. Refer to the Starting, stopping, and restarting CM Server topic of the ClearQuest Information Center.

Note: This will also stop the ClearCase Remote Client (CCRC) server and CM API operations if hosted on the same machine.

If installed, also disable the service for full-text searching.

4. Delete any existing logs from these directories:

5. Enable diagnostic tracing. Download the file core_trace_for_web.zip from this technote. Extract the core_trace_for_web_enable.reg file onto your Web server. Double-click on the file to update the Windows registry.

6. Restart all the web services except for full-text search.

7. Reproduce the problem behavior with ClearQuest Web.

8. Stop all web services again.

9. Gather all the logs in these directories:

·         <RATIONAL_COMMON>\IHS\logs

If instructed by a ClearQuest Support Engineer, gather the CM Server MBean configuration data. You can find instructions in the CM Server Diagnostic Logging and Information section.

Also collect the trace file, which should be located in the root C: drive directory.

10. Disable diagnostic tracing. Extract the
core_trace_for_web_disable.reg file onto your Web server. Double-click on the file to update the Windows registry.

11. Restart all necessary web services.

12. If you adjusted the logging levels for CM Server, you must restore the original settings. See the
CM Server Diagnostic Logging and Information section for instructions.

13. Login to ClearQuest Web as a Super User. Access the Site Administration > Site Configuration screen. Under the Application Options tab, set the Enable Diagnostics value to
default.

14. You may now resume normal ClearQuest Web operation.

 

Gathering Diagnostic Logs for ClearQuest Web on Linux or UNIX

 

1. Login to ClearQuest Web as a Super User. Access the Site Administration > Site Configuration screen. Under the Application Options tab, set the Enable Diagnostics value to full.

2. If instructed by a ClearQuest Support Engineer, refer to the CM Server Diagnostic Logging and Information section for instructions on increasing the CM Server logging levels.

3. Stop the CM Server and ClearQuest Web services. Refer to the Starting, stopping, and restarting CM Server topic of the ClearQuest Information Center.

Note: This will also stop the ClearCase Remote Client (CCRC) server and CM API operations if hosted on the same machine.

4. Delete any existing logs from these directories:

·         <RATIONAL_COMMON>/IHS/logs


5. Enable diagnostic tracing.

Modify the file
 cqrpc.sh, which is found in this directory:

<RATIONAL_COMMON>/CM/bin

If they do not exist, add these six lines to the end of the file:

CQ_DIAG_TRACE="API;EDIT;SESSION;PERL;SQL=3;THROW;DB_CONNECT=2;HOOKS=2;LICENSE;TIMER;THREAD;DB_MISC;"

CQ_DIAG_REPORT="MESSAGE_INFO=0x070B;DIAG_FLAGS=-1;OUTPUT_LIMIT=1000000"
CQ_DIAG_OUTPUT="/opt/RationalSDLC/common/CM/profiles/cmprofile/logs/cq_diagnostics.log"
export CQ_DIAG_TRACE
export CQ_DIAG_REPORT
export CQ_DIAG_OUTPUT

If these lines already exist in the file, then they are likely commented out. If so, uncomment the lines.

Note: If the install directory is different than indicated, modify the CQ_DIAG_OUTPUT to account for the correct
cmprofile logs directory.

6. Restart all the web services except for full-text search.

7. Reproduce the problem behavior with ClearQuest Web.

8. Stop all web services again.

9. Gather all the logs in these directories:

·         <RATIONAL_COMMON>/IHS/logs


If instructed by a ClearQuest Support Engineer, gather the CM Server MBean configuration data. You can find instructions in the
CM Server Diagnostic Logging and Information section.

If you defined a directory other than the
cmprofile logs directory for the diagnostic trace output, collect the logs from that directory.

10. Disable diagnostic tracing by commenting out all six diagnostic lines in the
cqrpc.sh file.

11. Restart all necessary web services.

12. If you adjusted the logging levels for CM Server, you must restore the original settings. See the
CM Server Diagnostic Logging and Information section for instructions.

13. Login to ClearQuest Web as a Super User. Access the Site Administration > Site Configuration screen. Under the Application Options tab, set the Enable Diagnostics value to
default.

14. You may now resume normal ClearQuest Web operation.


Change Management (CM) Server Diagnostic Logging and Information

 

In some instances, it is necessary to gather diagnostic information on CM Server as well as ClearQuest Web. These sections instruct you on how to prepare this diagnostic information for gathering along with the ClearQuest Web information. You should only follow these instructions at the request and guidance of a ClearQuest Support Engineer.

Collecting MBean attribute information

You can configure CM Server using a variety of different variables called MBean attributes. When experiencing problems with ClearQuest Web or CM Server, it is worth verifying that these attributes are correctly established. Incorrect attribute values can cause problems with the starting or stability of the server processes.

You can send IBM Rational Support a summary of your custom MBean configuration settings with these instructions:

1. Locate these directories:

Windows:
 <RATIONAL_COMMON>\CM\profiles\cmprofile\config\cells\<host>CMProfileNode01Cell\nodes\<host>CMProfileNode01Cell\servers\server1\stp

Linux/UNIX:
<RATIONAL_COMMON>/CM/profiles/cmprofile/config/cells/<host>CMProfileNode01Cell/nodes/<host>CMProfileNode01Cell/servers/server1/stp

Note: If the "stp" directory does not exist, you have not established any custom MBean attributes. You do not have to continue with gathering this particular data.

2. These files store the current MBean attributes configured for CM Server. Collect all of the files in this directory.

More information on proper MBean configuration

You can find more information about this in these documents:

·         The Setting available MBean attributes topic in the ClearQuest Information Center.

·         Technote 1384746 - Preserve the CM Server MBean Configuration Before Customizing the MBean Attributes, Upgrading, or Reinstalling ClearCase and ClearQuest.

Increasing CM Server logging levels

These are the steps for increasing the logging level detail on CM Server. By changing the logging level, you are increasing the trace output and diagnostic information in the CM Server logs. With these instructions, you will also verify that file count and file size of these logs is sufficient for reproducing a problem during a trace.

Increasing the diagnostic detail can affect system performance. This should only be done for short periods of time. Be sure to restore logging to original settings when such detail is not needed.


1. Browse to the CM Server administration console URL:

http://<server_name>:<port>/ibm/console

Note: The default port is 12060 for out-of-the-box CM Server. For CM Server hosted on your own IBM WebSphere Application Server, the default port is 9060.

2. Login to the administration console.

3. Access the menu option Troubleshooting > Logs and Trace.

4. Click on your server. The default for out-of-the-box CM Server is server1.

5. Click on Diagnostic Trace.

6. Under the Runtime tab, change the Maximum File Size and Maximum Number of Historical Log Files values to 20. Click OK at the end of the page.

7. Click the Save link in the Messages area at the top of the page that opens.

8. Click on JVM Logs.

9. Under the Configuration tab, change the Maximum Size and Maximum Number of Historical Log Files values to 20. Do this for both error log files, System.out and System.err. Click OK at the end of the page.

10. Click the Save link in the Messages area at the top of the page that opens.

11. You will need to restart the CM Server process for these changes to take affect.

12. Once restarted, return to the CM Server administration console.

13. Access the menu option Troubleshooting > Logs and Trace.

14. Click on your server. The default for out-of-the-box CM Server is server1.

15. Click on Change Log Detail Levels.

16. Under the Runtime tab, expand the com.ibm.rational.* group.

17. Click on the com.ibm.rational.stp.* sub-group. Select the context menu item Message and Trace Levels > fine. Click OK at the end of the page.

18. Click the Save link in the Messages area at the top of the page that opens.

Restoring standard CM Server logging levels

These are the steps for restoring the logging levels of CM Server to their original state.

1. Browse to this URL:

http://<server_name>:<port>/ibm/console

Note: The default port is 12060 for out-of-the-box CM Server. For CM Server hosted on your own IBM WebSphere Application Server, the default port is 9060.

2. Login to the administration console.

3. Access the menu option Troubleshooting > Logs and Trace.

4. Click on your server. The default for out-of-the-box CM Server is server1.

5. Click on Change Log Detail Levels.

6. Under the Runtime tab, expand the com.ibm.rational.* group.

7. Click on the com.ibm.rational.stp.* sub-group. Select the context menu item Message and Trace Levels > info. Click OK at the end of the page.

8. Click the Save link in the Messages area at the top of the page that opens.

 

Related information

MustGather: ClearQuest Web Java

 

core_trace_for_web.zip

acies in, or any omissions from, the information which it contains.

9.    How do I - configure ClearQuest Web 7.1.x to use an alternate HTTP port

What are the details on configuring the IBM® Rational® ClearQuest® 7.1.x server to use an alternate HTTP port other than port 80?

Cause

The Changing the default CM Server HTTP port and Changing the default CM Server ports topics in the ClearQuest Information Center have detailed information on changing port numbers for ClearQuest Web and CM Server. This a summary of the required steps

 

Answer

To change the ClearQuest 7.0.x Web services to use an alternate HTTP port, there are 3 files that need updating. This is an example of changing the port to from the default of 80 to 8080.

1.     httpd.conf - Location: (C:\Program Files\IBM\RationalSDLC\common\IHS\conf) - You must change the following line at the Listen directive:

Listen 0.0.0.0:8080

2.     plugin-cfg.xml - Location (C:\Program Files\IBM\RationalSDLC\common\eWAS\profiles) - Update port where the VirtualHost name is set to 80.

3.     virtualhosts.xml - Location (C:\Program Files\IBM\RationalSDLC\common\CM\profiles\cmprofile\config\cells\<node_name>) - Update HostAlias_2 where the entry is 80.


Stop all ClearQuest Web services before updating the files and then restart them after you have updated the files. When you now try to access ClearQuest Web, you must use the URL including the port number:

http://servername:8080/cqweb

If the ClearQuest Web fails to start, try re-booting the server to fully release the ports.

10. How do I – understand the Change Management (CM) Server configuration guidelines for ClearQuest Web

System Resources
All Platforms

CM Server host must have a minimum of 4 GB of memory.

Java Virtual Machine (JVM) cache for the CM Server profile must be 1 GB.


UNIX
General

At a minimum, the swap space on UNIX host systems must be twice the size of memory.


Solarisx86

Disable the Nagel algorithm by using the following command:


ndd -set /dev/tcp tcp_naglim_def 1

AIX

Use an AIX Power 5 or Power 6 host system.

Set the following operating system parameters:

no -o tcp_nagle_limit=0

Most TCP implementations use the Nagel algorithm, where a TCP connection can have only one outstanding small segment that has not been acknowledged. This causes TCP to delay sending further packets until it receives an acknowledgement or until it can bundle more data and send a full-size segment.

You must disable the Nagel algorithm when using the ClearQuest Web application.


no -o clean_partial_conns=1

Specifies whether SYN (synchronize the sequence number) attacks are avoided.

Enable this option for the ClearQuest Web application to protect against network attacks.


no -o tcp_nodelayack=1

Enabling this parameter causes TCP to send immediate acknowledgement (ACK) packets to the sender. When the parameter tcp_nodelayack is off, TCP delays sending ACK packets by up to 200 ms. This allows the ACK packet to piggyback on a response and minimizes the system overhead.

For optimal performance, enable this parameter.


no -o rfc1323=1

Enables window scaling and time stamps as specified by RFC 1323 (TCP Extensions for High Performance). Window scaling allows the TCP window sizes (tcp_recvspace and tcp_sendspace) to be larger than 64 KB (65,536) and is typically used for large maximum transmission unit (MTU) networks.

If your ClearCase VOBs or ClearQuest databases are hosted on a Windows system, enable this parameter for optimal performance.


HP

Increase the following tunable kernel parameters:

maxfiles=4096
maxfiles_lim=8192
nfile=16384

Disable the Nagel algorithm by issuing the following command:

ndd -set /dev/tcp tcp_naglim_def 1

Modify TCP_KEEPALIVE_INTERVAL (Determines the interval between probes)

ndd -set /dev/tcp tcp_keepalive_interval 7200000

default value: none recommended
value: 7200000 (milliseconds)

Increase JVM VIRTUAL PAGE SIZE(Sets the JVM instruction and data page sizes to 64 MB to improve performance)

For WebSphere 6.1.0.x use the following command

chatr +pi64M +pd64M <WASHOME>/java/bin/PA_RISC2.0/java


default value: 4 MB
recommended value: 64 MB

Stop WAS prior to making this change.

Modify TCP_CONN_REQUEST_MAX

Specifies the maximum number of connection requests that the operating system can queue when the server does not have available threads. When high connection rates occur, a large backlog of TCP/IP connection requests builds up and client connections are dropped. Adjust this setting when clients start to time out after waiting to connect. Verify this situation by issuing the netstat -p tcp command. Look for "connect requests dropped due to full queue."

ndd -set /dev/tcp tcp_conn_request_max 8192

default value: 4096
recommended value: 8192


CM Server Parameters

The CM Server may be tuned for optimal performance for ClearQuest Web users based on expected peak load. The following parameter list can be adjusted to achieve the desired performance level. See the CM Server documentation in the ClearQuest Web administrator help for instructions on how to modify these MBEANs.

serverWorkerThreadCount - Default value is 16

Description : The number of threads that a ClearQuest RPC process will use to handle incoming requests.

Configuration : Increasing this value allows for a fewer number of ClearQuest RPC processes. Update this value with caution, as setting it to an improper value can have a negative effect on performance. Setting this value too high will cause contention within a process, and setting this value too low increases the need for more ClearQuest RPC processes.

activeHttpSessionThreshold - Default value is 30.

Description : The number of active HTTP sessions on a ClearQuest RPC process. If this value is exceeded, it may cause the CM Server to start another ClearQuest RPC process.

Configuration: Increasing this value will allow for fewer ClearQuest RPC processes. Update this value with caution, as setting it too high will cause contention within a process, and setting it too low will increase the need for more ClearQuest RPC processes.

maximumActiveServers - Default value is 8.

Description : The maximum number of active ClearQuest RPC processes allowed by the CM Server. This number may be adjusted to suit the host system’s resource capacity.

recycleServerHttpSessionLimit - Default value is 200. A value of zero indicates that this limit will not be checked.

Description : The number of HTTP sessions that a ClearQuest RPC process will service before it is recycled by the CM Server.

recycleServerLifetimeLimit - Default value is 86,400 seconds (24 hours). A value of zero indicates that this limit will not be checked.

Description : The maximum life time, in seconds, of a ClearQuest RPC process before it is recycled by the CM Server.

recyclingPeriod - Default value is 3,600 seconds (60 minutes). This value must be greater than zero.

Description : The amount of time, in seconds, that a recycling ClearQuest RPC process is allowed to shutdown and complete any outstanding session work before it terminates.

Configuration: Update this value with caution, as setting this to an improper value can have a serious effect on performance. This value overrides the behaviors of the following MBEANs: sessionObjectDefaultTimeout, sessionQueryObjectTimeout, and sessionRecordObjectTimeout.

11. How do I – understand why the ClearQuest Web Server requires a CM Server

The IBM Rational ClearQuest Web Server is dependent on the CM Server. When you install IBM Rational ClearQuest Web Server, you must either install CM Server on the same system or have a CM Server available on a different system.

 

Resolving the problem

To workaround this issue, install CM Server on the same server as the ClearQuest Web Server. Or install CM Server on a different server that is accessible by the ClearQuest Web Server.

 

12. How do I – understand the configuring of ClearQuest Web 7.0.x to use an alternate HTTP port

What are the details on configuring the IBM® Rational® ClearQuest® 7.0.x Web Java server to use an alternate HTTP port other than port 80?

 

Cause

The To change the default RWP HTTP port and To change the default RWP ports topics in the ClearQuest Information Center have detailed information on changing port numbers for ClearQuest Web and the Rational Web Platform (RWP). This a summary of the required steps.

 

Answer

To change the ClearQuest 7.0.x Web services to use an alternate HTTP port, there are 3 files that need updating. This is an example of changing the port to from the default of 80 to 8080.

1.     httpd.conf - Location: ( c:\program files\rational\common
\rwp\IHS\conf
) - You must change the following line at the Listen directive:

Listen 0.0.0.0:8080

2.     plugin-cfg.xml - Location (c:\program files\rational\common\rwp\EmbeddedExpress\profiles) - Update port where the VirtualHost name is set to 80.

3.     virtualhosts.xml - Location (c:\program files\rational\Common\rwp\EmbeddedExpress\profiles
\profile1\config\cells\DefaultNode
) - Update HostAlias_2 where the entry is 80.

Stop all ClearQuest Web services before updating the files and then restart them after you have updated the files. When you now try to access ClearQuest Web, you must use the URL including the port number:

http://servername:8080/cqweb/login

If the ClearQuest Web fails to start, try re-booting the server to fully release the ports.

13. How do I – do CQWeb: Performance and Tuning

Level: Introductory

Carlos Ferreira, Product Manager, IBM 

06 Aug 2004

In this whitepaper Carlos Ferreira provides information on how to configure your environment to optimize performance of the new IBM Rational ClearQuest Web.

Overview

The intent of this whitepaper is to provide IBM® Rational® ClearQuest® Web administrators with system monitoring, tuning, and sizing information. This document applies to ClearQuest Web version 2003.06.00.500 (not to previous versions of ClearQuest Web, which were based on Active Server Pages technology). In order to optimize the performance of ClearQuest Web effectively, it is important to understand the concepts described here. From a top level point of view, the primary areas to consider in a ClearQuest Web deployment are:

In addition, these important considerations are covered in a separate Rational ClearQuest performance white paper entitled "Rational ClearQuest Performance Improvement" by James Tykal, Senior Technical Marketing Engineer:

In order to tune and size a ClearQuest Web application deployment effectively, you must first ensure that you have monitoring tools in place. They will measure critical performance parameters for each of the above areas, and are also useful for troubleshooting production performance problems.

 

Monitoring

Monitoring tools are dependent on the operating system on which you are deploying ClearQuest Web. The specific tool(s) you should use are naturally dependent on which ClearQuest Web component you are monitoring. In any case, your monitoring process should include storing results for specific configurations so that you can see performance trends over time.

 

Memory and CPU Usage

Operating system resources like process memory and CPU use are among the most important parameters to measure. Average CPU utilization of greater than 90% may be unhealthy-an indication that peak CPU usage of 100% is occurring. This may cause sporadically slow transaction response times and inconsistent memory usage patterns. To help you track this, Microsoft® Windows® comes with a performance monitoring tool that is available in the Microsoft Management Console. To launch the performance tool, type the following either in the Run dialog box or the at the MS-DOS prompt:

perfmon / WMI

For additional details on how to use this performance monitoring tool see the MSDN library performance tools page.

To measure UNIX® operating system resources, the top command is a useful performance monitoring tool. For additional details on how to use the top command, see: http://www.mcsr.olemiss.edu/cgi-bin/man-cgi?top+1 Table 1, following, shows some typical output of the top command.


Figure 1. Example output from UNIX top command table 1
Example output from UNIX top command table 1

Tables 2 and 3 show key ClearQuest Web processes to monitor.


Table 2. ClearQuest Web application processes on Windows

Service

Process

Additional information

Rational Web Platform, Apache HTTP server

rwp.exe
rotatelogs.exe

There are two rwp.exe processes for fault tolerance; one is master, one is worker. If the worker process dies, the master starts up a new one.
There are four rotatelogs.exe processes that are started by the two
rwp.exe processes (two each) to handle log rotation.

Rational Web Platform, Tomcat servlet engine for ClearQuest Web

java.exe
jk_nt_service.exe
1

The properties file that controls these Java processes is jk_service.properties.

Rational Web Platform, Tomcat servlet engine for ReqWeb

java.exe
jk_nt_service.exe
1

ClearQuest Web does not use this service.


Table 3. ClearQuest Server process on Windows

Service

Processes

Additional information

Rational ClearQuest
Request Manager

java.exe
jk_nt_service.exe
1
requestmgr.exe

The properties file that controls these Java® processes is requestmgr_service.properties, located in the <rational install>\clearquest\cqweb\cqserver directory.

Rational ClearQuest
Registry Server

java.exe
cqregsvr.exe
1

None.

Renaming ClearQuest Java Processes on Windows for Easier Monitoring

In Tables 2 and 3 above, there are four different ClearQuest Web processes called java.exe, which makes it difficult to isolate and monitor specific ClearQuest processes. To clarify their function, you should rename the processes specified in the bootstrap files shown on Table 4. The three steps required to rename a ClearQuest Java process are:

1.     Rename the Java executable in the bootstrap file that initiates the process.

2.     Create a copy of the java.exe program with the new name.

3.     Restart the services.


Table 4. Java process bootstrap properties files

CQWJ Java Process

Bootstrap Filename and Location

Registry Server

C:\Program Files\Rational\ClearQuest\cqweb\cqregsvr\ cqregsvr_service.properties

Request Manager

C:\Program Files\Rational\ClearQuest\cqweb\cqserver\ requestmgr_service.properties

Tomcat

C:\Program Files\Rational\Common\rwp\bin\ jk_service.properties

1.     Modify the following section in each bootstrap file:

#
# This is the Java interpreter used for running Tomcat
#
wrapper.javabin=$(wrapper.java_home)\bin\java.exe
                                                                            

 

2.     Change the java.exe file name to something more meaningful, such as java_requestmgr.exe for the Request Manager. If you are working with a multiple Request Manager configuration, name each Request Manager process uniquely, such as java_requestmgr_A.exe.

3.     Create copies of the actual java.exe program and give the copies the same names as the renamed processes. The java.exe program used by ClearQuest Web Application is in C:\Program Files\Rational\Common\Java\JRE\bin. Simply duplicate this program and rename the copy. Be sure to keep the original java.exe in this directory.

4.     Restart all the ClearQuest Web processes to have the renamed processes take effect. You can use Windows Task Manager to examine the renamed processes. On UNIX, the command ps -ef | grep java will provide all the java processes that are running, along with their executable directory and process ID. The process ID can then be correlated with the process ID provided in the top command. Table 5 shows the Java process directory and the component to which it corresponds.

On UNIX, conversely, renaming the Java processes is not necessary because the process IDs can be determined from the information detailed in Table 5.


Table 5. ClearQuest Web application processes on UNIX

Service

Process

Additional information

Rational Web Platform, Apache HTTP server

/opt/rational/common/rw
;p/bin/rwp

On UNIX, the rwp processes are collectively one instance of Apache. Apache consists of one master process and several worker processes (instead of one master and one multi-threaded worker like that running on Windows). You can tune the number of worker rwp processes by editing the rwp.conf file. See the comments in rwp.conf for instructions. The master rwp process starts two rotatelogs processes to handle log rotation

Rational Web Platform, Tomcat servlet engine

/opt/rational/common/java
/bin/..
/bin/arch/native_threads/java-
Xms16m -Xmx256

The word "arch" represents the architecture for example, sun5 for Sun Solaris.

Registry Server

java

Process ID can be found in the file /opt/rational/clearquest/cqweb/cqregsvr
/logs/cqreg.pid

Request Manager

java

Process ID can be found in the file /opt/rational/clearquest/cqweb/cqserver
/logs/cqrm.pid

 

Users

When you are seeking to understand system performance, the number of concurrent users accessing the ClearQuest Web application during a performance test is an important metric to capture. Table 6 below provides access log information for Apache and Tomcat.


Table 6. Access files

Name

Description

Location

access.log

Apache access log containing the list of IP addresses that have accessed ClearQuest Web and when they accessed it.

Windows: C:\Program Files\Rational\Common\rwp\logs
UNIX:
/opt/rational/common/rwp/logs

localhost_access.log

Tomcat access log

Windows: C:\Program Files\Rational\Common\rwp\logs
UNIX:
/opt/rational/common/rwp/logs

The access.log file contains the client IP addresses, as well as the times that the clients have accessed the application. Here is an example of the output:

192.168.223.1 - - [23/Aug/2003:17:36:37 -0400] "GET

/cqweb/main?command=ExecuteQuery&queryName=Public+Queries%2FAll+Defects&dbid=

33554655&pNm=Public+Queries&pDbid=33554440&rmsessionid=e8746e42-eb91-4773-

bd99-c0a8df01e187 HTTP/1.1" 200 1571

192.168.223.1 - - [23/Aug/2003:17:36:37 -0400] "GET

/cqweb/main?command=ExecuteQueryWithoutPrompts&dbid=33554655&rmsessionid=e874

6e42-eb91-4773-bd99-

c0a8df01e187&bNewQuery=false&bNewSavedQuery=true&queryName=Public%20Queries%2

FAll%20Defects HTTP/1.1" 200 519

192.168.223.1 - - [23/Aug/2003:17:36:38 -0400] "GET

/cqweb/main?command=GetWSContentFrame&dbid=33554655&qid=33554655&rmsessionid=

e8746e42-eb91-4773-bd99-c0a8df01e187 HTTP/1.1" 200 1151

192.168.223.1 - - [23/Aug/2003:17:36:38 -0400] "GET /common/html/null.html 

HTTP/1.1" 304 0

            

 

Other Metrics

Other important values to monitor include:

You can monitor active HTTP sessions-using the RWP Tomcat servlet access logging -- by modifying C:\Program Files\Rational\Common\rwp\conf\server.xml. For more information go to: http://jakarta.apache.org/tomcat/tomcat-4.1-doc/config/valve.html#Access%20Log%20Valve

You can log the following items:

You can also monitor the current status of your HTTP Web server using the following URL: http://Hostname/server-status, where Hostname is the name of the server on which ClearQuest Web is deployed. The following information is provided:

The following additional information can be accessed by adding the ExtendedStatus On directive to the C:\Program Files\Rational\Common\rwp\conf\rwp.conf, as shown below.

#

#----------------------------------------------

# Directives related to inquiring server status

#----------------------------------------------

ExtendedStatus On

            

 

 

Performance

Other key indicators to consider when monitoring web applications include transaction response times and transaction throughput. There are many software tools available that allow you to simulate user transaction load on your ClearQuest Web deployment. Note that these tools often require that you record or build scripts that reflect your user transaction load profile. They also provide metrics regarding the number of transactions that succeed or fail, and the average, minimum, and maximum response times per transaction. Monitoring these transactions is an important step in being able to size your hardware for your production deployment effectively. In fact, IBM® Rational® Test Manager ™ was used to test the performance of the IBM Rational deployment of ClearQuest Web.

 

Tuning

Rational ClearQuest Web Application

The ClearQuest Web application and the ClearQuest Server are the two installable components of the latest version of ClearQuest Web. The ClearQuest Web application installs the RWP (including Apache version 2 and Tomcat version 4), which is the common web platform for serving the IBM® Rational® RequisteWeb®, ClearQuest Web, IBM® Rational® ClearCase® Web, and IBM® Rational® Project Console™ web clients. The ClearQuest Web Application is the presentation tier of the ClearQuest Web, deployed as a web application on the Tomcat servlet engine. Some ClearQuest Web static HTML and Javascript files are also deployed on the Apache Web Server.

When tuning the ClearQuest Web deployment, do not change too many configuration parameters at one time. After making a change, monitor the application using monitoring tools described in the previous section.

As opposed to the software configuration, the single biggest hardware issue affecting ClearQuest Web performance is RAM. If multiple applications are using a server that lacks available memory or CPU resources, the most likely result is poor performance. To ensure that there is adequate memory and CPU available for each ClearQuest process deployed on the server, use the monitoring tools described in the previous section to determine which processes are consuming memory and CPU. With this information, you can stop or move unnecessary processes to a different server to conserve memory or CPU. In addition, you can increase the maximum JVM memory for each of these processes to eliminate Out of Java Memory Error or OutOfMemoryException reported in the log files.

For the peak number of concurrent clients, you should ensure there is a sufficient memory for Apache, Tomcat, Request Manager, and Registry Server processes by looking at your process list using a tool such as top. If you deploy all of these applications on the same server, their total memory should not be more than 80% of the total available memory, since some memory needs to remain available for the operating system processes. Finally, run the latest stable release and patch level of the operating system that you choose. Many OS suppliers have introduced significant performance improvements to their TCP stacks and thread libraries in recent years.

 

Reduce the Amount of Logging

Logging to files requires the use of system resources: disk, memory, and CPU. Excessive logging degrades performance, and the sheer number of log entries can also make it more difficult to find problems. Logging should be set to <logger level="SEVERE"/> when trying to troubleshoot problems in production. See the ClearQuest Web Administrator's Guide (in Additional References, following) for instructions on how to set the logging level for all ClearQuest Web Application components. As log files increase in size, however, performance will degrade. You should therefore rotate log files every 24 hours. With the RWP, ClearQuest Web provides utilities to do so.

 

Tuning Apache

This section covers some of the more important tuning parameters of the Apache HTTP server. For a complete list of all the parameters that can affect performance, see the Apache Web site. You can obtain significant performance gains simply by ensuring that settings are correctly configured for the expected application load. Since every ClearQuest Web client's request goes to the Apache HTTP server first, its performance plays an important role in the overall system operation.

 

Secure Sockets Layer (SSL)

If SSL client authentication is configured, the server requests the client's certificate for any HTTPS (HTTP + SSL) request. This of course adds overhead and therefore decreases system performance. If you don't need SSL, you can disable SSL connections in the Apache Web server. See the New ClearQuest Administrator's Guide for information about enabling and disabling SSL Connections in Apache.

 

KeepAlive Directive 2

This directive enables HTTP persistent connections. The syntax is: KeepAlive On|Off Default: KeepAlive On

The Keep-Alive extension to HTTP/1.0 and the persistent connection feature of HTTP/1.1 provide long-lived HTTP sessions, which allows multiple requests to be sent over the same TCP connection. In some cases this has been shown to result in an almost 50% speedup in latency times for HTML documents with many images. To enable Keep-Alive connections, set KeepAlive On.

MaxClients Directive

A Web server should never have to swap, as swapping increases the latency of each request beyond a point that users consider "fast enough". This causes users to hit stop and reload, further increasing the load. You can, and should, control the MaxClients setting to prevent your server from spawning so many children that it starts swapping. This directive specifies the maximum number of child processes that will be created to serve requests, and limits the number of simultaneous requests that will be served. Any connection attempts that are over the MaxClients limit will normally be queued, up to a number based on the ListenBacklog directive. You should set this to the maximum number of clients that your environment can manage without experiencing throughput degradation or a prohibitive increase of the response time.

 

ExpiresByType Directive

A major performance gain in high latency environments is possible if you add the Mod_Expires Module to the RWP, and modify the web application configuration to utilize the ExpiresByType directive. These directives will reduce the number of round trips from the client browser to the RWP Apache Web server. A web server has the option to tell the browser how long it should cache content. By default, the RWP Apache does not tell the browser anything about when the content should expire, which basically means that the browser determines (through its own heuristic algorithms) when the content will expire. When the browser checks for a new version, it sends a condition get request ("send me a new copy of this file if your copy is newer than mine"). However, since the server is rarely updated it almost always responds with a 304 response, which tells the browser it already has the latest version. All of these 304 requests are essentially wasted requests since there is no new data returned. The ExpiresByType directive may be added to the ClearQuest Web in a future release.

 

Tuning Tomcat

Setting the Servlet Queue Size

The maximum number of concurrent connections that a servlet is allowed to handle should typically be lower than the total number of http threads. This is because not all the requests take the same time to fulfill. Some requests may require a limited amount of computing power, while other HTTP requests may simply need an HTML page. ClearQuest Web includes the Apache and Tomcat versions that support the AJP 1.3 and 1.4 protocols, and the <connector> element of Tomcat's server.xml file tells Tomcat to listen for AJP requests. The maxProcessors attribute of the <connector> element represents the maximum number of request processing threads that this connector can create, which therefore determines the maximum number of simultaneous requests that can be handled. The default value is 75. To change this value, edit the \Rational\Common\rwp\conf\server.xml file

Tuning Tomcat Server Memory

You can configure the available minimum and maximum Java Virtual Machine (JVM) memory used by Tomcat on Windows by modifying the C:\Program Files\Rational\Common\rwp\bin\jk_service.properties file. Modify the section shown below:

#

# JVM Options

#

# Useful Options:

# -Xms2m = Initial heap size, modify for desired size

# -Xmx256m = Maximum heap size, modify for desired size

            

 

For UNIX, modify the JAVA_OPTS definition in the setclasspath.sh script, which is in /opt/rational/common/rwp/bin.

As an example of how much memory you may require, performance tests completed using an example customer schema showed that approximately 400 kilobytes of memory per user was required for the CQ Web application session on the Tomcat servlet engine. The steady state memory usage without any users was approximately 60 megabytes.

 

Garbage Collection

The best way to optimize garbage collection is through testing. You'll want to set the minimum and maximum JVM memory size close to one another, because JVM maximum and minimum memory settings that are too far apart will cause the garbage collector to run less frequently, and will therefore require more time and CPU resources to collect more objects. Garbage collections with a frequency of less than one minute should produce a good result. To determine the duration between garbage collection intervals, measure the time between major decreases in Java process memory.

 

Tuning ClearQuest Server

The ClearQuest Server includes two components: the Request Manager and the Registry Server. The Registry Server is a software load-balancer process that directs requests from the ClearQuest Web application (deployed on the Tomcat servlet engine) to the Request Manager(s). The Request Manager stores a user's ClearQuest session. The Request Manager is responsible for activities like submitting, modifying, viewing, and deleting queries and records in the ClearQuest database.

Threads

A thread is a unit of processing capacity available to perform computing within the JVM. The greater the number of threads the higher the CPU load. In cases where CPU load is high, and the ClearQuest Web application is CPU-bound, the number of threads should be reduced. In cases where CPU usage is low, on the other hand, you can increase the number of threads to handle more user or transaction load. When increasing the number of threads, check to make sure that there is adequate memory available for the Request Manager to handle the additional concurrent load. In order to understand how to modify the ClearQuest Web thread parameters described below, see the Rational ClearQuest Web Administrator's Guide (the Customizing the jtl.properties File section, as well as Table 5, jtl.properties File Locations).

MAXSERVICEREQUESTTHREADS -- This specifies the maximum number of concurrent ClearQuest Web application requests that the Request Manager can process. Although you can increase this value to try to minimize the queued time for multiple requests, the default value for this property is set to five based on the assumption that ClearQuest Web is deployed on a machine with one CPU. This is because testing suggests that this is the optimal number of threads for one CPU. On a single-CPU machine, setting this value to less than five might result in under-utilization of system resources, while increasing it to more than five might result in slight degradation in the response times.

If the ClearQuest Server is deployed on a single-CPU machine, use the default value. If the machine has more than one processor, then modify this setting to five times the number of CPUs, i.e., 5 * #CPUs. For example, if the ClearQuest Server is installed on a four-processor machine, modify this setting to 20.

MAXSERVICERESPONSETHREADS -- this is the number of threads sending responses back to the various requestors. The default value is two, again for a single-CPU machine. This value should be changed to reflect two times the number of CPUs. For example, on a four-CPU machine, this value should be set to eight.

Testing with an example customer schema on a four-CPU server with MAXSERVICEREQUESTTHREADS set to thirty, fourteen simultaneous users successfully preformed a submit action all within thirty seconds. In cases where MAXSERVICEREQUESTTHREADS is not set high enough, you may see errors like Failed to execute use case 'cq_getworkspace_folder'. String index out of range: -1.

 

Time Out

RPCREQUESTTIMEOUTSECOND -- This setting defines the amount of time in seconds that the ClearQuest Web application waits for the Request Manager to processes requests. If the ClearQuest Web application does not receive the response from Request Manager in the time defined by this setting, it times out and notifies the user. The default value for this timeout is set to 90 seconds. Ideally, a request should not require 90 seconds to process. The Request Manager processes most of the requests it receives in just a few seconds. However, there might be some scenarios where the requests take a very long time. For example, a query that is searching for a word in the description area of all the defects might take longer then 90 seconds, and would result in a timeout. Similarly, submitting a defect that has a lot of hooks in it could result in a long processing time on the Request Manager, again resulting in a timeout.

Increasing this setting might provide an easy temporary resolution for the time-out error, but it would be the wrong solution for end users. For example, setting this value to 300 seconds would result in users having to wait five or more minutes for a query or record operation. The right solution is to find which queries, records, or hooks are taking a long time to execute, determine why, and resolve the problem. Ask yourself whether the filter criteria are badly defined and overly complex, or if there are there too many hooks into the record. Settling these types of issues could provide a permanent solution that is more responsive, requires less system resources, and has fewer time-out errors.

 

Request Manager Memory

It is likely that you will have to modify the Request Manager memory to reflect your deployment characteristics. You can configure the available minimum and maximum JVM memory used by the ClearQuest Request Manager by modifying the file named C:\Program Files\Rational\ClearQuest\cqweb\cqserver\ requestmgr_service.properties. For UNIX, modify /opt/rational/clearquest/cqweb/cqserver/start_cqrm.sh Modify the section shown below:

#

# JVM Options

#

# Useful Options:

# -Xms2m = Initial heap size, modify for desired size

# -Xmx256m = Maximum heap size, modify for desired size

            

 

Again as a guideline, testing showed that the ClearQuest Request Manager steady-state memory usage with one user was approximately 60 megabytes. Performance tests done using an example customer schema showed that ClearQuest Request Manager required 5 to 12 megabytes of additional memory for each additional user doing 15 transactions per hour.

Registry Server Memory

It is not likely that you will have to modify the Registry Server memory. Nevertheless, the available minimum and maximum JVM memory used by the ClearQuest Registry Server can be set by modifying C:\Program Files\Rational\ClearQuest\cqweb\cqregsvr\ cqregsvr_service.properties. For UNIX, modify /opt/rational/clearquest/cqweb/cqregsvr/start_cqreg.sh. Modify the section shown below:

 

#
# JVM Options
#
# Useful Options:
# -Xms2m = Initial heap size, modify for desired size
# -Xmx256m = Maximum heap size, modify for desired size
                                              

 

The ClearQuest Registry Server steady state memory usage with one user was approximately 20 megabytes. Performance tests done using an example customer schema showed that for each additional user, ClearQuest Registry Server needed a negligible amount of additional memory.

 

Tuning the Network Configuration

While this paper's intent is not to provide a comprehensive guide for tuning your network, this section will provide information on some quick ways to diagnose network configuration issues that may cause performance problems with the new ClearQuest Web.

Network Latency

Poor network performance may cause performance degradation of any web application. When troubleshooting performance problems with the new ClearQuest Web, you should verify network latency between:

Since the new ClearQuest Web Application installs the Web Server (Apache) and servlet engine Server (Tomcat) on the same server, you don't have to verify item 2. However, this may be applicable in cases where a customer has installed a proxy web server between the web client making the HTTP request and the ClearQuest Web Application Server. These proxy web servers are sometimes used with firewalls for security purposes, or to provide a software load-balancer with multiple ClearQuest Web Clusters.

 

Determining Network Latency

Network latency can be determined by typing the ping command at the starting server and then the name of the target server between which you are trying to determine the latency. You must determine the latency between each server. The results below are from a ping command.

 
ping sus-ma1ratlt2

 
Pinging sus-ma1ratlt2 [9.34.111.60] with 32 bytes of data:
 
Reply from 9.34.111.60: bytes=32 time=125ms TTL=119
Reply from 9.34.111.60: bytes=32 time=127ms TTL=119
Reply from 9.34.111.60: bytes=32 time=125ms TTL=119
Reply from 9.34.111.60: bytes=32 time=126ms TTL=119
Ping statistics for 9.34.111.60:
    Packets: Sent = 4, Received = 4, Lost = 0 (0% loss),
Approximate round trip times in milli-seconds:
    Minimum = 125ms, Maximum = 127ms, Average = 125ms
                                              

 

If the combined network latency between the web client, ClearQuest Web Application, Request Manager, and the Database Server is greater than 200 milliseconds, ClearQuest Web transaction performance can degrade. Note that performance problems associated with ClearQuest Web login are often caused by latency between the Request Manager Server and the Rational Common License Server. In addition, ping statistics revealing packets being lost at a rate greater than 5 percent could also indicate degraded ClearQuest Web transaction performance. Consult your network administrator to resolve network latency and lost packets concerns.

 

Tuning the Rational Common License Server

ClearQuest Web uses the Rational Common License Server based on FlexLM from Globetrotter Software. Rational provides tools to monitor and administer your ClearQuest licenses. One tool is LMTools by Globetrotter Software, which provides License Server status and server diagnostics. To improve the performance of your ClearQuest deployment, ensure that there is good network connectivity between the Request Manager and ClearQuest License Server. As mentioned above, network connectivity should have a latency of less than 200 ms and very few or no dropped packets. Furthermore, performance testing has revealed that each additional license server causes the login transaction response time to reduce an additional four seconds. Also consider co-locating your license server with your Request Manager.

Additional time to check out a license is required at sites that have deployed the new ClearQuest Web with ClearQuest MultiSite. A MultiSite license is checked out when the user logs in. A ClearQuest license, on the other hand, is checked out when the user selects the user database.

Licenses are checked out only once. The ClearQuest Web Application does not have to have network connectivity to the license server, only the Request Manager does.

 

Hardware Sizing for a ClearQuest Web Deployment

Server sizing to meet performance needs is unique to each customer's deployment environment. Performance is highly dependent on a customer's database schema, usage, web server configuration, database configuration, and network configuration. The IBM Software Group does not give customer-specific recommendations for sizing or quantifying how much or what type of hardware a customer needs to meet specific ClearQuest Web transaction load or performance criteria. In order for customers to determine their hardware requirements to deploy ClearQuest Web, they should start with the minimum recommended hardware outlined in the installation guide. Then, they should execute performance tests to determine how many concurrent users can be accommodated while maintaining their desired transaction response times and transaction rates for a single-server environment.

Quantifying the number of concurrent users per server allows you to calculate how many servers you need to meet your anticipated peak concurrent user load. You should add more server capacity to allow for hardware failover or administrative maintenance. The reason for this approach is that one customer may do performance tests with a hardware configuration where they are able to achieve 50 concurrent users with a response time of 10 seconds. Another customer with the same hardware configuration could perform the same tests and determine that to maintain a response time of 5 seconds or less they can't have more than 25 concurrent users. The latter customer will have to buy twice the number of servers to meet their performance requirements. This is why it is important that each customer performs their own performance testing to determine specific hardware needs.

 

Capture Important Hardware Sizing Parameters

To effectively size your ClearQuest Web Application deployment, the following questions should be answered:

Load Model

Here is an example of how to define the average and peak performance requirements for a ClearQuest Web deployment.

Example Load Calculation

Here is an example of how to calculate average and peak transaction rates.

AVERAGE LOAD MODEL

User population                        1500 users
       User profiles       Sessions/day           Transactions/session
       Heavy users           20%                   12                           10
       Light users             80%                    2                             6
% active per day           90% of Heavy users; 70% of Light users
Work Day                     9 hours (all activity evenly distributed)
User session is              20 minutes
 
User Sessions per day is 4,920 = 
       Heavy users 1500 users*20%*12 sessions/day * 90% Active
       Light users 1500 users*80%* 2 sessions/day * 70% Active
Transactions per day is 42,480 =
       Heavy users 1500 users*20%*12 sessions/day * 90% Active * 10 Transactions/session
       Light users 1500 users*80%* 2 sessions/day * 70% Active * 6 Transactions/session
Concurrent users is 182 = (20 * 4,920) / (9 * 60)
Transactions per second           1.31 = (42,480 / 9 hr) * 1hr/60min*1min/60sec

PEAK LOAD MODEL

Concurrent users is 300 = 1500 / 5
Transactions per second 2.16 TPS = 300*(1.31/182)

 

Create and Execute Performance Tests

Based on the ClearQuest Web user requirements and sizing parameters, create a set of performance tests that reflect your environment. Start by configuring a group of ClearQuest Web Application and Request Manager Servers. Establish your monitoring tools and confirm that your testing environment reflects your production deployment environment. Then notify your web server, ClearQuest Server, and database server administrators that you will be executing performance tests. Have them monitor their servers during the performance tests. Gradually add ClearQuest Web user load at a consistent rate (such as one user per minute) and record key performance metrics at consistent time intervals. These include:

Determine Bottlenecks and Tune ClearQuest Components

After executing the performance tests, review the monitoring data to determine which processes become resource constrained. For each such process determine what configuration parameters could improve performance (based on the tuning parameters outlined in the tuning section of this document). Adjust these parameters and execute performance tests again. During this process, you should: