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.

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



