IBM Support

IBM Support Assistant Lite for Rational ClearQuest v7.1

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

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


Downloading and Launching ISA Lite
  1. Download ISA Lite for Rational ClearQuest V7.1 from: https://www.ibm.com/services/forms/preLogin.do?source=swg-isalite&S_PKG=isal131rcq
  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.1_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 platforms
    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/jre
      • If you are running in a desktop environment: ./runISALite.sh
      • If you are running in a console / terminal environment: ./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.



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 NameWhen do you use this collector?
General Collectors
  • Installation Manager Collector
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
  • 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 for troubleshooting general CQ web server issues without restarting services. Follow link for more information on: Data gathered by collector and detailed walk thru.
  • Rational ClearQuest Web General Collector
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.
  • Rational ClearQuest Web - Customized Trace Collector
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.
  • 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.

CM Server Collectors

  • General Change Management Server Collector
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
  • Server Configuration Collector
Use this data collector to gather only change management server configuration information and basic system information. Detailed description: Server Configuration Collector
  • Server Processes Trace 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

  • Rational ClearQuest Client General Collector
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
  • Rational ClearQuest Client - General Trace Collector
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
  • Rational ClearQuest Client - Customized Trace Collector
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.
      • 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 web 7.1 server basic info and logs
    • FolderFile Description
      /PHD_DMP_Files_NOT_found.txt or PHD_DMP_Files_Found.txtIndication of whether .dmp or .phd files were found in the following directories:
      • <product_install>/common/CM
      • <product_install>/common/CM/bin
      • <product_install>/common/CM/profiles/cmprofile directory.
      /CM_profile_property_
      and_preferences
      *.*Collects information relating to configuration information from <product_install>/common directory:

      These are:
      • 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
      /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, *.txtCollects logs from <product_install>/common/eWAS and IHS directory.
      By default, <product_install> are :
        Windows: /Program File/IBM/RationalSDLC/common
        Linux/Unix: /opt/IBM/RationalSDLC
      But, if user has non default ClearQuest install location, the top level path to the log files will be base off user's no default install path.
      /log_files_common_
      CM_profiles
      *.*Collect log directories from <product_install>/CM/profiles directory, excluding *.dmp and *.phd files.
      Directory paths collected are:
      • cmprofile/logs
      • cqsearchprofile/logs
      • reportalprofile/logs
      /Java_core_from_CM*.*Collects javacore*.txt from the following directories if they exists:
      • <product_install>/common/CM
      • <product_install>/common/CM/bin
      • <product_install>/common/CM/profiles/*
    • ClearQuest web 7.1 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/cqrpc.sh" file, look for file specified by CQ_DIAG_OUTPUT
    • 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.
      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.

      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


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

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


        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

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

    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.
    • 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 : Look for a directory that does not match the list of directories below.
    • ClearQuest Client RCP information
    • FolderFile 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.
    • FolderFile Description
      /CM_profile_property_
      and_preferences
      *.*Collects information relating to configuration information from <product_install>/common directory:

      These are:
      • 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
      /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.
      FolderFile 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.
        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.

    [{"Product":{"code":"SSSH5A","label":"Rational ClearQuest"},"Business Unit":{"code":"BU004","label":"Hybrid Cloud"},"Component":"IBM Support Assistant","Platform":[{"code":"PF016","label":"Linux"},{"code":"PF033","label":"Windows"}],"Version":"7.1","Edition":""}]

    Document Information

    Modified date:
    23 June 2018

    UID

    swg21407905