IBM Support

IBM Support Assistant Lite for Rational ClearQuest 7.0

News


Abstract

This document describes how to use the IBM Support Assistant Lite (ISA Lite) for IBM Rational ClearQuest 7.0. 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 7.0 is a customized subset of the IBM Support Assistant Workbench that provides automated data collection capability specific for Rational ClearQuest 7.0. If you do not have IBM Support Assistant Workbench installed and need to provide information for our support team, you can use this tool to quickly gather information using ISA Lite for Rational ClearQuest 7.0

*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
Data Collection Options
Details: Rational ClearQuest Web Collectors
Details: Rational ClearQuest Client Collectors
Data Collector Completion Options & Uploads


Prerequisites

  • 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 information is listed: here.

Downloading and Launching ISA Lite
  1. Download ISA Lite for Rational ClearQuest 7.0 from: https://www.ibm.com/services/forms/preLogin.do?source=swg-isalite&S_PKG=isalrcq70
  2. 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.0_20110923_134.zip
  3. Open a command prompt, or shell. All information below must be run from the command prompt.
  4. Change directory: cd <extracted location>/ISALite.
    Windows:
    1. If Java is available in your path , simply run: runISALite.bat
    2. 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.

    Linux / Unix
    1. In ksh: chmod a+x *.sh to ensure .sh files in ISALite folder can be executed.
    2. If Java is available in your path , simply run: ./runISALite.sh
    3. 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
      • If you are running in a desktop environment: run: ./runISALite.sh
      • If you are running in a console / terminal environment, run: ./runISALite.sh -console


Using ISA Lite (non-console mode)
  1. Select a data collector to run. Details for each collector are listed below.
  2. Fill in the Filename field.
  3. Click the Collect Data button to start data collection.
  4. (Optional) Click on "Show execution details" to see the collector execution details.
  5. When finished, simply close the window.

