Common Usage of the Tools

All of the following examples use the JVM Profiler Interface (JVMPI) to invoke our Java Profiler (JPROF). However, JVMPI is no longer supported after Java 5. Its replacement, the JVM Tools Interface (JVMTI), is available on all Java versions beginning with Java 5.

To use JVMTI instead of JVMPI, simply replace -Xrunjprof: with -agentlib:jprof= wherever it appears below.

CPU Profiling (TProf)

Time profiling (tprof) is performed by the following steps:
1. Execute run.tprof in a window and follow the prompts until you are asked to press Enter to begin tracing.

2. Start your application in another window.

   If it is a Java application, use the following command:

   java   -Xrunjprof:tprof[,logpath=path]   classfile

   • logpath=path sets the path directory as the location for the JPROF output files. post requires a corresponding -jdir path/log option to locate these files. Use the appropriate slash ("/" or "\") for your operating system.

3. Press Enter when you are ready to begin tracing.

4. Press Enter again when you are ready to end tracing.

5. Perform the data reduction steps to produce tprof.out.

6. View the tprof reports.

tprof . swtrace . jprof . post . rtdriver

CPU Utilization (AI)

1. Execute swtrace ai

2. Output is written to stdout

   swtrace

Java CallFlow (Generic/Gencalib)

This produces a file which shows each method entry and exit and the number of instructions which were executed since the last method entry or exit. If you wish to have the raw number of instructions reported, use the generic option. If you would rather have the calibrated number of instructions reported, use the gencalib option.

The calibrated number of instructions is an estimate of the number of instructions which would have been executed if you were not using JPROF.

1. Start your Java application with the following command:

   java   -Xrunjprof:gencalib[,metrics=raw_cycles][,delay_start][,logpath=path]   classfile

   • metrics=raw_cycles changes the metric to raw_cycles, replacing the default of ptt_insts.

   • delay_start delays profiling until "start" is received from rtdriver.

   • logpath=path sets the path directory as the location for the JPROF output files. Use the appropriate slash ("/" or "\") for your operating system.

2. For runtime control, you can execute rtdriver -l in another window

   • start
   • end
   • exit_rtdriver

3. Output in log-gen.1_pid


jprof . rtdriver

Java Lock Monitor

1. Start your Java application with the following command:

   java   -Xrunjprof:classloadinfo[,logpath=path]   classfile

   • classloadinfo enables the tracking of classes

   • logpath=path sets the path directory as the location for the JPROF output files. Use the appropriate slash ("/" or "\") for your operating system.

2. For runtime control, you must execute rtdriver -l in another window
   • jlm | jlmstart
   • jlml | jlmstartlite
   • jd | jlmdump
   • jreset | jlmreset
   • jstop | jlmstop

3. Output is in log-jlm.n

   jlm . jprof . rtdriver

Heapdump

Analyzing the current state of the Java heap involves:
1. Dumping the contents of the Java heap using jprof and rtdriver:
   • Start your Java application with the following command:

     java   -Xrunjprof:ehd[,logpath=path]   classfile

     • ehd enables heap dump processing

     • logpath=path sets the path directory as the location for the JPROF output files. Use the appropriate slash ("/" or "\") for your operating system.

   • Execute rtdriver -l in another window and enter the hd command.

   • Class summary output is written to log-hdcnm.1_pid and the detailed heap dump is written to log-hd.1_pid.

2. Executing hdump to perform the data reduction on the log-hd.1_pid file to analyze leaks.

   hdump . jprof . rtdriver

Instruction Trace ( ITrace )

Instruction trace (ITrace) is performed by the following steps:
1. Execute run.itrace in a window and follow the prompts until you are asked to press Enter to begin tracing.

2. Start your application in another window.

   If it is a Java application, use the following command:

   java   -Xrunjprof:itrace[,logpath=path]   classfile

   • logpath=path sets the path directory as the location for the JPROF output files. post requires a corresponding -jdir path/log option to locate these files. Use the appropriate slash ("/" or "\") for your operating system.

3. Press Enter when you are ready to begin tracing.

4. Press Enter again when you are ready to end tracing.

   swtrace . itrace . post . jprof .

The trainer Program

trainer is a Java program that was designed to train the calibration routines in JPROF by providing repeated examples of the most common sequences of method. Most of the examples in trainer make nested calls 20 levels deep in an attempt to exceed the limits of any optimizer that would attempt to inline the sequences we are trying to calibrate. Over time, trainer evolved into an example which demonstrates how to control JPROF programmatically. The .java and .class files for trainer are included in the packages for all platforms.

The syntax for invoking trainer, which can be displayed using the "-?" parameter, is as follows:

trainer [itrace|rtdriver|rtdcmds=xxxx] [nonative] [warmup=n] [threads=m]

where:

• The itrace parameter invokes the JPerf Itraceon and Itraceoff commands around exactly one iteration of the trainer tests after warmup has completed.

• The rtdriver parameter invokes the RtDriver start and flush commands around exactly one iteration of the trainer tests after warmup has completed.

• The rtdcmds=xxxx parameter issues the sequence of RtDriver commands in xxxx, which are separated by commas, after warmup has completed. One iteration of the trainer tests is executed between each pair of commands. Thus, rtdcmds=start,flush is equivalent to rtdriver.

• The nonative parameter suppresses the execution of the tests involving native routines.

• The warmup=n parameter sets the number of times that the warmup tests will be executed. Each warmup iteration executes the set of trainer tests 100 times. One asterisk (*) is written to stdout after each of the first 50 tests and one asterisk is removed after each of the last 50 tests, giving the impression of a sweeping motion. The default warmup value is 100 iterations, which is 10000 times through the set of trainer tests.

• The threads=m parameter starts m additional Java threads before starting the warmup, each of which will execute the same number of trainer tests as the warmup, but without producing the sweeping asterisks.