Collecting performance data using command-line scripts

About this task

The command-line data collection scripts allow a Hotspots Detection or System Scorecard Activity to be run without the client GUI, instead creating an output file that can later be imported into the GUI. This can be useful for scripted or automated data collection, or on a machine that does not have the Rational Developer for AIX and Linux Performance Advisor server component installed.

For example, if a product developed with Rational Developer for AIX and Linux experiences a performance problem by a customer, the development team may distribute the collection scripts to the customer so that they may run the data collection on the exact system where the problem was encountered. The scripts are also designed to be easy to integrate into existing launch or test processes so a team developing with Rational Developer for AIX and Linux could integrate the scripts into a nightly build process to collect performance data from the latest build.

This task describes how to create a bundle containing the scripts and required tools for a specific target system, how to unpack that bundle on the target system, how to use the scripts to run activities, and how to import the results back into Rational Developer for AIX and Linux Performance Advisor.

As with the client GUI, you may profile on a runtime system that is not the same as the system where you build your source code. In this case, you will need two bundles, one for the runtime host and one for the build host, and you will need to run the script on each system. Follow the steps below once for the build system, and again for the runtime system. On the build system, use the -B option when running the scripts; on the runtime system, use the -R option.

Procedure

  1. Create a command-line data collection bundle. The data collection scripts and tools are specific to a type of target system, and the messages that may be displayed when the scripts are run are specific to a language and a character encoding on the remote system, so you must create a bundle appropriate for the system where you intend to use it. To create the bundle from the client:
    1. Click the File menu and choose Export...
    2. In the Export dialog, in the Performance Advisor category select Command-line Data Collection Bundle and click Next to bring up the Create and export a command-line data collection bundle wizard
      Create and export a command-line data bundle wizard
    3. If you have an existing remote connection to the target system where you will be collecting data, select Existing Connection and choose the connection from the dropdown. If you do not have a remote connection, chose Other System and then select the remote system type and character encoding used on the remote system. With an existing connection, the system type and encoding can be determined automatically. For other systems, the System Type must be selected from the dropdown. A bundle created for a one system type (for example, AIX) will not work on other system types (for example, Linux). When using the scripts, they will be run as some user on the target system. For messages from the scripts to be correctly displayed, they must be encoded the same way as that user. If you are unsure about the correct encoding, log into the target system as the user who will run the scripts, and run the command locale charmap, then select the resulting encoding from the System file encoding dropdown.
    4. Select a location to save the bundle. The bundle can be saved to a local file by choosing Local file, or directly to a remote system by choosing Remote file.
    5. Click Finish
  2. Unpack the bundle on the target system If you did not save the bundle directly to the target system, copy it there using the utilities you normally use to transfer files, for example ftp or ssh. The bundle is a .zip file and can be unpacked with the unzip or jar commands. If you do not have either command on the target system, you may need to unpack the bundle before moving it to the target machine. Copy the bundle to the directory where you want to unpack the scripts, change to that directory and upack it with the command unzip bundle.zip or jar xvf bundle.zip which will create a directory named pa-tools that will contain the collection scripts and their required utilities.
  3. Run the activity scripts In the pa-tools directory there are two activity scripts, pa-hotspots.sh which is collects data for a Hotspot Detection activity and pa-scorecard.sh which collects data for a System Scorecard activity. Both scripts are invoked in a similar way and share some common options, and both normally produce a .par file that contains the collected data or error messages if the data could not be collected.

    To collect data for a Hotspot Detection activity, change directory to where you would normally run the application you wish to profile, and run the command /bin/sh dir/pa-tools/pa-hotspots.sh [options] application [application args] where dir is the directory where you unpacked the scripts, options are common options or options for the pa-hotspots.sh script, application is the command you would use to run your application and application args are any command-line arguments you pass to your application.

    To collect data for a System Scorecard activity, run the command /bin/sh dir/pa-tools/pa-scorecard.sh [options] where dir is the directory where you unpacked the scripts, options are common options or options for the pa-scorecard.sh script.

    Table 1. Script options. Options for the scripts. Most options correspond with similar functionality in the GUI.
    Common Options
    Option Description
    -A activityname Display activityname as the activity name when the results are imported. Equivalent to setting the activity name in the activity wizard in the GUI.
    -B Collect build-side data. If your application is built on one system but you want to profile it on another, use this option with the script on the system where the application is built. The default is to collect both build-side and run-side data. See also -R.
    -b builddir The builddir is the directory where your application source is stored and built. This will be used if you are collecting build-side data and corresponds to the project directory in the GUI.
    -C configfile Use configfile as a configuration file for the run. Configuration files set variables corresponding to command-line options.
    -D workdir The directory workdir will be used to store temporary data. Equivalent to the temporary data directory set in the session wizard in the GUI.
    -j jredir A JRE home directory. equivalent to an entry in the table of JRE locations in the session wizard in the GUI. Only used if -N is used with a value greater than 0. If you have multiple JRE locations, -J may be more convenient.
    -J jredirfilelist The path to a file which lists, one per line, JRE home directories. Only used if -N is used with a value greater than 0. Equivalent to multiple -j options.
    -m module An executable or a shared library that is to be profiled and makes up part of your application. Equivalent to an executable or module entry from the session wizard in the GUI. If you have multiple modules, -M may be more convenient.
    -M modulefilelist The path to a file which lists, one per line, executables or shared libraries to be profiled that are part of your application. Equivalent to multiple -m options.
    -N javapercent A number representing the percentage of your application that is Java. The default is 0.
    -o outputfile The path and name of an output file where collected data will be stored. This file is imported into the GUI to display the collected data, or possibly error messages if data could not be collected. The default output filename is yyyymmddThhmmss.par, where yyyymmddThhmmss represents the current date and time in ISO 8601 format.
    -R Collect run-side data. If your application is built on one system but you want to profile it on another, use this option with the script on the system where the application is to be run and profiled. The default is to collect both build-side and run-side data. See also -B.
    -S sessionname Display sessionname as the session name when the results are imported. Equivalent to setting the session name in the session wizard in the GUI.
    -u userdir The given directory will be searched for some additional collected build or source data, for example XL compiler transformation reports. If you have multiple directories, -U may be more convenient. This is only used when collecting build-side data. See also -b.
    -U userdirfilelist The path to a file which lists, one per line, directories to be searched for additional data. Equivalent to multiple -u options.
    Options for pa-hotspots.sh
    -d delay When launching your application, wait delay seconds after launching before starting profiling. This is equivalent to the option to start after delay value in the hotspot detection activity wizard.
    -f srcfilename Files with this name will be considered as source files for your application. It is usually easier to use -x or -X to specify file suffix instead of the name, but -f can be used if the file has no suffix. If you have many such files, -F may be more convenient.
    -F srcfilenamefilelist The path to a file which lists, one per line, filenames like those described for -f.
    -i interval How often, in seconds to sample system data. This is not the sample rate for the actual profiler.
    -l launchconfig The name of a launch configuration in the GUI to associate with this data. This is not required, but can be used to help the GUI find source files when the data is imported if you do not have your source code in the IDE.
    -p pid Instead of launching an application to profile, profile the process with process ID pid. If you wish to profile multiple process IDs, -P may be more convenient
    -P pidfilelist The path to a file which lists, one per line, process IDs which will be profiled.
    -t profiletime How long, in seconds, to profile the application. The default is 0, which will profile until the application ends.
    -x srcsuffix A suffix which indicates a source file in your application. For multiple suffix values, using -X may be more convenient. The default is the default list of suffix values for the project types Rational Developer for AIX and Linux Performance Advisor supports.
    -X srcsuffixfilelist The path to a file which lists, one per line, source file suffix strings. Equivalent to multiple -x options.
    Options for pa-scorecard.sh  
    -L lowestarch The lowest target architecture your application supports (Power processesors only). Equivalent to the minimum platform supported in the system scorecard activity wizard.
    -T targetarch The ideal target architecture your application supports (Power processesors only). Equivalent to the ideal in the system scorecard activity wizard.

    The collection scripts may generate error messages. If the bundle was created with the correct system file encoding, the messages should be translated and displayed correctly. If not, importing the output file into the client GUI will show the translated error messages correctly. If no output file was created, or if the GUI is not available, the following table can be used to look up the message ID.

    Table 2. Script messages by message ID. Messages from the collection scripts
    Message ID Message
    RPAS0001 Target host data collection complete.
    RPAS0002 The collection of data on the target host completed successfully.
    RPAS0003 Error: Data collector was interrupted
    RPAS0004 The data collection on the target system was interrupted, perhaps as the result of an intermittent problem such as a loss of network connectivity. Try collecting data again.
    RPAS0005 Error: Data collection aborted.
    RPAS0006 Due to earlier errors, data collection was aborted. Fix these problems and try collecting data again.
    RPAS0007 Error: The data collection was unable to identify the target application for profiling.
    RPAS0008 The Performance Advisor did not identify your application for the system profiler. This can happen if your application exits quickly; check the Console window to see if your application ended. It is also possible this is due to earlier problems or connection issues.
    RPAS0009 Error: Unable to save collected data to project.
    RPAS0010 The Performance Advisor was unable to save the collected profiling data to the project area. The most likely cause is that you are low on disk space in the filesystem where your project is stored on the target system.
    RPAS0011 Error: No process data was collected, unable to identify target application.
    RPAS0012 The Performance Advisor was unable to collection information about processes on the target system. This could be due to network problems or lack of disk space on the target host. You may still be able to view profiling results, but some functionality such as identifying your application in the My Application filter may be affected.
    RPAS0013 Error: System data collection failed
    RPAS0014 The Performance Advisor could not collect Hotspot data because it was not able to collect system data to verify that the host supports profiling. Earlier errors or warnings may give additional detail.
    RPAS0015 Error: The data collection was unable to identify the target application for profiling before the system profiler completed its timed collection.
    RPAS0016 The Performance Advisor did not identify your application before the system profiler finished the timed collection specified in the collection options. This can happen if the collection time is too short, or may be the result of connection problems or a system issue on the target host.
    RPAS0017 Error: The data collection was unable to identify the target application for profiling before the system profiler exited.
    RPAS0018 The Performance Advisor did not identify your application before the system profiler exited. This may be the result of connection problems or a system issue on the target host.
    RPAS0019 Error: tprof exited with an error.
    RPAS0020 The tprof tool exited with an error. This can happen if the there is insufficient disk space in the temporary data directory you selected for the Session, or if you set custom tprof options, there may be an error in those settings.
    RPAS0021 Error: tprof2xml exited with an error.
    RPAS0022 The tprof2xml tool exited with an error. This can happen if the there is insufficient disk space in the temporary data directory you selected for the Session, or because of a tprof error.
    RPAS0023 Error: The tprof tool or the trace subsystem is already running; multiple utilities are making use of the trace subsystem.
    RPAS0024 The tprof tool can only be launched when no one else is using the the trace subsystem.
    RPAS0025 Error: You are already running tprof or some other utility that makes use of the trace subsystem.
    RPAS0026 If you would like to stop your existing use of the trace subsystem, then please log onto your target machine and issue the "trcstop" command. You can use the Remote Systems tab to launch a shell or a ssh terminal on your target machine. In addition, if you would like to stop your existing run of tprof, then you can use the Remote Systems tab to browse your target system, browse a list of your running processes, select your existing tprof process, and terminate it.
    RPAS0027 Error: Someone else is already running tprof or some other utility that makes use of the trace subsystem.
    RPAS0028 If you would like to know who is currently running tprof or making use of the trace subsystem, you can use the Remote Systems tab to browse the list of processes. Be sure to use the "Show in Table" feature, which can be selected by right-clicking on the Processes item.
    RPAS0029 Error: tprof did not generate expected data file.
    RPAS0030 The tprof tool completed but did not create the data file needed by the Performance Advisor. This can happen if the there is insufficient disk space in the temporary data directory you selected for the Session.
    RPAS0031 Internal Error: procstack did not generate a .pcs file.
    RPAS0032 An internal error occurred and the required data was not collected. Please report this failure.
    RPAS0033 Error: OProfile is already running; multiple utilities are making use of OProfile.
    RPAS0034 OProfile can only be used by one utility at a time.
    RPAS0035 Error: You are already running OProfile.
    RPAS0036 If you would like to stop your existing use of OProfile, then please log onto your target machine and issue the command, "opcontrol --shutdown" . You can use the Remote Systems tab to launch a shell or a ssh terminal on your target machine.
    RPAS0037 Error: Someone else is already running OProfile.
    RPAS0038 If you would like to know who is currently running OProfile, you can use the Remote Systems tab to browse the list of processes. Be sure to use the "Show in Table" feature, which can be selected by right-clicking on the Processes item.
    RPAS0039 Error: OProfile failed to launch, perhaps due to an existing instance of OProfile running. CAUTION: Due to a defect in OProfile, any existing, running instance of OProfile will be corrupt.
    RPAS0040 More details about the bug can be found here: IBM LTC Bugzilla bug #73763: Attempting to run oprofile twice corrupts the first instance of oprofile. https://bugzilla.linux.ibm.com/show_bug.cgi?id=73763.
    RPAS0041 Error: Target operating system is not AIX.
    RPAS0042 The target system does not appear to be AIX, but the connection is configured for AIX. Change the launch configuration to use a connection to an AIX system.
    RPAS0043 Error: This version of AIX is older than 5.3.
    RPAS0044 The minimum supported version for the Performance Advisor is AIX 5.3. The target system does not meet this minimum requirement.
    RPAS0045 Warning: This version of AIX is newer than 7.1 and has not been tested with the Performance Advisor.
    RPAS0046 At the time of product release, the highest version of AIX available was 7.1 and therefore newer versions of AIX could not have been tested against the Performance Advisor.
    RPAS0047 Warning: This Technology Level of AIX is no longer supported by IBM. The Performance Advisor may still work, but you should remain cautious of the results.
    RPAS0048 We recommend that you upgrade the Technology Level of your AIX to a version that is currently supported by IBM. Please visit the following IBM web site to obtain updates. http://www-933.ibm.com/support/fixcentral
    RPAS0049 Error: Could not find tprof.
    RPAS0050 The tprof profiling tool was not found. Please make sure that the bos.perf.tools AIX fileset is installed.
    RPAS0051 Error: Could not find tprof2xml.
    RPAS0052 The tprof2xml converter was not found. Please make sure that either the bos.perf.tools or the tprof2xml.rte AIX fileset is installed.
    RPAS0053 Error: Could not find a Java VM in your PATH environment variable.
    RPAS0054 The Performance Advisor requires a Java 1.4 or newer JVM on the target system, and the installation directory must be in your PATH environment variable. Please install an appropriate Java version (if necessary) and add it to your PATH environment variable.
    RPAS0055 Error: Old Java version. You need a Java 1.4 or newer JVM.
    RPAS0056 The Performance Advisor requires a Java 1.4 or newer JVM on the target system, but the version found is older. Please install an appropriate Java version (if necessary) and ensure that it is in your PATH environment variable before any older version.
    RPAS0057 Warning: You are running low on disk space on the target host.
    RPAS0058 Collecting performance tuning data can use large amounts of disk space on the target system. The temporary data folder you set in your Session does not have much available space, and this could cause errors when you collect data.
    RPAS0059 Error: Could not find procstack.
    RPAS0060 The procstack tool used by the Performance Advisor was not found. Please make sure that the bos.perf.proctools AIX fileset is installed.
    RPAS0061 Error: Target operating system is not a supported Linux.
    RPAS0062 See the product documentation for supported Linux versions and required update levels.
    RPAS0063 Warning: This Linux distribution is older than the oldest supported version.
    RPAS0064 See the product documentation for supported Linux versions and required update levels.
    RPAS0065 Warning: This distribution of Linux is unsupported by the Performance Advisor.
    RPAS0066 See the product documentation for supported Linux versions and required update levels.
    RPAS0067 Error: root access is required for data collection on Linux.
    RPAS0068 The Performance Advisor uses OProfile to collect data on Linux and OProfile must run as root. Make sure the connection you have configured for data collection has root access.
    RPAS0069 Error: root access required and no root escalation command is set.
    RPAS0070 The Performance Advisor uses OProfile to collect data on Linux and OProfile must run as root. For local connections, the session must set a command to escalate privileges if the current user is not root. For remote connections, make sure the connection has root access.
    RPAS0071 Error: root privilege escalation command not found.
    RPAS0072 The root privilege escalation command set in the session was not found. Check that the selected command is installed and verify the command name or use a full path to the command.
    RPAS0073 Error: Could not find opcontrol.
    RPAS0074 The Performance Advisor requires the opcontrol command which is part of the OProfile profiling package. Please install this package, and ensure it is in your PATH environment variable.
    RPAS0075 Error: Could not find opreport.
    RPAS0076 The Performance Advisor requires the opreport command which is part of the OProfile profiling package. Please install this package, and ensure it is in your PATH environment variable.
    RPAS0077 Error: Could not find oprofiled.
    RPAS0078 The Performance Advisor requires the OProfile daemon which is part of the OProfile profiling package. Please install this package, and ensure it is in your PATH environment variable.
    RPAS0079 Error: OProfile does not support required profiling event.
    RPAS0080 The Performance Advisor requires the installed OProfile profiling package to support certain profiling capabilities, and the installed version does not meet this requirement. See the product documentation for information about the supported version of OProfile.
    RPAS0081 Error: OProfile must be in timer mode.
    RPAS0082 Your server appears to be using a hypervisor, so the OProfile profiling tool must be set to use timer mode. See the product documentation for information about setting up OProfile.
    RPAS0083 Error: Could not find RDp object debug dump tool.
    RPAS0084 The Performance Advisor requires the RDPower server to be installed. Please ensure that your RDPower server installation is correct.
    RPAS0085 Error: Unable to initialize OProfile.
    RPAS0086 The Performance Advisor was not able to initialize the OProfile profiling system. Please ensure that OProfile is installed and works with your kernel, and that the user specified in your connection has permission to use OProfile.
    RPAS0087 Error: Unable to start OProfile.
    RPAS0088 The Performance Advisor was not able to start the OProfile profiling system. Please ensure that OProfile is installed and works with your kernel, and that the user specified in your connection has permission to use OProfile.
    RPAS0089 Error: Unable to collect detailed profiling results.
    RPAS0090 The detailed profile report from OProfile was not generated or was empty. This may mean that OProfile is not correctly configured, or the system ran out of disk space.
    RPAS0091 Error: Unable to collect profiling call graph results.
    RPAS0092 The call graph profile report from OProfile was not generated or was empty. This may mean that OProfile is not correctly configured, or the system ran out of disk space.
    RPAS0110 Error: Data collection failed and no output file was created
    RPAS0110 Error: Data collection failed; import "partfile" for details
    RPAS0112 Error: Unable to create output file "file"
    RPAS0150 Error: Unknown script option: "option"
    RPAS0151 Error: Unable to read file "file"
    RPAS0152 Error: Invalid process ID: "pid"
    RPAS0153 Error: Invalid number: "str"
    RPAS0154 Error: Unable to create "dir"
    RPAS0155 Error: Nothing to profile; use -p <pid>, -P <pids_file> or specify command and arguments.
    RPAS0156 Error: Incompatible launch process ID options; IBM_RDPPA_HS_PID_FILE cannot be used with -p or -P.
    RPAS0157 Error: The system profiler exited with an error code: num
    RPAS0158 Error: Unable to shut down system profiler (process id pid)
    RPAS0159 Error: OProfile legacy profiling mode tools are required.
    RPAS0160 Error: OProfile does not appear to be installed. Please install OProfile and ensure it is in your PATH environment variable.
    RPAS0161 Error: OProfile does not appear to be installed. Please install OProfile with legacy profiling mode support and ensure it is in your PATH environment variable.
    RPAS0171 Error: Unable to change crontab, exit status num
  4. Import the data into the client GUI After the data collection script completes successfully, an output file will be created. Unless the -o option (above) was used to change the default, this output file will be in the directory where the script was run, and will be named yyyymmddThhmmss.par, where yyyymmddThhmmss represents the current date and time in ISO 8601 format. Importing this file into the GUI will allow you to view the collected data, or if data could not be collected, will display error messages from the script.
    1. Click the File menu and choose Import...
    2. In the Import dialog, in the Performance Advisor category select Activity Run from Command-Line Script and click Next to bring up the Import Activity Run from Command-Line Script wizard.
      Import Activity Run from Command-Line Data Collection Script wizard main page
    3. If you have a remote connection to the system where the collection script was run, you can select Remote file and browse directly to the .par file; if not, copy the .par file to the local system or another remote system to which you do have a connection, and browse to it with Local file or Remote file as appropriate.
    4. Select the project into which you will import the collected data. If you do not have a project for your application, you can create an empty C/C++ project for this purpose.
    5. Click Next. If the .par file contains data that was collected for only the build side (with -B) or only the runtime side (with -R) you will see another page asking you to select the second .par file containing the remaining data. Select the file and click Next.
    The final wizard page gives information on the activity, including whether it was successful or not, as well as showing any messages that the script generated when it ran. Ifthe activity was successful, the imported activity will be in the completed state and the data can be viewed with the Hotspots Browser, Scorecard Viewer, etc.
    Successful import of an activity run from command-line data collection script
    If the activity was not successful, the activity will be in the FAILED state so no views will be available, but error messages will be shown.
    Import of a failed Hotspot Detection activity run from command-line data collection script, showing error message

Feedback