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

To use JVMPI instead of JVMTI, simply replace -agentlib:jprof= with -Xrunjprof: 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   -agentlib:jprof=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 Pathlength Profiling

1. Start your Java application with the following command:

   java   -agentlib:jprof=callflow[,start][,logpath=path]   classfile

   • callflow   implies metrics=ptt_insts+ptt_cycles. See Metrics for a discussion about metric selection.

   • start begins data collection immediately, instead of waiting 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. The following commands can be used:

   • start - Starts data collection.
   • end - Ends data collection, writes the data that has been collected, then resets all internal buffers.
   • flush - Writes the data that has been collected, but does not end or reset data collection.

3. Output in log-rt.1_pid

jprof . rtdriver

Java Object Profiling with Full Call Tree

1. Start your Java application with the following command:

   java   -agentlib:jprof=calltree,objectinfo[,hr][,sobjs][,start][,logpath=path]   classfile

   • calltree is used with object profiling because it implies nometrics, which turns off the metrics that are not required for this kind of profiling.

   • objectinfo indicates that we are interested in tracking both object allocations and frees. It also implies nomethodtypes, which eliminates the distinction between interpreted and compiled methods.

     Lines describing allocated objects are added after each node in the calltree where an allocation occurs. These lines use logical metrics for AllocatedObjects, AllocatedBytes, LiveObjects, and LiveBytes and display the class of the object, in parentheses, in same field that would have contained the name of the method.

   • hr or humanreadable adds extra blank lines around the lines describing the allocated objects to improve readability.

   • The sobjs option separates objects of the same class by size.

   • start begins data collection immediately, instead of waiting 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. The following commands can be used:

   • start - Starts data collection.
   • end - Ends data collection, writes the data that has been collected, then resets all internal buffers.
   • flush - Writes the data that has been collected, but does not end or reset data collection.

3. Output is in log-rt.1_pid

   jprof . rtdriver
   

Java Object Profiling with Reduced Call Tree

This feature is available only after JPROF version 8.8.0 and only using JVMTI.
1. Start your Java application with the following command:

   java   -agentlib:jprof=scs=allocated_bytes[=nn],objectinfo[,hr][,sobjs][,start][,logpath=path]   classfile

   • Rather than instrumenting every method entry and exit, scs=allocated_bytes samples the current call stack only when objects are allocated. This produces callflow trees only down to those places where objects are allocated.

   • Adding =nn samples the call stack only after nn or more bytes have been allocated. This can result in much fewer samples and faster execution, but it also means that only some of the allocations and frees are actually recorded. This option is useful when profiling very large applications.

   • objectinfo indicates that we are interested in tracking both object allocations and frees. It also implies nomethodtypes, which eliminates the distinction between interpreted and compiled methods.

     Lines describing allocated objects are added after each node in the calltree where an allocation occurs. These lines use logical metrics for AllocatedObjects, AllocatedBytes, LiveObjects, and LiveBytes and display the class of the object, in parentheses, in same field that would have contained the name of the method.

   • hr or humanreadable adds extra blank lines around the lines describing the allocated objects to improve readability.

   • The sobjs option separates objects of the same class by size.

   • start begins data collection immediately, instead of waiting 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. The following commands can be used:

   • start - Starts data collection.
   • end - Ends data collection, writes the data that has been collected, then resets all internal buffers.
   • flush - Writes the data that has been collected, but does not end or reset data collection.

3. Output is in log-rt.1_pid

   jprof . rtdriver
   

Java Profiling via Monitor Events

This feature is available only after JPROF version 8.8.0 and only using JVMTI.
1. Start your Java application with the following command:

   java   -agentlib:jprof=scs=monitor_contended_entered[+][=nn][,hr][,start][,logpath=path]   classfile

   • Rather than instrumenting every method entry and exit, scs=contended_monitor_entered samples the current call stack only when a MONITOR_CONTENDED_ENTERED event is received. This produces callflow trees only down to those places where the events were received.

   • The + indicates that you want to display the object classes associated with the events.

   • Adding =nn samples the call stack only after nn or more events have been received. This can result in much fewer samples and faster execution, but it also means that only some of the events are actually recorded. This option is useful when profiling very large applications.

   • hr or humanreadable, when used with the + option, improves readability by adding extra blank lines around the lines describing the object classes associated with the events.

   • start begins data collection immediately, instead of waiting 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. The following commands can be used:

   • start - Starts data collection.
   • end - Ends data collection, writes the data that has been collected, then resets all internal buffers.
   • flush - Writes the data that has been collected, but does not end or reset data collection.

3. Output is in log-rt.1_pid

   jprof . rtdriver
   

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   -agentlib:jprof=gencalib[,metrics=raw_cycles][,start][,logpath=path]   classfile

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

     start begins data collection immediately, instead of waiting 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. The following commands can be used:

   • start - Starts data collection.
   • end - Ends data collection, writes the data that has been collected, then resets all internal buffers.
   • flush - Writes the data that has been collected, but does not end or reset data collection.

3. Output in log-gen.1_pid

   jprof . rtdriver

Java Lock Monitor

1. Start your Java application with the following command:

   java   -agentlib:jprof=[,logpath=path]   classfile

   • 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   -agentlib:jprof=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   -agentlib:jprof=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

Record and Playback

1. To record all events for later playback, start your Java application with the following command:

   java   -agentlib:jprof=callflow,record[,objectinfo][,start][,logpath=path]   classfile

   • callflow puts JPROF in normal callflow gathering mode.

   • record sends a record of all events to log-trace and turns off tree building.

   • objectinfo can be used to record object allocations and frees.

   • start begins data collection immediately, instead of waiting 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. The following commands can be used:

   • start - Starts data collection.
   • end - Ends data collection, writes the data that has been collected, then resets all internal buffers.
   • flush - Writes the data that has been collected, but does not end or reset data collection.

3. All output is placed in log-trace_pid.

4. To playback the events into normal JPROF output files, use the following command:
   java   -agentlib:jprof=playback=pid

   jprof

Training Calibration

Calibration refers to the adjustment of an observed metric, usually ptt_insts, to compensate for the overhead imposed by observing that metric. To accurately perform this calibration, we must first train JPROF by gathering statistics about the overhead associated with the various events reported by the JVM.

If the start option is specified when JPROF is invoked, training can usually be achieved by simply observing JVM startup. However, profiling is usually started only after the application has been "warmed up" and frequently used methods have already been compiled by the JIT. In those cases, there will probably not be time to properly train the calibration routines before they are needed.

The calstats= and usestats= options are used to calculate, save, and restore the results of calibration training sessions. The calstats=filename option, defines a file for recording calibration statistics. If the file already exists, it will use the previous statistics and update them as needed. If the file does not exist, it will create it. The usestats=filename option, also reads the previous statistics, but makes no attempt to update the statistics, in an attempt to minimize overhead while profiling.

To be useful, training and profiling must be performed using nearly identical JPROF options. That is, the version, platform, and JVM information in the calstats file header must match the current environment. The metrics recorded in the calstats file must also match the metrics used when profiling. You will need to create a unique calstats file for each unique configuration you plan to use.

Typically, calstats= is used during training, such as:

java   -agentlib:jprof=callflow,calstats=statfile,start   trainer

while usestats= is used during profiling, such as:

java   -agentlib:jprof=callflow,usestats=statfile   classfile

trainer is a Java program that was specifically designed to train the calibration routines by providing repeated examples of the most common sequences of JVM events. 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 also 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.