Home

Installing Performance Inspector

Installation
Profiling WebSphere
Verification
- Treetest Syntax
- Treetest Examples

Installation

We have attempted to present a consistent interface across all of our supported platforms. Although the tinstall script is used to install the package on all platforms, there are always platform specific requirements and procedures. Use the following links to view our platform specific installation instructions and information:

Profiling WebSphere®

Since many WebSphere® applications use multiple JVMs, environment variables generally do not work because they only apply to the initial JVM. Instead, the JPROF options need to be added to server.xml, the Websphere Application Server configuration file, to guarantee that JPROF is attached to the correct JVM.

As an alternative, you could create a server1.bat file to use with startserver, such as:

    /Websphere/AppServer/profiles/default/bin/startserver server1 -script server1.bat

Thus, you can modify this file to include the appropriate JVMTI or JVMPI commands you want to use whenever you start the server.

Verification

If you have any doubts about whether you have correctly installed Performance Inspector, you can verify that it is working properly by using treetest. The treetest testcase also provides a good example of how to control Performance Inspector from within a Java application.

Treetest Syntax


Usage: treetest iterations [idle] [verbose] [itrace|rtdcmds=xxxx]
This is the call tree with percentages:

main100 --> mainA30 --> mainAA10
                    --> mainAB20
        --> mainB70 --> mainBA30
                    --> mainBB40

The main100 method calls two methods, mainA30 and mainB70, with a cumulative execution time of 30 and 70 percent, respectively. The mainA30 method calls mainAA10 and mainAB20, while mainB70 calls mainBA30 and mainBB40. The number at the end of each method name indicates the percentage of the execution time it uses by looping 1000, 2000, 3000, or 4000 times, respectively.

The examples at the end of this section will demonstrate how you can you can verify that Performance Inspector is working properly by examining the relative amount of time or events associated with each of these mainXXnn methods.

iterations is the number of times main100 is executed.
idle indicates that the idleXXnn methods, which sleep for 10 milliseconds instead of looping 1000 times, should be executed instead of the mainXXnn methods. A much smaller number of iterations should be used with idle.
verbose writes the total number of times the mainXXnn loops have been executed to stdout after each call to main100, providing status and generating some strings which will eventually be garbage collected.
itrace calls the jperf/RTDriver class to turn instruction tracing on and off around one additional call to main100 or idle100, after the specified number of iterations has been executed.
rtdcmds=xxxx specifies a string of RTDriver commands, separated by commas, to be sent to JPROF. Following the execution of the specified number of iterations, each command in xxxx is sent to JPROF using the jperf/RTDriver class, with one more call to main100 or idle100 after each command. You must have JPerf.jar in your class path to use this parameter.

Treetest Examples

All of the treetest examples use JVMTI (JVM Tools Interface), which is only available on Java 5.0 and later versions. To use the older JVMPI (JVM Profiler Interface), which is only available on Java 5.0 and earlier versions, simply use -Xrunjprof: instead of -agentlib:jprof= wherever it appears.

If PTT is supported on your platform and JPerf.jar is in your class path, the simplest test of Performance Inspector is:

java -agentlib:jprof=callflow,nopidx treetest 100000 verbose rtdcmds=start,end

This executes the main100 method 100000 times to guarantee that all of the mainXXnn methods have been compiled, then it executes it one more time between start and end RTDriver commands. The log-rt.1 output file contains the information collected between those commands. The information we want can be extracted using:

grep treetest.main log-rt.1

On Windows, which does not provide a grep command, use find instead:

find treetest.main log-rt.1

The fourth column of data will be the number of instructions executed by each method, the ptt_insts metric. If everything is working properly, the percentage of total instructions associated with each of the mainXXnn methods should be close to nn percent.

The next column in log-rt.1 represents the number of machine cycles associated with each method, the ptt_cycles metric. Because ptt_cycles is not a stable metric like ptt_insts, the percentages will not be as accurate.

Note that you may not see all of the methods in log-rt.1. This is because the Java compiler may convert them to inline methods, which do not usually generate the method entry and exit events used by JPROF to perform the profiling. To see them, you have to disable inlining by specifying the appropriate option for your version of Java.

For JVMTI only, you can also test callstack sampling of idle threads with the following test:

java -agentlib:jprof=scs=idle,start,nopidx treetest 10 idle verbose

This test does not require JPerf.jar to be in your class path because the rtdcmds=xxxx parameter was not specified.

You may not be able to simply use grep to view the number of samples associated with each idleXXnn method. Although the samples are associated with the idleXXnn methods on Windows, on AIX the samples are associated with the java/lang/Thread.sleep method which each idleXXnn method calls. Thus, you may need to view log-rt.1 with an editor to verify the results. If everything is working properly, the percentage of total samples associated with each of the idleXXnn methods should be close to nn percent.

Home