Common usages of JPROF are:
JPROF functions are controlled by Java Invocation Parameters and by RTDRIVER commands from a command line or from Java.
JPROF causes significant application slowdown due to additional execution pathlength in the JVM, JIT, and JPROF due to instrumentation, the overhead associated with generating and handling the events used while profiling the application. This can be on the order of 1.5 to 10 times the original pathlength.
JPROF compensates for this overhead via "calibration", an automated process of calculating the amount of time spent performing the instrumentation, then removing that amount from all statistics reported about the functions that have been instrumented. Without calibration, it is often impossible to accurately determine the significance of small routines because they are overwhelmed by the instrumentation that has been inserted to measure them.
Please note that even with calibration, this instrumentation overhead may cause unexpected changes in your application. For example, increased pathlength can change cache behavior, wait times, and the behavior of background tasks.
Accuracy of calibration is achieved through the use of metrics, such as the number of instructions completed between events. The Per Thread Time (PTT) facility consists of kernel code that manages hardware counters to correctly assign metrics, such as time or instruction completed, to each thread. The availability of metrics, and even PTT, varies by platform.
When PTT is available, the number of instructions completed allows accurate calibration because null routines can be profiled to determine the minimum overhead associated with various events. When PTT is not available or not used, the metric is defaulted to elapsed machine cycles and the calibration may be much less accurate. See Calibration for a detailed description of how this calibration is performed.
The tracking of object allocations, the numbers of Allocated Objects (AO), Allocated Bytes (AB), Live Objects (LO), and Live Bytes (LB), does not need calibration, since these values are not changed by instrumentation.
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.
java -agentlib:jprof=tprof classfile
This data is post-processed using:
post
together with swtrace.nrm2, to produce tprof.out.
java -agentlib:jprof=callflow,start classfile
java -agentlib:jprof=calltree,objectinfo,start classfile
java -agentlib:jprof=callflow,start,record classfile
To playback the results, use:
java -agentlib:jprof=playback=pid
Where 'pid' is the process id of java when the recording was made.
java -agentlib:jprof=generic classfile
To use cycles on thread as the metric use:
java -agentlib:jprof=generic,ptt_cycles classfile
Additional options can be appended to this list by using the JPROFOPTS environment variable. This environment variable makes it easy to temporarily add options to JPROF without having to modify existing scripts.
Because 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. It is good
practice to save/back up the original version before modifying it.
One way to update the server.xml is to use a browser to access the
WebSphere Administrative Console and follow these steps:
-> Go to the WebSphere Administrative Console -> Servers -> Application Servers -> select server
-> Go to "Java and Process Management" -> Process Definition -> Java Virtual Machine
-> Go to the "Generic JVM Arguments" and enter the appropriate jprof options in the box.
-> Click OK and -> save.
Note: The options in the "Generic JVM Arguments" box are put on the JVM's command line for the server.
The parameter parser supports up to five ways to specify each option. For example, pidx, the option that adds the process id as a suffix to all file names, can be specified as pidx, +pidx, allpidx, -pidx, or nopidx. "all" is an alias for "+" and "no" is an alias for "-" to make the options as readable as possible.
Many options also have aliases, such as enableheapdump and its alias, ehd.
The most important two options are help and allhelp, since they are used to display the help information built into JPROF itself. help displays information about only the most commonly used options. allhelp displays information about all options, including debugging options and those that may be obsolete or are deprecated.
Since the help information is integrated into the option parser, the help and allhelp options produce the most up-to-date documentation available for JPROF. Follow this link to view the standard help listing in its current form.
When you specify callflow mode, you automatically get per thread instructions and per thread cycles as your metrics. If you do not want to use any metrics, which is commonly done when you are only interested in profiling memory usage or if you are not using our device driver, you can select calltree mode.
There are three kinds of metrics: physical, logical, and composite. Physical metrics define what data is gathered, while logical metrics define what data is displayed. Composite metrics are logical metrics which depend on multiple physical metrics.
All of the metrics that you specify are treated as logical metrics. That is, they will produce a column of output in the log-rt files. The physical metrics are implicitly specified by the set of logical metrics. The only times that this distinction is important is when you are doing metric scaling or using the record and playback modes.
Default metrics can be overridden using the metrics=metricname option, using any of the metric names above. Multiple metrics can be specified using a '+' between them. For example, metrics=ptt_insts+ptt_cycles is the default when callflow is specified.
All metrics can use :n as a suffix to shift out the last n decimal digits. All metrics ending with _cycles can be scaled to seconds, milliseconds, microseconds, or nanoseconds using :sec, :msec, :usec, or :nsec. You can add logical metrics using the metrics= option. For example, metrics=ptt_cycles+ptt_cycles:nsec will produce two columns of cycles on thread, first unscaled, then scaled to nanoseconds.
As another example, metrics=ptt_insts+ptt_cycles+cpi will produce the standard callflow output with an additional column for CPI. However, composite metrics, such as CPI, have no delta columns in log-rt.
You may also select any metric supported by our device driver on your platform. The list of valid metric names can be found just after the header in the log-msg file. Specify only the name, not the numbers or the brackets. For example, METRICS=L2_READ_MISS could be used to select read misses in the level 2 cache on a dual-core Pentium.
Each time that JPROF starts, it will check all of the files for the selected set of metrics in sequence number order. If it finds a file with matching header information, it will load its starting calibration statistics from that file. Otherwise, it will check the next file in the sequence. If it does not exist, a new set of statistics will be generated and saved to that file when JPROF terminates.
Mismatched headers are usually caused by switching JVMs or versions of JPROF. This matching process ensures the best possible match of calibration statistics to your current configuration. It is recommended that you run your application with JPROF at least once on a new configuration to allow good statistics to be generated before you start gathering information for analysis. The trainer.java program that is included in the package was specifically designed to train the calibration routines.
JPROF is controlled at runtime by commands from either the rtdriver command-line program or from the RtDriver class from within Java programs.
rtdriver command-line when in the piClient mode of operation, which is the default. All commands, except EXIT_RTDRIVER, are passed to JPROF for validation and execution.
The simplest case of using rtdriver, with client and server on the same machine, is shown below:
See the rtdriver documentation for a description of how to use a different host and/or port.
In piClient mode, the following commands are supported by JPROF:
| HELP | Displays the common rtdriver commands supported by JPROF. |
| ALLHELP | Displays all of the rtdriver commands supported by JPROF. |
| JPROFINFO | Displays the JPROF version information. |
| JPROFHELP | Displays the common JPROF options. |
| ALLJPROFHELP | Displays all of the JPROF options. |
Since the help information is integrated into the option parser, the help and allhelp options produce the most up-to-date documentation available for JPROF. Follow this link to view the standard RTDRIVER help listing in its current form.
These five commands should provide you with all of the help that you need while JPROF is executing.
The RtDriver.command method allows you to send any valid command to the copy of JPROF that was loaded by your JVM.
To send the start command, followed by the hd command, simply add these statements to your java program:
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.
This will cause "jitting" after n calls.
This will cause "jitting" after n calls.
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.
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: