Welcome to the IBM® Performance Optimization Toolkit 6.1.2 for Rational® Performance Tester. This guide contains information about installing and setting up the toolkit.
Additional late-breaking information about limitations and work-arounds may be found in the toolkit release notes.
This file is available in the following national languages:
French |
Brazilian Portuguese |
German |
Simplified Chinese |
Italian |
Spanish |
Japanese |
Traditional Chinese |
Korean |
IBM Performance Optimization Toolkit requires the Rational Performance Tester product to be installed. The toolkit provides the following features:
The following hardware must be installed before you install this toolkit. These numbers assume you also install the data collection infrastructure on the same machine:
The following hardware is the required minimum for installing the data collection infrastructure on a machine other than the one where the workbench is also installed:
The following software must be installed before you install this update for the toolkit:
Note: if you have Version 6.x.0 of one of the products installed, use the Rational Product Updater to update to Version 6.x.1.
Note: If you are installing from scratch, install only the workbench portion of the toolkit, not the data collection infrastructure. If you have installed the data collection infrastructure of the V6.1 toolkit, you must uninstall it before installing the V6.1.2 data collection infrastructure.
Important: Uninstall all beta versions of Rational Performance Analyst and Rational Performance Tester, and install the appropriate Rational Software Development Platform product listed above, before you install the toolkit.
Install the data collection infrastructure on all hosts involved in your distributed application from which you wish to collect data. It is also recommended (and for some scenarios required) that you install the data collection infrastructure on the local machine where you have installed the toolkit.
Note for Linux: The Hyades Data Collection Engine feature of the data collection infrastructure is compiled using libstdc++-libc6.2-2.so.3 shared library. Ensure that this shared library exists under the /usr/lib directory. If it does not exist, you have to install the RPM package compat-libstdc++ that comes with the operating system installation media.
The data collection infrastructure has been tested on the following platforms:
It is not tested, but expected to run on Red Flag Advance Server v4.0 on Intel IA32.
In general, the data collection infrastructure works with JVM version 1.4 and above. Here are the JVM versions (java -fullversion) that data collection has been tested on:
The toolkit collects performance profiling data for distributed applications, and sends it to the workbench where you view and analyze the collected data. You can query a Tivoli Monitoring for Transaction Performance (TMTP), IBM Tivoli Composite Application Manager for Response Time Tracking (ITCAM for RTT), or IBM Tivoli Composite Application Manager for WebSphere (ITCAM for WebSphere) management server database to collect past performance data for an application deployed in a production environment. With IBM Performance Optimization Toolkit for Rational Performance Tester, you can also monitor a live application in a development or testing environment and collect its data in real time.
In a production environment, you can collect data by querying the management server database for the following system management software:
For a live Web application, the data collection infrastructure collects performance profiling data from the following Web servers:
Please see the installation guides for complete instructions on installing these products. The installation instructions below include information on how to configure these products for use with the data collection infrastructure.
Before you install the toolkit, check that your environment variable TEMP or TMP is pointing to a valid temporary directory with at least 100 MB free. This is in addition to the space required to install the product.
The prerequired V6.x.0 toolkit, along with the installation instructions, is available from the following Web site:
To upgrade the toolkit to version 6.x.1:
Errors occurred during the installation - User cancelled installation
When you attempt to uninstall the toolkit in this state, you may receive the following error:
A suitable JVM could not be found. Please run the program again using the option -is:javahome <JAVA HOME DIR>.
To work around this, you must rerun the installation program again to complete the previously canceled modification, and then proceed to uninstall the toolkit.
The toolkit is installed as an addition to a Rational Software Development Platform product you already have installed (Rational Performance Tester, Rational Application Developer or Rational Software Architect). To use the tools, launch that program the usual way. For example, from the Start menu select Programs > IBM Rational > Rational Software Development Platform.
The first time that you start after installing, a dialog box may open with a default workspace directory already specified. If you want to save your work somewhere else, you can change the name and location of the workspace. If you wish to always use this workspace, enable the Use this as the default and do not ask again check box. You can change the default value after you have started the product in the Window > Preferences > Workbench > Startup and Shutdown page.
The workbench may first open to a series of welcome pages that provide a product overview, including overview information about the toolkit, and information about what's new, plus links to tutorials, samples, and external Web resources for the base product. Spend some time exploring these options. Notice as well the sources of information that are available from the Help menu. You can return to these welcome pages by selecting Help > Welcome.
Note: If you have installed the data collection infrastructure, uninstall it first, before you uninstall the toolkit. See Uninstalling the data collection infrastructure for instructions.
To uninstall the toolkit:
Note: you can get around this step if, when you updated to V6.x.1 you did not click the Clean Up button. If you did not do the clean up step, then:
rpu -enableRollback
If you try to partially uninstall one or more of the required features, you will receive an error message similar to this:
Invalid selection: Unable to uninstall ide_required: root is not set for uninstall
To work around this problem, select the Product Uninstallation check box in the uninstall wizard. The uninstallation panel will be reinitialized so that you may now uninstall the toolkit entirely, or clear the selection of features that you do not want to uninstall.
Before you install the toolkit, check the following things:
The prerequired V6.x.0 toolkit, along with the installation instructions, is available from the following Web site:
To upgrade the toolkit to version 6.x.1:
You must now install the data collection infrastructure. See Installing the data collection infrastructure for instructions.
If you rerun the installation program to add additional features and select to cancel the modification before it finishes, you may receive the following error:
Errors occurred during the installation - User cancelled installation
When you attempt to uninstall the product in this state, you may receive the following error:
A suitable JVM could not be found. Please run the program again using the option -is:javahome <JAVA HOME DIR>.
To work around this, you must rerun the installation program again to complete the previously canceled modification, and then proceed to uninstall the product.
There are two ways to avoid the problem. The first and recommended way is to update the RHEL 3 system to Quarterly Update 2 or later from Red Hat. Update 2 includes a fix to the failing pthreads library.
Alternatively, and advised only if you are not using Update 2, is to switch the installer to run under LinuxThreads. LinuxThreads does not exhibit this failure and can be used to run the installer. To enable LinuxThreads for the installer, you must set two environment variables in the shell that you intend to run the installer in.
Run the following two commands:
export RPM_FORCE_NPTL=1 export LD_ASSUME_KERNEL=2.4.19
To verify variables are set, run the commands:
env | grep RPM_FORCE_NPTL env | grep LD_ASSUME_KERNEL
Both of the preceding commands return the variable and value you entered through the export commands. Then run the installation as normal.
The toolkit is installed as an addition to a Rational Software Development Platform program you already have installed (for example, Rational Performance Tester or Rational Application Developer). To start the Software Development Platform from a command line, go to your installation directory and run the command: ./rationalsdp.bin.
Alternatively, if you are working in Gnome (which is the Red Hat default), the product shortcut will be on the main menu under Programming > Rational Software Development Platform. If you are working in KDE (which is the SuSE default) the product shortcut will be IBM Rational > Rational Software Development Platform.
The first time that you start after installing, a dialog box may open with a default workspace directory already specified. If you want to save your work somewhere else, you can change the name and location of the workspace. If you wish to always use this workspace, enable the Use this as the default and do not ask again check box. You can change the default value after you have started the product in the Window > Preferences > Workbench > Startup and Shutdown page.
The workbench may first open to a series of welcome pages that provide a product overview and information about what's new, plus links to tutorials, samples, and external Web resources. Spend some time exploring these options. Notice as well the sources of information that are available from the Help menu. You can return to these welcome pages by selecting Help > Welcome.
Note: If you have installed the data collection infrastructure, uninstall it first, before you uninstall the toolkit. See Uninstalling the data collection infrastructure for instructions.
To uninstall the toolkit on Linux, follow these steps:
Note: you can get around this step if, when you updated to V6.x.1 you did not click the Clean Up button. If you did not do the clean up step, then:
rpu.bin -enableRollback
If you try to partially uninstall one or more of the required features, you will receive an error message similar to this:
Invalid selection: Unable to uninstall ide_required: root is not set for uninstall
To work around this problem, select the Product Uninstallation check box. The uninstallation panel will be reinitialized so that you may now uninstall the toolkit entirely, or clear the selection of features that you do not want to uninstall.
The data collection infrastructure must be installed on any machine involved in running the application being monitored, from which you want to collect performance data. You must then configure the application servers on those machines to enable profiling of their applications. Also, to collect data via performance tests or load test schedules, you must install the data collection infrastructure on the same machine as where the toolkit front end is installed.
Important notes:
Earlier versions of Agent Controller have been shipped with earlier IBM products and may reside on hosts from which you are collecting data. Dynamic discovery is the process by which data collection 'crawls' the hosts used by the distributed application, contacting Agent Controller on each host. If one of the hosts used by the distributed application has an earlier version of Agent Controller, dynamic discovery will stop at that host and not continue past that host until transactions move beyond that host to the next host used. To fix this problem, update the version of Agent Controller on all hosts used by the application by uninstalling Agent Controller and installing the data collection infrastructure on those hosts.
The data collection infrastructure conflicts with other Hyades-based data collection mechanisms. If you have a previous version of Agent Controller or any software derived from the Hyades Data Collection Engine, stop it, uninstall it, and clean up any left-over files before installing this version of Agent Controller. The following files may be left behind after uninstalling and must be removed:
Windows:
%RASERVER_HOME%\*.* (directory where Agent Controller is installed) %SystemRoot%\system32\piAgent.dll (Windows' system32 directory) %SystemRoot%\system32\LogAgent.dll %SystemRoot%\system32\hcbnd.dll %SystemRoot%\system32\hcclco.dll %SystemRoot%\system32\hccldt.dll %SystemRoot%\system32\hccls.dll %SystemRoot%\system32\hcclserc.dll %SystemRoot%\system32\hcclsert.dll %SystemRoot%\system32\hcclsm.dll %SystemRoot%\system32\hcjbnd.dll %SystemRoot%\system32\hclaunch.dll %SystemRoot%\system32\hcthread.dll %SystemRoot%\system32\piAgent.dll %SystemRoot%\system32\rac.dll %SystemRoot%\system32\sysperf.dllLinux, AIX, HP-UX, Solaris:
$RASERVER_HOME/* (directory where Agent Controller is installed /usr/lib/libpiAgent.so (or .sl on HP-UX) /usr/lib/libLogAgent.so /usr/lib/libhcbnd.so /usr/lib/libhcclco.so /usr/lib/libhccldt.so /usr/lib/libhccls.so /usr/lib/libhcclserc.so /usr/lib/libhcclsert.so /usr/lib/libhcclsm.so /usr/lib/libhcjbnd.so /usr/lib/libhclaunch.so /usr/lib/libhcthread.so
For complete uninstallation instructions, refer to the uninstall instructions provided with the Agent Controller or other Hyades-based data collection mechanism you have installed.
Note: There are known intermittent problems with installing the data collection infrastructure on Windows Server 2003 machines using either long paths or paths with spaces. Avoid such directories if possible. This applies not only to the target installation directory, but also to the directory from which you are installing.
To install the data collection infrastructure:
Note (Linux): If you experience trouble starting the installer or the rest of the install, you may need to set execution rights on the files involved. Run the following commands from the temporary directory where you have downloaded and unpacked the image:
chmod 755 setup.bin chmod 755 setup/lplinuxbin chmod 755 dci_linux/disk1/setup/setup.bin
Note: If you are installing on the same machine as a Rational Software Development Platform product such as Rational Application Developer or Rational Performance Tester, then you must install the data collection infrastructure in the same location as where that product installed Agent Controller.
Click Next.
Click Next.
Note: If you get errors during this stage of the installation, and you have Agent Controller installed from the Rational Application Developer product, quit the installation, uninstall Agent Controller (following instructions in the Rational Application Developer installation guide), and try installing the data collection infrastructure again.
The next step is to configure the application server to use the data collection infrastructure.
To install the data collection infrastructure:
/installDCIComponents.sh -console
Any errors that occur during the installation will be shown on the console. The error messages will indicate the name of the installation error log file where you can get more information about what happened. Errors in one stage will stop the install, and the next components will not be installed.
Important note if you are using WebSphere Application Server V6.x on HP-UX: After you install the data collection infrastructure, make sure the SHLIB_PATH is set. Otherwise, transaction data may not be collected and there will be NoClassDef errors reported within ARM. To set the SHLIB_PATH, run the following command:
export SHLIB_PATH=$(SHLIB_PATH):$tivoli_comp/app/instrument/5301/lib/$(interp):$tivoli_comp/bin/$(interp)/USRLIB
The next step is to configure the application server to use the data collection infrastructure.
For an application server to correctly send performance data to the data collection infrastructure, it must be configured properly and restarted before you start to use data collection.
Notes:
To configure an application server:
Changes will take effect when you stop and then restart the server.
Repeat the configuration steps for every server on the machine involved in any data collection for the applications you will be profiling (Usually, there will be only one application server, but it is possible you have more than one on a machine).
To see the syntax for the instrumentServer command, type the command without any arguments:
AIX, HP-UX, Linux, Solaris:
./instrumentServer.shWindows:
instrumentServer
Examples:
On a non-Windows machine, to configure an IBM WebSphere Application Server V5.x server named server1, installed in the directory /opt/WebSphere/AppServer (no security):
./instrumentServer.sh -install -type IBM -serverName server1 -serverHome /opt/WebSphere/AppServer -serverVersion 5On a non-Windows machine, to configure an WebSphere Application Server V6.0 server named server2, installed in the directory /opt/WebSphere/AppServer, with profile name profile1 and security enabled:
./instrumentServer.sh -install -type IBM -serverName server2 -serverHome /opt/WebSphere/AppServer -profileName default -user myUserId -password myPassword -serverVersion 6On a non-Windows machine, to configure a BEA WebLogic server (with specifics as indicated):
./instrumentServer.sh -install -type BEA -serverName server1 -serverHome /opt/bea/weblogic81 -domain mydomain -domainPath /opt/bea/weblogic81/mydomain -javaHome /opt/bea/jdk141_02 -nodeManagedHost hostname.xyz.com -nodeManagedPort 7001 -adminServer my_server -startScript /opt/bea/weblogic81/mydomain/startManagedWeblogic.shOn a Windows machine, to configure a WebSphere Application Server V5.1 server named my_Server, installed in C:\Program Files\was-5.1, with security enabled:
instrumentServer -install -type IBM -serverName my_Server -serverHome "C:\Program Files\was5.1" -user myUserId -password myPassword -serverVersion 5On a Windows machine, to configure a BEA WebLogic server (with specifics as indicated):
instrumentServer -install -type BEA -serverName server1 -serverHome C:\bea\weblogic81 -domain mydomain -domainPath C:\bea\weblogic81\mydomain -javaHome C:\bea\jdk141_02 -nodeManagedHost localhost -nodeManagedPort 7001 -adminServer my_server -startScript C:\bea\weblogic81\mydomain\startManagedWeblogic.cmd
The data collection infrastructure must be started in order to collect performance data from running applications and tests.
Starting the data collection infrastrucure starts the Agent Controller component; it is important that other instances of Agent Controller are stopped before you start the data collection infrastructure. For this reason, if you are using Rational Performance Tester, you must start the data collection infrastructure (on the local machine) before you start Rational Performance Tester (which otherwise starts Agent Controller).
On platforms that support it, entries will be made to the main launch menu (for example, the Start menu on Windows) for starting and stopping the data collection infrastructure. So, for example, on Windows, click Start > Programs > IBM Rational > IBM Rational Software Development Platform > Start data collection infrastructure or Stop data collection infrastructure.
Otherwise, to start the data collection infrastructure:
Note for collecting Web services data on WebSphere Application Server: Start the data collection infrastructure before you start Websphere Application Server. Otherwise, Web service data might not be collected. If it is not possible for you to restart the server after starting the data collection infrastructure, you can force it to reconnect to the ARM engine by disabling and then enabling ARM via JMX or the admin console.
To stop the data collection infrastructure:
Troubleshooting tip for HP-UX: If you experience problems starting the ARM agent component of the data collection infrastructure on HP-UX, the machine may have a configuration limitation that prevents the ARM agent from launching properly. Check the following kernel configuration parameters and make sure that they are at least as large as the values given:
sema 1 semaem 16384 semmap 4098 semmni 4096 semmns 8192 semmnu 4092 semmsl 2048 semume 512 semvmx 32767
These kernel configuration parameters are related to the semaphore usage on your system. Refer to HP-UX system documentation or consult with a system administrator for detailed instructions on modifying the HP-UX kernel configuration parameters. Alternatively, if you do not want update your kernel configuration, you may edit the file tapm_ep.cfg, located under the Data Collection Infrastructure installation directory. In this file you will find two parameters:
IPCAppToEngSize=500 IPCEngToAppSize=500
Change these settings to:
IPCAppToEngSize=50 IPCEngToAppSize=50
The side effect of this change is a potential reduction in the performance of data collection.
After you have already installed (and possibly used) the data collection infrastructure, you can add more hosts to the access list by doing the following:
Note: If you uninstall the data collection infrastructure on a machine that also includes a Rational Software Development Platform product such as Rational Performance Tester, Rational Application Developer, or Rational Software Architect, it will remove the Agent Controller or data collection component installed by that product. If you wish to use Agent Controller or data collection with that product after you have uninstalled this toolkit's data collection infrastructure, you must reinstall it using that product's installation procedures.
Likewise, if you uninstall a Rational Software Development Platform product that has installed Agent Controller, such as Rational Application Developer or Rational Performance Tester, it will remove that component of the data collection infrastructure, disabling it. You will have to reinstall the data collection infrastructure.
Before you uninstall the data collection infrastructure, you must unconfigure all application servers configured to work with it. To unconfigure a server:
instrumentServer -uninstall -type IBM -serverName my_Server -serverHome "C:\Program Files\was5.1" -user myUserId -password myPassword -serverVersion 5
See configuration examples for other examples of what the original configuration arguments might have been. Note: All configured servers are listed in the file serverConfig.xml.
Note: If you have uninstalled the server or removed the server instance without unconfiguring it, the instrumentServer utility will still think it is there, but will be unable to contact it to unconfigure it. This will block the uninstallation process for the data collection infrastructure. To resolve this, add the -force argument to the instrumentServer command. This will remove the corresponding line in serverConfig.xml without having to contact the missing server to unconfigure it. For the same example as above:
instrumentServer -uninstall -force -type IBM -serverName my_Server -serverHome "C:\Program Files\was5.1" -user myUserId -password myPassword -serverVersion 5
Repeat the unconfiguration steps for every server configured for data collection. Once you are finished, the serverConfig.xml file will be empty, and data collection uninstallation will proceed.
Next, uninstall the data collection infrastructure.
To uninstall the data collection infrastructure, use the operating system's install manager (for example, on Windows, the Add/Remove Programs window). Find the program IBM Rational Data Collection Infrastructure V6.1 and remove it.
If the operating system does not have such an install manager, to uninstall the data collection infrastructure:
To uninstall the data collection infrastructure:
rpa_prod/rpa_comp/rpa_boot_stop_unix.sh
Uninstall each data collection component by running the following commands in the order shown. After each, confirm your intention to uninstall the component, and wait while the uninstallation completes. Note: For any of the following, you can use -silent, rather than -console, to run the uninstall silently.
/dci_prod/_uninst/uninstall.bin -console
/IBM_Agent_Controller/_uninst/uninstall.bin -console -W prod_id_uninstall.value=dci
/tau_prod/_uninst/uninstall.bin -console
/rpa_prod/tivoli_comp/_uninst/uninstall.bin -console
If you have trouble uninstalling the data collection infrastructure, ensure the agents are stopped before attempting to uninstall.
If, after uninstalling the data collection infrastructure, WebSphere Application Server no longer starts, you may be able to fix it by doing the following steps:
Open up the file server.xml in <was_install>/config/cells/<cell>/nodes/<node>/servers/<server>/ (<server> is likely server1, and <cell> and <node> is likely the machine name).
Locate the following line: genericJvmArgs="<some set of strings>"
Replace this with an empty string: genericJvmArgs=""
You should now be able to start the application server.