Configuring

1. Configure RPT
1.1. Configure the Agent Controller in a secure environment
1.2. Configure the environment for SAP tests
1.2.1. Configure SAP R/3 for performance testing
1.2.2. Configure the environment for batch input tests
1.3. Configure the data collection infrastructure
1.3.1. Data collection infrastructure overview
1.3.2. Instrument local servers
1.3.2.1. Tips for instrumenting Oracle WebLogic Application Server
1.3.2.2. Tips for instrumenting WebSphere Application Server
1.3.3. Instrument servers by using the command prompt
1.3.4. Remove instrumentation
1.3.5. Remove instrumentation using the command prompt


1.1. Configure the Agent Controller in a secure environment

We do not recommend running the Agent Controller behind a firewall. However, if you are required to run the Agent Controller behind a firewall, run the SetConfig script on the agent computers and the workbench computer before recording or running tests.

  1. Enable the security setting on each agent computer that generates load for your tests, as well as your workbench computer.

    1. On the workbench computer, click Window > Preferences > Agent Controller > Integrated Agent Controller. Under Integrated Agent Controller security, click On. Click OK.

    2. On each agent computer, run the SetConfig script (SetConfig.bat for Microsoft Windows platforms; SetConfig.sh for non-Windows platforms). This script is located in the installation directory. The default installation directory is C:\\IBM\SDP\AgentController\bin. See Change Agent Controller security settings after installation for details on running this script.

  2. Restart Rational Performance Tester on the workbench computer.

  3. Restart the agent controller on all of the agent computers.

  4. Record the test, or run the schedule or test.

    1. During recording, you are prompted to provide a user name and password for your workbench computer.

    2. During the schedule or test run, you are prompted to enter a user name and password for each location (agent) that has security enabled, as well as your workbench computer. You are not prompted again for user names and passwords when you rerun the test or schedule in the same workbench session.

      Note: This secure environment has no effect on collecting test results, except for response time breakdown data. Response time breakdown data cannot be collected when running at a secure location.


1.2. Configure the environment for SAP tests

Some of the capabilities of service tests require that you manually install additional libraries and files or that you configure some elements of the test environment.


1.2.1. Configure SAP R/3 for performance testing

Performance test recording and execution requires scripting to be enabled on the SAP R/3 application server and on all SAP GUI clients that are installed on remote computers. The following instructions are for SAP R/3 version 6.40 and might vary with other versions. Refer to SAP documentation for further information.

Performance testing relies on the SAP Scripting API and ActiveX. Make sure that Active X is installed when installing the SAP GUI client and enable scripting on the SAP R/3 server.

Note: You only need to perform the following actions once. Scripting should remain enabled on the SAP R/3 server after a restart.

To enable scripting on the SAP R/3 server:

  1. Check that there is a Scripting directory located in the SAP GUI installation directory. If this directory does not exist, then the SAP Scripting API is not installed and you must reinstall SAP GUI with the SAP Scripting API option.

  2. Run the SAP GUI client and logon to SAP R/3 with your user name and password. Administrator privileges might be required to enable scripting on the server.

  3. In SAP, run the transaction rz11, type the parameter name sapgui/user_scripting, and then click Display. If the parameter is not found, then make sure you have the correct support package level from SAP. Contact your SAP representative for guidance.

  4. If the Current value is FALSE, click the Change value button, and then set the New value to TRUE in uppercase characters.

  5. Click Save, and then end the transaction. Scripting will be enabled the next time you log on.

  6. In the SAP GUI client toolbar, click the Customizing of Local Layout toolbar button, and then select Options.

  7. Select the Scripting page.

  8. Select Enable Scripting, and then disable both Notify When a Script Attaches to Running GUI and Notify When a Script Opens a Connection.

  9. Click OK.

  10. In the Help menu, select Settings, and then select the F4 Help page.

  11. In Display, select Dialog (modal) and then click the Enter button.

Repeat steps 5 through 9 for SAP GUI clients on all remote computers. For more information about enabling scripting on the SAP R/3 application server, refer to the following SAP notes, available from SAP:


1.2.2. Configure the environment for batch input tests

