JPROF - Java Profiler


Quick Start

A few quick examples of how to use JPROF are listed below. All of the examples use the JVM Tool Interface (JVMTI) to invoke 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. Additional examples can be found in Examples of Common Tasks.

Invocation Options

Metric Selection Options

Automatic Calibration Statistics

Runtime Control

JPROF is controlled at runtime by commands from either the rtdriver command-line program or from the RtDriver class from within Java programs.

Using piClient Mode

Using the RtDriver Class

Using Non-Interactive Commands

JPROF Reconfiguration (BETA)

JPROF Reconfiguration is still a BETA in this release, but it is believed to be stable and ready for testing by our users so that we can get feedback about usability.

Users do not need to terminate the JVM to change the JPROF options. When reconfig=optionstring is specified as a command, JPROF will terminate its normal processing and almost completely detach itself from the JVM. It will then restart as if -agentlib:jprof=optionstring had been specified when the JVM was started. The log-msg, log-jita2n, and log-jtnm files stay open and the sequence numbers on all other files, like log-rt and log-hd will continue to increase.

To minimize the execution footprint of JPROF until you wish to reconfigure it, you can explicitly send a detach command to JPROF. This discards almost all of the memory used by JPROF, except for the thread table, and turns off all event processing except for THREAD_END events. This is the same processing that is performed at the start of a reconfig= command.

Since many capabilities can only be enabled at JVM startup time, the enablereconfig option has been added. This enables all of the capabilities you might need when you reconfigure JPROF, but it does not immediately enable the features themselves.

Controlling Java Compilation

It is sometimes necessary to control the compilation of Java methods to properly profile your applications. For example, the inlining of small methods can make them disappear from reports because they no longer generate entry and exit events once they have been compiled. This section explains how to control the compilation.

Record and Playback Modes (Windows only)

When applications use most of available memory, the memory required to build callflow trees can significantly impact the application. To address this problem, we have created the record and playback modes.

During record mode, all events are recorded by writing them to log-trace. By default, no trees are built during record mode, so that there is almost no impact on application memory. To reduce the execution impact, the instrumentation used to capture the events only writes the information to a buffer and a separate thread performs the actual writing to disk. No other processing is performed at record time, unless the trees option is specified.

During playback mode, all of the events are read from log-trace and normal processing is performed. Since memory is no longer shared with the application, the trees can be much bigger than before. Gathering of calibration data is performed only on the first reading of the log-trace file and stored in log-trace-calib to speed up later processing of the same file.

All of the names of the output files have a 'p' appended to them. That is, log-msg becomes log-msgp and log-rt.1 becomes log-rtp.1. The headers of these playback files reflect the information at record time, not playback time, since playback can even be performed on a different JVM or operating system.

There are many additional advantages to playback mode, not the least of which is selective playback. That is, the data can be filtered at playback time to produce files that reflect activity only of specific methods and/or threads during specific time intervals. Any subset or combination of the physical metrics that were recorded can be specified as logical metrics at playback time.

To use record mode, simply include record among the specified options. To use playback mode, you execute java again with playback as the first JPROF option. You do not need to specify a classfile, since java is only used as scaffolding to load JPROF.

All of the options specified at playback time are appended to the options that were specified at record time. These merged options are the only differences that you should see in the file headers between the record and playback versions of the output files when the trees option is used at record time.

Since all JPROF options are processed from left to right, debug options and any options that are meaningless at playback time, like heapdump, are automatically reset when the playback option is parsed. Therefore, verbose or verbmsg must be specifed after the playback option if you wish to see verbose messages at playback time.

Metrics specified after the playback option are logical metrics that define the columns that will appear in the log-rtp files. Only metrics which use the physical metrics that were recorded can be specified. If generic or gencalib is specified, the first of these logical metrics will be used for the log-genp files.

Files Produced by JPROF

JPROF can generate a variety of files, based on the options that are specified. By default, all of the files are placed in the current directory and use "log" as a prefix, such as log-msg.

The logpath=path option can be used to select a different directory, while the logprefix=prefix option will change the prefix used to create the filenames. For example, if logpath=abc,logprefix=def is specified, then log-msg would be replaced by abc/def-msg.

There is only one log-msg for any execution of JPROF. However, numbered instances of other files may be created in response to commands, as noted below.

Unless you specify nopidx, all of the files will use a _PID extension, such as log-msg_1234 for process 1234.

The types of files produced by JPROF and their contents are: