News
Abstract
This document describes how to use the IBM Support Assistant Lite (ISA Lite) for IBM Rational ClearQuest V7.1. This is a tool that provides an automated way for you to gather initial data needed for the Rational support team to analyze problems.
Content
ISA Lite for Rational ClearQuest v7.1 is a customized subset of the IBM Support Assistant Workbench that provides automated data collection capability specific for Rational ClearQuest V7.1. If you do not have IBM Support Assistant Workbench installed and need to provide information for our support team, you can use this to quickly gather information using ISA Lite for Rational ClearQuest V7.1. This package contains data collection tasks for gathering basic ClearQuest web, ClearQuest client data and CM Server related data collection tasks.
Details of what is collected as well as collector walk through are described below.
*Update*: The ISALite collector has been updated to include:
- Capability to handle collection 64 bit systems & Windows 7
- Fix - system event log collection
 | Prerequisites |
| Downloading and Launching ISA Lite |
| Using ISA Lite |
| Collector Overview |
| Details: ClearQuest Web Collectors |
| Details: ClearQuest Client Collectors |
| Data Collector Completion Options & Uploads |
- You need an IBM ID and password to download ISA Lite. Register here if you do not already have one.
- Please use the JAVA JRE that comes with ClearQuest. This is listed here.
Downloading and Launching ISA Lite
- Download ISA Lite for Rational ClearQuest V7.1 from: https://www.ibm.com/services/forms/preLogin.do?source=swg-isalite&S_PKG=isal131rcq
- Extract the .zip file in a folder.
- If your platform does not have unzip utility, you can use jar to unzip file: jar xf ISALiteforRationalClearQuest_7.1_20110923_134.zip
- Open a command prompt, or shell. All information below must be run from the command prompt.
- Change directory: cd <extracted location>/ISALite.
- Windows:
- If Java is available in your path , simply run: runISALite.bat
- If Java is not available on your path, ISA Lite will prompt you for the path. This path should contain a "bin" or a "jre" directory. You can also set JAVA_HOME before running ISA Lite:
- Example: set JAVA_HOME=C:\Program Files\Rational\Common\java
- Once this is completed, run: runISALite.bat or runISALite.bat -console to run in console mode.
- In ksh: chmod a+x *.sh to ensure .sh files in ISALite folder can be executed.
- If Java is available in your path , simply run: ./runISALite.sh
- If Java is not available on your path, ISA Lite will prompt you for the path. This path should contain a "bin" or a "jre" directory. You can also set JAVA_HOME before running ISA Lite:
- Example (in ksh): export JAVA_HOME=/opt/rational/common/java/jre
- If you are running in a desktop environment: ./runISALite.sh
- If you are running in a console / terminal environment: ./runISALite.sh -console
Linux / Unix platforms
Using ISA Lite (non-console mode)
- Select a data collector to run. Details for each collector are listed below.
- Fill in the Filename field.
- Click the Collect Data button to start data collection.
- (Optional) Click on "Show execution details" to see the collector execution details.
- When finished, simply close the window.
Using ISALite (silent option)
To automate ISA collection and/or to run silently, please review the following two documents that discuss performing a silent recording, and a silent playback via command line:
http://www.ibm.com/support/docview.wss?uid=swg27017356
see section : Using ISALite for Remote Collection / "To further simplify ..."
http://www.ibm.com/developerworks/websphere/techjournal/0809_supauth/0809_supauth.html
see : "Silent Collection"
Using this technique you can record an ISA execution, and subsequently playback via command line silently.
Collector Overview
This is a listing of the data collectors included in the package as well as a high level description of its functionality.
| Collector Name | When do you use this collector? |
| General Collectors | |
| Use this collector for general IBM Installation Manager issues. This can be used to collect information when running into install issues on products that leverages IBM Installation Manager as an install platform. Detailed description : Installation Manager Collector |
| Use this collector to gather data for troubleshooting ClearQuest integration issues with Rational Test products. Detailed description: Rational ClearQuest Integration Collector |
| Use this collector to gather data for troubleshooting general CQ web server issues without restarting services. Follow link for more information on: Data gathered by collector and detailed walk thru. |
| Use this collector to gather data for troubleshooting general CQ web server issues with problem recreation, using default trace settings. ClearQuest services will be restarted. Follow link for more information on: Data gathered by collector and detail walk thru. |
| Use this collector to gather data for troubleshooting general CQ web server issues with problem recreation, using customizable trace settings. ClearQuest services will be restarted. Follow link for more information on: Data gathered by collector and detail walk thru. |
| Use this collector for Rational Common Licensing issues. The data collected provides our support team initial information to assess FlexLM licensing issues. Detailed description: Rational FlexLM data collector. |
| Use this collector to gather WinMSD information for our support team. The collector executes msinfo32.exe on windows system and gathers the output. An upload option is provided. This information helps the support team to get a better understanding of user's environment. |
CM Server Collectors | |
| Use this collector to gather data for troubleshooting general issues relating to Change Management Server . This includes change management server configuration, IBM Installation Manager as well as information related to embedded WAS. Its recommended that user run this with administrator privileges. Detailed description: General Change Management Server Collector |
| Use this data collector to gather only change management server configuration information and basic system information. Detailed description: Server Configuration Collector |
| Use this data collector to enable process trace on the Change Management Server. User will be prompted to recreate problems found, and when completed, to continue with the data collection tool to disable trace settings and gather information. Its recommended that the user run this with administrator privileges. This data collector WILL restart the Change Management Server to enable and disable trace settings. Detailed description: Server Processes Trace Collector |
ClearQuest Client Collectors | |
| Use this collector to gather data for troubleshooting general CQ client issues without problem recreation. Follow link for more information on: Data gathered by collector and detailed walk thru |
| Use this collector to gather data for troubleshooting general CQ client issues with problem recreation, using default trace settings. The collector will enable ClearQuest core trace with default settings and prompt for problem recreation. When completes, data is gathered and trace is disabled. Follow link for more information on: Data gathered by collector and detailed walk thru |
| Use this collector to gather data for troubleshooting general CQ client issues with problem recreation, using customizable trace settings. The collector will enable ClearQuest core trace with settings provided and prompt for problem recreation. When completes, data is gathered and trace is disabled. Follow link for more information on: Data gathered by collector and detailed walk thru |
Details: Rational ClearQuest Web Collectors
The Rational ClearQuest Web collectors enables a user to automatically gather the data specified by MustGather ClearQuest Web 7.1 Server . Three collection options are provided.
Basic collection without trace or problem recreation: Collection with trace enablement for problem recreation:
- IMPORTANT: For the above collectors, ClearQuest Web Services will be restarted.
- You'll need to run these collectors with appropriate permissions to restart server services
- You'll need to have appropriate permission to update:
- Windows: Registry - to enable core trace settings.
- Linux / Unix : ClearQuest web services start up files.
Data Collected for Rational ClearQuest Web Collectors
This set of collector gathers the following data.
- Basic system information :
- A subset of Installation Manager information.
- Windows: Registry information, system Event logs, mem and systeminfo.
- Linux or Unix System
- uname -a
- umask
- df - m
- env
- ps -aef
- For OS mem information:
- Linus: free -m
- AIX: bootinfo –r
- SunOS/Solaris: /usr/sbin/prtconf | grep "Memory size"
- Linux/Unix Specific ClearQuest information
- ClearQuest web 7.1 server basic info and logs
- <product_install>/common/CM
- <product_install>/common/CM/bin
- <product_install>/common/CM/profiles/cmprofile directory.
- CM/profiles/cmprofile/eWASportDefs.props CM/profiles/cmprofile/installedApps/*/RationalClearQuestWeb.ear/CQWebModule.war/WEB-INF/classes/*.properties
- CM/profiles/cmprofile/installedApps/*/RationalClearQuestWeb.ear/CQWebModule.war/WEB-INF/config/*.pref
- CM/profiles/cmprofile/config/cells/*/nodes/*/servers/server1/server.xml
- CM/profiles/cqsearchprofile/eWASportDefs.props
- CM/bin/tslogger.properties
- IHS/conf/*.conf
- eWAS/profiles/plugin-cfg.xml
- cmprofile/logs
- cqsearchprofile/logs
- reportalprofile/logs
- <product_install>/common/CM
- <product_install>/common/CM/bin
- <product_install>/common/CM/profiles/*
| Folder | File | Description |
| /IM/InstallationManager | *.* | Basic installation information only. Files: installed.xml, installRegistry.xml, installed.xsd, and installed.xsl |
| Folder |
| Description |
| / | regfile.rational.software.export.txt | Registry export of key: [HKEY_LOCAL_MACHINE\SOFTWARE\Rational Software] |
| regfile.rational.software.export_ANALYSIS.txt | Listing of product entries listed under registry key: [HKEY_LOCAL_MACHINE\SOFTWARE\Rational Software] | |
| regfile.sware.uninstall.export.txt | Registry export of key: [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall] | |
| regfile.sware.uninstall.export_ANALYSIS.txt | Listing of product entries and version in above key that contains "Publisher"="Rational Software" | |
| win_mem_out.txt | Output of mem | |
| win_systeminfo_out.txy | Output of systeminfo | |
| /system_info | *.* | System event files |
| Folder |
| Description |
| / | Linux_UnixSystemInfo.txt | Gathers output from the following execution: |
| Folder | File | Description |
| /CQDB_registry | *.* | ClearQuest DB registry information. Collect if available. |
| Folder | File | Description |
| / | PHD_DMP_Files_NOT_found.txt or PHD_DMP_Files_Found.txt | Indication of whether .dmp or .phd files were found in the following directories: |
| /CM_profile_property_ and_preferences | *.* | Collects information relating to configuration information from <product_install>/common directory: These are: |
| /dat_files_common_ CM_profiles_cmprofile _config_cells | *.dat files | Collect all the *.dat files from: <product_install>/common/CM/profiles/cmprofile/config/cells/*/stp/*.dat |
| CM_MBeans_Config_Dat_File_List.txt or CM_MBeans_Config_Dat_Not_Found.txt | Information to indicate whether any *.dat files were available. | |
| /opt or /Program File or <product_install> /common | *.log, *.log.*, *.stderr, *.stdout, *.txt | Collects logs from <product_install>/common/eWAS and IHS directory. By default, <product_install> are :
Linux/Unix: /opt/IBM/RationalSDLC |
| /log_files_common_ CM_profiles | *.* | Collect log directories from <product_install>/CM/profiles directory, excluding *.dmp and *.phd files. Directory paths collected are: |
| /Java_core_from_CM | *.* | Collects javacore*.txt from the following directories if they exists: |
- ClearQuest web 7.1 trace output.
- Windows: C:/cq_trace.log
- Linux/Unix: /tmp/cq_trace.log
- Windows: In the enable registry file, look for entry "output"
- Linux/Unix: In the "after/cqrpc.sh" file, look for file specified by CQ_DIAG_OUTPUT
NOTE: existing logs of similar patterns are also collected.
| Folder | File | Description |
| / or /tmp or <user_specified> | cq_trace.log* | Trace output. By default, trace output are set to NOTE: If the user had specified a different location or file name, then that information is used to gather the trace output. To determine where the trace output is located, please see /trace_settings/enable/*.*. |
- ClearQuest web 7.1 data relating to enabling and disabling trace setting.
These set of data are specific to the Rational ClearQuest Web General Collector and the Customized Trace collector only.
| Folder | File | Description |
| LOCATION_OF_PREVIOUS_LOGS.txt | This file contains the location of the target log directory in which old logs are moved to. This is available only If the user has indicated to move the logs during problem recreation. | |
| 1_Pre_Trace_enable_CMServer_stop _all_services.txt | Execution log of stop services before tracing is enabled. | |
| 2_Post_Trace_enable_CMServer _ start_services_nofulltextsearch.txt | Execution log of start services after trace settings has been set. | |
| 3_Post_Trace_enable_CMServer _ stop_services_nofulltextsearch.txt | Execution log of stop services after trace settings has been set, and the user has finished problem recreation. | |
| 4_Post_Trace_disable_CMServer _ start_all_services.txt | Execution log of start service after trace settings has been disabled. | |
| /trace_settings /enable | *.* | Trace settings used to enable trace . On Linux/Unix system - this also captures the start up file "before" trace enable, "after" trace enable. |
| /trace_settings /disable | *.* | Trace settings used to disable trace. On Linux/Unix system - this also captures the start up file "before" trace is being disabled, "after" trace is disabled. |
Detailed Walk Thru for Rational ClearQuest Web General Collector - No Service Restart
- This collector gathers the above data without enabling/disabling trace settings.
Introduction
The collector will first inform you what it is going to collect. Click OK, to proceed
Click OK to continue.
The collector will run to completion and request feedback and ftp options.
Please continue to Data Collector Completion Options & Uploads for additional information.
Detailed Walk Thru for Rational ClearQuest Web General Collector
- If you like the logs to be moved - provide a directory location in which you have write permission, and select "OK".
- If you do not want the logs to be moved - select "Skip"
Introduction
The collector will first inform you what it is going to collect. Click OK, to proceed
Prompt: Move Existing Logs
This prompt is available for Rational ClearQuest Web General Collector and Rational ClearQuest Web - Customized Trace Collector . This allows old trace and log files to be moved to a target directory. Logs will be moved once the collector is ready to restart ClearQuest services.
Prompt : ClearQuest Web Service has been Enabled & Please Recreate the ClearQuest Web Server Issue
This is to let you know that ClearQuest Web Services has been enabled.
Please recreate the problem you have encountered. Click OK to continue with disabling trace.
The collector will run to completion and request feedback and ftp options.
Please continue to Data Collector Completion Options & Uploads for additional information.
Detailed Walk Thru for Rational ClearQuest Web - Customized Trace Collector
- Enable CQ CoreTrace field: provide a registry file that contains the appropriate trace settings. By default, a general trace setting registry file has been provided.
- Disable CQ CoreTrace field: provide a registry file that resets the trace settings. By default, a general trace disable setting registry file has been provided.
Introduction
The collector will first inform you what it is going to collect. Click OK, to proceed
Provide your trace settings
- Windows:
Select OK to continue.
Linux/Unix :
In each field, provide the appropriate settings for these environment variables to be set within cqrpc.sh By default, these are settings for the general web server issues.
Note: blanks or "" are not accepted.
Please continue to Data Collector Completion Options & Uploads for additional information.
Details: ClearQuest Client Collectors
This is a set of collectors that gatherers data that is relevant for debugging ClearQuest client application issues. The user has the option to only collect information, or to enable trace for problem reproduction. Three collection options are listed below.
Basic collection without trace or problem recreation: Collection with trace enablement.
- Rational ClearQuest Client - General Trace Collector
- Rational ClearQuest Client - Customized Trace Collector
Data Collected by ClearQuest Client Collectors
This set of collector gathers the following data relevant to troubleshooting ClearQuest client issues.
- Basic system information as specified above
- ClearQuest client 7.1 trace output.
- Windows: C:/cq_trace.log
- Linux/Unix: /tmp/cq_trace.log
- Windows: In the enable registry file, look for entry "output"
- Linux/Unix : Look for a directory that does not match the list of directories below.
- ClearQuest Client RCP information
| Folder | File | Description |
| / or /tmp or <user_specified> | cq_trace.log* | Trace output. By default, trace output are set to NOTE: If the user had specified a different location or file name, then that information is used to gather the trace output. To determine where the trace output is located, please see /trace_settings/enable/*.*. |
| Folder | File | Description |
| /ClearQuest_RCP | *.* | Gathers information relating to clearquest rcp product. These includes product configuration information and log, and <product_install>/rcp/clearquest.ini file. |
- Basic ClearQuest web 7.1 server configuration if found on same system.
- CM/profiles/cmprofile/eWASportDefs.props CM/profiles/cmprofile/installedApps/*/RationalClearQuestWeb.ear/CQWebModule.war/WEB-INF/classes/*.properties
- CM/profiles/cmprofile/installedApps/*/RationalClearQuestWeb.ear/CQWebModule.war/WEB-INF/config/*.pref
- CM/profiles/cmprofile/config/cells/*/nodes/*/servers/server1/server.xml
- CM/profiles/cqsearchprofile/eWASportDefs.props
- CM/bin/tslogger.properties
- IHS/conf/*.conf
- eWAS/profiles/plugin-cfg.xml
| Folder | File | Description |
| /CM_profile_property_ and_preferences | *.* | Collects information relating to configuration information from <product_install>/common directory: These are: |
| /dat_files_common_ CM_profiles_cmprofile _config_cells | *.dat files | Collect all the *.dat files from: <product_install>/common/CM/profiles/cmprofile/config/cells/*/stp/*.dat |
| CM_MBeans_Config_Dat_File_List.txt or CM_MBeans_Config_Dat_Not_Found.txt | Information to indicate whether any *.dat files were available. |
- ClearQuest client data relating to enabling and disabling trace setting.
These set of data are specific to the Rational ClearQuest Client - General Trace Collector and the Customized Trace Collector only.
| Folder | File | Description |
| /trace_settings /enable | *.* | Trace settings used to enable trace . On Linux/Unix system - this also captures the start up file "before" trace enable, "after" trace enable. |
| /trace_settings /disable | *.* | Trace settings used to disable trace. On Linux/Unix system - this also captures the start up file "before" trace is being disabled, "after" trace is disabled. |
Detailed Walk Thru for Rational ClearQuest Client General Collector
- This collector gathers all above data without enabling/disabling trace settings.
- Introduction
The collector will first inform you what it is going to collect. Click OK, to proceed
Click OK to continue. The collector will run to completion and request feedback and ftp options.
Please continue to Data Collector Completion Options & Uploads for additional information.
Detailed Walk Thru for Rational ClearQuest Client - General Trace Collector
- This collector gathers all above data and will enable trace with default trace settings. Collection happens after trace has been disabled.
- Introduction
- The collector will first inform you what it is going to collect. Click OK, to proceed
- Problem Recreation.
- Select 'OK' once you've provided the full path to the ClearQuest client program.
- Select 'Skip' if you would like to skip this step. This would mean you will not be able to gather problem recreation data through this collector tool.
- Prompt: Please close all instances of ClearQuest Clients.
Before trace settings is enabled, all instances of ClearQuest Client needs to be closed. Once you have completed that task, click OK to proceed.
Launching ClearQuest client for problem recreation:
Due to difference in how environment and trace settings are enabled on Windows and Linux / Unix systems, a different set of instruction is provided.
- Windows
At this point, ClearQuest client trace has been enabled. You'll need to launch the ClearQuest Client you have an issue with and recreate the problem you had encountered.
Click OK once you've done so.
- Linux/Unix
The collector will require that you provide a path referencing the ClearQuest client program you are having issues with. This allows the collector to launch the client you've specified with the debug trace settings you've provided.
At this point, the collector will attempt to launch your script with appropriate trace settings enabled in the environment. Please re-create your problem with the client program that has been launched by the tool. Click on OK when you've completed problem recreation.
Example shown here indicates the parameters that were provided by default.
- Prompt: Complete problem recreation
This asks you to close the client program that you (or the collector) had launched.
Click 'OK' to continue and disable trace settings.
Please continue to Data Collector Completion Options & Uploads for additional information.
Detailed Walk Thru for Rational ClearQuest Client - Customized General Collector
This collector gathers all above data and will enable trace with user provided trace settings. Collection happens after trace has been disabled.
- Enable CQ CoreTrace field: provide a registry file that contains the appropriate trace settings. By default, a general trace setting registry file has been provided.
- Disable CQ CoreTrace field: provide a registry file that resets the trace settings. By default, a general trace disable setting registry file has been provided.
Introduction
- The collector will first inform you what it is going to collect. Click OK, to proceed
Provide your trace settings
- Windows:
Linux/Unix :
In each field, provide the appropriate settings for these environment variables. These will enable trace for the ClearQuest client, when launched with these environment settings. By default, these are settings for the general client issues. NOTE: blanks or "" are not accepted.
Please continue to Data Collector Completion Options & Uploads for additional information.
Data Collector Completion Options & Uploads
When the collector is completed, it will request feedback about ISA. Select Yes, to provide feedback. Select No to continue.
You'll also be provided with data upload options. This will allow you to send the collected data to IBM or another location via FTP or HTTPS.
IMPORTANT: To upload information to IBM, you'll need to have a PMR number. This is obtained when you work with our support team. If you do not have a PMR number, but do have support contract, you can leverage the Software Support page to open a service request and included the collected data with the service request.
IBM Service Request Page: https://www.ibm.com/support/servicerequest/
The upload options are:
- Send the Logs to IBM using secure transfer (HTTPS). You'll need an PMR number to transfer the data to IBM. This sends the collected data to IBM Support team through the HTTPS protocol.
- FTP the Logs to IBM Support (unencrypted). You'll need an PMR number to transfer the data to IBM. This sends the collected data to IBM Support team through the FTP protocol. This is a less secure option.
- FTP the Logs to a Different Location (unencrypted) This allows you to send the collected data to another location via FTP. You'll need to provide the target FTP location and appropriate authentication to access it.
- Do Not FTP the Logs. Do nothing.
Click OK to continue. If you choose options other than Do Not FTP the Logs above, you will need to fill in additional information required to complete the upload.
When the collector completes, the .zip file is created at the location specified in Output File name. You can use any unzip tool to extract the files to examine the content of collected data.
Related Information
[{"Product":{"code":"SSSH5A","label":"Rational ClearQuest"},"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Component":"IBM Support Assistant","Platform":[{"code":"PF016","label":"Linux"},{"code":"PF033","label":"Windows"}],"Version":"7.1","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}}]
Was this topic helpful?
Document Information
Modified date:
23 June 2018
UID
swg21407905