To play back SAP batch input tests, you must install the SAP Java. Connector (JCo) libraries provided by SAP on local and remote computers running the agent controller.

The following files are required:

Contact SAP for instructions on obtaining these files.

On each local and remote computer used for running batch input tests and schedules, you must prepare an environment with these libraries, set the class path of the JRE that the Rational Agent Controller uses.

To configure a computer for SAP batch input tests:

  1. Copy sapjco3.jar into the jre/lib/ext directory of the JRE. The exact location is specified in the serviceconfig.xml file located in the AgentController\config directory.

    By default, this is the following directory: C:\\IBM\SDP\jdk\jre\lib\ext.

  2. Copy sapco3.dll into the C:\Windows\System32 directory.

  3. Click Start > Control Panel > Administrative Tools > Services, and then stop and restart the IBM Rational Agent Controller service.

When running a simple SAP batch input test, results should appear in the SAP Batch Input Transaction page of the SAP performance report. If not, look at the test log for connection and transaction execution information.


1.3. Configure the data collection infrastructure

To collect response time breakdown data from remote computers used in distributed applications, you must install and configure the data collection infrastructure on the remote computers.


1.3.1. Data collection infrastructure overview

The data collection infrastructure collects performance profiling data for distributed applications and sends the data to the workbench computer, where you can view and analyze the collected data. The data collection infrastructure must be installed, configured, and running on all remote computers that will be used in your distributed application. The data collection infrastructure is installed when you install Rational Performance Tester Agent.

You can monitor a live application in a development or testing environment and collect data from the application in real time. Data collection is supported on the following web servers:

You can also query IBM Tivoli Monitoring for Transaction Performance, IBM Tivoli Composite Application Manager for Response Time Tracking, IBM Tivoli Composite Application Manager for WebSphere or IBM Tivoli Composite Appliciuiu.uation Manager for Application Diagnostics management server databases to collect past performance data for an application that is deployed in a production environment. Data collection is supported on the following software versions:


1.3.2. Instrument local servers

You must instrument application servers to collect response time breakdown data. You can use either a command-line or graphical user interface to instrument application servers to work with the data collection infrastructure.

  1. In Windows, click Start > Programs > IBM Data Collection Infrastructure > Application Server Instrumenter. In Linux, use the start menu to open the Application Server Instrumenter. In the AIX operating system, type /opt/IBM/SDP/DCI/rapa_prod/instrument_comp/ASI at a command prompt to start the Application Server Instrumenter. The Application Server Instrumenter starts.
  2. Use the Application Server Instrumenter to instrument the server. See the examples that follow.
  3. If you are instrumenting a BEA WebLogic server, after you have instrumented the server you must restart the application server. The Application Server Instrumenter automatically restarts WebSphere application servers.

    Note: All IBM Rational Performance Tester systems that are involved with the data collection infrastructure must have the data collection software running for the transaction breakdown function to be available within the results of a RPT test schedule.

    Note: The application server instrumenter or the instrumentServer.bat (or instrumentServer.sh) batch file can fail with a generic error message (Error during install/uninstall) when instrumenting or uninstrumenting a server. If this error occurs, you can find more information to help troubleshoot the error in the log files in the IBM Tivoli common directory. On Windows, the default location of this directory is C:\\IBM\tivoli\common. On Linux, the default location of this directory is /var/ibm/tivoli/common. If the IBM Tivoli common directory is not in the default location, search for a path containing tivoli/common, or for any of these log files: trace-install.log, trace-ma.log, or trace-tapmagent.log.

    Note: For IBM WebSphere Application Server 6.0 or later, if you create a new profile and then use the application server instrumenter to instrument this profile without first starting WebSphere Application Server, the application server instrumenter reports that the server is instrumented and prompts you to restart the server manually. This message is incorrect; the server is not actually instrumented. To work around this problem, complete these steps:

    1. Close and then restart the application server instrumenter.
    2. Select the entry that you just added from the list of instrumented servers, and click Remove.
    3. Restart WebSphere Application Server.
    4. Restart the application server instrumenter, and use it to instrument the server.
    To avoid this problem, after you create a new profile, start the WebSphere Application Server profile manually. Then, use the application server instrumenter to instrument the server.