Example:
    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.


    Data Collection Options

    This is a listing of the data collectors included in the package as well as a high level description of its functionality.
    Collector NameWhen do you use this collector?
    • Rational ClearQuest Integration Collector
    		Use this collector to gather data for troubleshooting ClearQuest integration issues with Rational Test products. Detailed description: Rational ClearQuest Integration Collector
    • Rational ClearQuest Web General Collector - No Service Restart
    		Use this collector to gather data necessary to debug general CQ web server problem without restarting services. Follow link for more information on: Data gathered by collector and detail walk thru.
    • Rational ClearQuest Web General Collector
    		Use this collector to gather data necessary to debug general CQ web core server problem. Services will be restarted to enable CQ core trace. Follow link for more information on: Data gathered by collector and detailed walk thru
    • Rational ClearQuest Web General Performance Issues Collector
    		Use this collector to gather data necessary to debug general CQ web server performance issues. Services will be restarted to enable CQ core trace specific to performance issues. The enablement settings are as follows:
      Windows

      "Trace"="mains;db_connect=2;sql=2;throw;edit;session;mutex;api;resultset;edit;email;perl;vbasic"
      "Report"="diag_flags=-1;MESSAGE_INFO=0xFFFF"
      "output"="c:\\cq_trace.log"


      Linux

      CQ_DIAG_TRACE="MAINS;DB_CONNECT=2;SQL=2;EDIT;SESSION;MUTEX;API;RESULTSET;EDIT;EMAIL;PERL;VBASIC;"
      CQ_DIAG_REPORT="MESSAGE_INFO=0x070B;DIAG_FLAGS=-1"
      CQ_DIAG_OUTPUT="/tmp/cq_trace.log"

    Follow link for more information on: Data gathered by collector and detail walk thru.
    • Rational ClearQuest Web Database Connection Issues Collector
    		Use this collector to gather data necessary to debug general CQ web server database connection issues. Services will be restarted to enable CQ core trace specific to database connection issues. The enablement settings are as follows:
      Windows

      "Trace"="db_connect=3;sql=2;throw;db_misc;mains"
      "Report"="diag_flags=-1;MESSAGE_INFO=0x40B"
      "output"="c:\\cq_trace.log"


      Linux

      CQ_DIAG_TRACE="DB_CONNECT=3;SQL=2;THROW;DB_MISC;MAINS;"
      CQ_DIAG_REPORT="MESSAGE_INFO=0x070B;DIAG_FLAGS=-1"
      CQ_DIAG_OUTPUT="/tmp/cq_trace.log"

    Follow link for more information on: Data gathered by collector and detail walk thru.
    • Rational ClearQuest Web - Customized Trace Collector
    		Use this collector to gather data necessary to debug CQ web server issues, providing capability to set customized trace setting. Services will be restarted. Follow link for more information on: Data gathered by collector and detailed walk thru
    • Rational ClearQuest Client General Collector
    		Use this collector to gathers data necessary to debug general CQ client issues without problem recreation. Follow link for more information on: Data gathered by collector and detailed walk thru.
    • Rational ClearQuest Client - General Trace Collector
    		Use this collector to gathers data necessary to debug general CQ client issues with problem recreation using default trace settings. The collector will enable ClearQuest core trace 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.
    • Rational ClearQuest Client - Customized Trace Collector
    		Use this collector to gathers data necessary to debug general CQ client issues with problem recreation using customizable trace settings. The collector will enable ClearQuest core trace 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.
    • FlexLM Collector
    		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.
    • WinMSD Collector (Windows Only)
    		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.

    At the end of the data collection, you'll have an option to upload the data collected to IBM if you have a PMR available. Please see Data Collector Completion Options & Uploads for additional information.


    Details: Rational ClearQuest Web Collectors

    The Rational ClearQuest Web collectors enables a user to automatically gather the data specified by MustGather ClearQuest Web Server. Additionally, this tool also gathers system information that can help our support engineers with troubleshooting ClearQuest web issues. Five collection options are provided.

    Basic collection without trace or problem recreation: Collection with trace enablement for problem recreation
    Data Collected by Rational ClearQuest Web Collectors

    Listing of data collected by the set of Rational ClearQuest Web Collectors.
    • Basic system information
      • A subset of Installation Manager information. This is relevant when you have other Rational products installed.
        • FolderFile Description
        /IM/InstallationManager*.*Basic installation information only. Files: installed.xml, installRegistry.xml, installed.xsd, and installed.xsl
        If Installation Manager is not found, file: Installation_Manager_NOT_FOUND.txt is create to log this information.
      • Windows: Registry information, system Event logs, mem and systeminfo.
        • Folder
          File
        		Description
        /regfile.rational.software.export.txtRegistry export of key: [HKEY_LOCAL_MACHINE\SOFTWARE\Rational Software]

        		regfile.rational.software.export_ANALYSIS.txtListing of product entries listed under registry key: [HKEY_LOCAL_MACHINE\SOFTWARE\Rational Software]

        		regfile.sware.uninstall.export.txtRegistry export of key: [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall]

        		regfile.sware.uninstall.export_ANALYSIS.txtListing of product entries and version in above key that contains "Publisher"="Rational Software"

        		win_mem_out.txtOutput of mem

        		win_systeminfo_out.txyOutput of systeminfo
        /system_info*.*System event files
      • Linux or Unix System
        • Folder
          File
        		Description
        /Linux_UnixSystemInfo.txtGathers output from the following execution:
        • 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
        • FolderFile Description
        /CQDB_registry*.*ClearQuest DB registry information. Collect if available.

    • ClearQuest configuration and log files specified by MustGather ClearQuest Web Server.
      • FolderFile Description
      /<product_install>*.*Configuration and logs gathered from the <product_install> directory.
    • ClearQuest web trace output.

      • NOTE: existing logs of similar patterns are also collected.
      FolderFile Description
      / or
      /tmp or
      <user_specified>      		cq_trace.log* Trace output.
      By default, trace output are set to
      • Windows: C:/cq_trace.log
      • Linux/Unix: /tmp/cq_trace.log

      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/*.*.
      • Windows: In the enable registry file, look for entry "output"
      • Linux/Unix: In the "after/start_cqreg.sh" file, look for file specified by CQ_DIAG_OUTPUT
    • ClearQuest web data relating to enabling and disabling trace setting.

      • These set of data are specific to the trace enabling collectors.
      FolderFile Description
      /LOCATION_OF_PREVIOUS_LOGS.txtThis 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.
      /trace_settings
      /enable      		*.*Trace settings used to enable trace . Listing includes:
      • Logging.xml files before and after trace enablement.
      • Windows: registry file that enables trace
      • Linux/Unix system: start_cqreg.sh files before and after trace enablement in directories "before" and "after"
      /trace_settings
      /disable      		*.*Trace settings used to disable trace . Listing includes:
      • Logging.xml files before and after trace is disabled.
      • Windows: registry file that disables trace
      • Linux/Unix system: start_cqreg.sh files before and after trace is disabled in directories "before" and "after"


    Detailed Walk thru for Rational Web General Collector - No Service Restart
      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.

      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 the Web General Collector , Performance Collector and Data Connections Issues Collector.
      This set of collectors will restart ClearQuest web services to enable trace settings, specified by the individual collectors. User is then asked to recreate the problem they had encountered. Once the problem recreation is completed, trace is disabled and the data listed above are gathered.

      Introduction
        The collector will first inform you what it is going to collect. Click OK to proceed.


      Problem Recreation
        Prompt: Move Existing Logs
        This prompt is available for Rational ClearQuest Web collectors that enables trace. 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.
        • Select 'OK' - If you like the logs to be moved - provide a directory location in which you have write permission.
        • Select 'Skip' - If you do not want the logs to be moved.

        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 complete problem recreation. When you are finished, click OK and this will disable trace, and data collection will start. 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
      This collector will restart ClearQuest web services to enable trace settings that are provided by the user. User is then asked to recreate the problem they had encountered. Once the problem recreation is completed, trace is disabled and the data listed above are gathered.

      Introduction


      The collector will first inform you what it is going to collect. Click OK, to proceed

      Provide your trace settings

        Windows:
        • 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.

        Select OK to continue.

        Linux/Unix :
        In each field, provide the appropriate settings for these environment variables to be set within start_cqreg.sh By default, these are settings for the general web server issues.
        NOTE: blanks or "" are not accepted.

    The rest of the steps follows the Problem Recreation step for the Rational ClearQuest Web General Collector. User are prompted to first move their existing log files and re-create the problem. The collector will run to completion and request feedback and ftp options.

    Please continue to Data Collector Completion Options & Uploads for additional information.


    Details: Rational ClearQuest Client Collectors

    The Rational ClearQuest Clients collectors enables a user to automatically gather the basic system information and ClearQuest RCP data that will provide initial diagnostic information for the Rational support team. There are three collection options.

    Data Collected by Rational ClearQuest Web Collectors
    • Basic system information as stated above.
    • If on the same system - configuration files specified by MustGather ClearQuest Web Server. NOTE: This does not include the log files.
    • ClearQuest Client RCP information
      • FolderFile Description
      /ClearQuest_RCP*.*Gathers information relating to clearquest rcp product. These includes product configuration information and ini files.
    • ClearQuest client 7.0 trace output.
      • FolderFile Description
      / or
      /tmp or
      <user_specified>      		cq_trace.log* Trace output.
      By default, trace output are set to
      • Windows: C:/cq_trace.log
      • Linux/Unix: /tmp/cq_trace.log

      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/*.*.
      • Windows: In the enable registry file, look for entry "output"
      • Linux/Unix: In the "after/start_cqreg.sh" file, look for file specified by CQ_DIAG_OUTPUT
    • ClearQuest web data relating to enabling and disabling trace setting.

      • These set of data are specific to the trace enabling collectors.
      FolderFile Description
      /trace_settings
      /enable      		*.*Windows registry file that enables trace is recorded.
      /trace_settings
      /disable      		*.*Windows registry file that disable trace settings is recorded.

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


        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.

    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 - 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.
      Introduction
      The collector will first inform you what it is going to collect. Click OK, to proceed

      Provide your trace settings

        Windows:
        • 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.


        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.

    The rest of the walk through continues from Problem Recreation step in which user are the prompted to first move their existing log files and re-create the problem. The collector will run to completion and request feedback and ftp options.

    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

    IBM Support Assistant Forum

    [{"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.0.1","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}}]

    Document Information

    Modified date:
    23 June 2018

    UID

    swg21409491

    Page Feedback