Example

To instrument a Linux computer that is equipped with the 64-bit version of IBM WebSphere Application Server, Version 6.1, where the server is named server2, the server is installed in the /opt/WebSphere/AppServer directory, with the profile name set to the default value, and security enabled:

  1. Click Instrument Local Server.
  2. From the Type list, select IBM WebSphere Application Server v6.1.
  3. Type /opt/WebSphere/AppServer in the Server home field.
  4. Type server2 in the Server name field.
  5. Type default in the Profile name field.
  6. Under Server JVM, click 64-bit.
  7. Select the Requires global security check box.
  8. Type the WebSphere user ID in the User field.
  9. Type the WebSphere password in the Password field.
  10. Click OK.

To instrument a Microsoft Windows computer that is equipped with a BEA WebLogic 10 application server named server1 that is installed in the C:\bea\weblogic10 directory, using the 32-bit version of JRockit JVM, and the C:\bea\weblogic10\mydomain\startWebLogic.cmd start script file :

  1. Click Instrument Local Server.
  2. Select BEA WebLogic Application Server v10.x from the Type list.
  3. Type server1 in the Server name field.
  4. Type C:\bea\weblogic10 in the Server home field.
  5. Type C:\bea\weblogic10\mydomain\startWebLogic.cmd in the Start script field.
  6. Under Server JVM, select Oracle JRockit 32-bit.
  7. Click OK.
  8. Stop and restart the server.

Repeat the instrumentation steps for every application server that is involved in data collection for the applications that you will profile. Typically, there will be only one application server. You can instrument only one local application server per computer.


1.3.2.1. Tips for instrumenting Oracle WebLogic Application Server

Tips when instrumenting Oracle WebLogic Application Server to collect response time breakdown data.

You must provide correct information in the Application Server Instrumenter.

Server name is the name of the server to instrument. For example, for Oracle WebLogic Application Server 10.3 running on Microsoft Windows with the default sample application MedRec installed, the server name is MedRecServer.

Server home is the path to the server bin directory. For example, for Oracle WebLogic Application Server 10.3 running on Microsoft Windows with the default sample application MedRec installed, the server home is: C:\Oracle\Middleware\wlserver_10.3\samples\domains\medrec.

Start script is the script, a .cmd or .sh file, used to start the Oracle WebLogic Application Server. For example, for Oracle WebLogic Application Server 10.3 running on Microsoft Windows with the default sample application MedRec installed, the start script is C:\Oracle\Middleware\wlserver_10.3\samples\domains\medrec\bin\startWebLogic.cmd.

Server JVM is the type of Java. Virtual Machine (JVM) used by Oracle WebLogic Application Server. To determine the server JVM, examine the system processes while the server is running and see whether the JRockit JVM or the Oracle JVM is active.


1.3.2.2. Tips for instrumenting WebSphere Application Server

Follow these tips when you instrument WebSphere Application Server to collect response time breakdown data.

You must provide correct information in the Application Server Instrumenter.

Server home is the complete path to the WebSphere Application Server installation directory. By default, on Microsoft Windows the server home is C:\\IBM\WebSphere\AppServer. In Linux and AIX , the default server home is /opt/IBM/WebSphere/AppServer.

Server name is the name of the WebSphere Application Server instance to instrument. To see a list of server names, change to the bin directory, and type this command at a command prompt: wsadmin -conntype none -c "puts stdout [$AdminConfig list Server]".

An example of output from this command is as follows:

WASX7357I: By request, this scripting client is not connected to any server process. Certain configuration and application operations will be available in local mode. server1(cells/MachinenameNode01Cell/nodes/MachinenameNode01/servers/server1|server.xml#Server_1183122130078)

In this case, server1 is the server name.

Profile name is the name of the profile that is associated with the server to instrument.

To see a list of profiles from WebSphere Application Server, change to the bin directory, and type this command at a command prompt: manageprofiles -listProfiles. By default, in Microsoft Windows the bin directory is C:\\IBM\WebSphere\AppServer\bin. In Linux and AIX, the default bin directory is /opt/IBM/WebSphere/AppServer/bin.


1.3.3. Instrument servers by using the command prompt

You must instrument application servers to collect response time breakdown data. You can use either a command prompt or graphical user interface to instrument application servers to work with the data collection infrastructure.

The data collection infrastructure must be installed on each computer from which you want to collect performance data. The application server must be running. You must have administrator or root user privileges to instrument servers.

  1. Open a command prompt, and go to the instrument_comp folder in the directory where the data collection infrastructure is installed. By default, in Microsoft Windows, this directory is C:\\IBM\SDP\DCI\rapa_prod\instrument_comp. In Linux and IBM AIX , this directory is /opt/IBM/SDP/DCI/rapa_prod/instrument_comp.
  2. Type the command name with the arguments to use to instrument a server. See the examples that follow. The instrumentation utility is instrumentServer.sh on AIX and Linux systems and instrumentServer.bat on Windows systems. Enter the command name with no arguments to see the syntax details for the command.
  3. After you have instrumented the application server, you might have to restart the application server. Instrumentation changes take effect after the application server is restarted.


Example

Assume that you must instrument a Windows computer that is configured as follows:

Type the following command and arguments:

instrumentServer -install -type was7 -serverName my_Server2 -serverHome "C:\Program Files\was7.0" -serverVMArch 64 -user my_WAS_userId -password my_WAS_password -profileName default

To instrument a Linux computer that is equipped with a BEA WebLogic 10 application server, with configuration details as indicated, using the 32-bit version of JRockit JVM, type the following command and arguments:

./instrumentServer.sh -install -type wls10 -serverName server1 -serverHome /opt/bea/weblogic10 -serverVM oracle -serverVMArch 32 -startScript /opt/bea/weblogic10/mydomain/startWebLogic.sh

Repeat the instrumentation steps for each application server that is involved in data collection for the applications that you will profile. Typically, there will be only one application server. You can instrument only one local application server per computer.


1.3.4. Remove instrumentation

Before you uninstall the data collection infrastructure, you must remove instrumentation from all application servers that were instrumented to work with the data collection infrastructure.

To remove the instrumentation from an application server:

  1. Click Start > Programs > IBM Data Collection Infrastructure > Application Server Instrumenter. On the IBM AIX operating system, type /DCI/rapa_prod/instrument_comp/ASI at a command prompt to start the Application Server Instrumenter.
  2. Select the server to remove the instrumentation from.
  3. Click Uninstrument Server.
  4. Restart the server if prompted to do so.

You can uninstall the data collection infrastructure.


1.3.5. Remove instrumentation using the command prompt

Before you uninstall the data collection infrastructure, you must remove instrumentation from all application servers that were instrumented to work with the data collection infrastructure.

If you have uninstalled the application server or removed an instance of the application server, you cannot use the instrumentation utility to remove instrumentation from the server. This situation will block the data collection infrastructure uninstall process. Do not uninstall an application server before you have removed instrumentation from the application server.

Instrumented servers are listed in the file InstrumentationRegistry.xml. After you have removed instrumentation from a server, the InstrumentationRegistry.xml file will be empty of references to any application server. If you uninstall an application server before you have removed instrumentation, to uninstall the data collection infrastructure you must edit InstrumentationRegistry.xml to remove the applicationServer element for the application server that you uninstalled.

To remove instrumentation from application servers:

  1. Open a command prompt, and change directories to the instrument_comp folder in the data collection infrastructure installation directory. By default, on Microsoft Windows this directory is C:\\IBM\SDP\DCI\rapa_prod\instrument_comp. On Linux and IBM AIX , this directory is /opt/IBM/SDP/DCI/rapa_prod/instrument_comp.
  2. Type the command name with the -uninstall argument and all of the other arguments usedd when instrumenting the server. The instrumentation utility, which is also used to remove instrumentation from servers, is instrumentServer.sh on AIX and Linux systems and instrumentServer.bat on Windows systems. Enter the command name with no arguments to see the syntax details for the command.
  3. Restart the server if prompted to do so.

You can uninstall the data collection infrastructure.