ProfileViewer

by Ulf Dittmer and Greg White

This Java application reads profiling information produced by the Java interpreter and various flavours of the gprof tool and displays it for easy interpretation.

ProfileViewer was originally written by Greg White. Now that he no longer maintains it, he has released the source under the GNU General Public License. This page describes the changes that have been made since then; please do not contact Greg about this version.

These instructions accompany version 1.0 of ProfileViewer. See the COPYING file for copyright and license information.

Requirements: Java 1.4 or later

Although PV was conceived to handle the profiling output of Java 1, it works fine with the output generated by Java 2 if the "-prof" option is used (instead of the "-Xrunhprof" option, which generates Java 2 profiling output.)
For Java 2 either the "-Xrunhprof:cpu=old" or the "-classic -prof" switch can be used, neither of which worked without hiccups for me, but your mileage may vary.
I have no plans to add support for the Java 2 format to PV; the file format is very different. I'd be happy to integrate it if someone wants to take a shot at it, though. Thanks to enhancements by Luc Maisonobe, several different profiling formats can be recognized and read by PV.

Download

Latest version 1.0.3 released June 16, 2009

This Zip file contains the source files, the executable jar file and the documentation.


If you're using ProfileViewer, you might also be interested in Nathan Fiedlers JSwat, a GPL'ed Java debugger based on Suns JPDA debugging architecture. Especially interesting is its ability to attach to a running JVM, and to debug on remote hosts.

Table of Contents

Installing ProfileViewer

Unzip ProfileViewer.zip

Unzip the distribution into a directory of your choice.

Modify CLASSPATH

Add the jar files to the classpath environment variable. Alternatively, just double-click the ProfileViewer jar file.

Creating a Profile File

You create a profile file for an application by running the java interpreter with the -prof option (e.g. java -prof MyApp).

The procedure for creating a profile file for an applet is similar. Type

java -prof sun.applet.AppletViewer app.html

where app.html is the HTML file you normally pass to the applet viewer. When profiling applets, you may find that there is much more profiling information than you really want due to all of the supporting classes.

Here's some info about using the sun.misc.VM class to get more control over when profiling data is generated or written to disk. It's quoted verbatim from a post by Jens Alfke to the mrj-dev list. Note: This class seems to have changed quite a bit since I last used it in the Java 1.1 days. JDKs 1.3 and later do no longer have these methods, and I don't know where this functionality might be located now. Of course, the sun.* hierarchy is subject to change without notice, so this was to be expected.

What's less known is that you can drive the profiler yourself, and have 
it run only on the parts of your code you're interested in. (This also 
helps avoid buffer overflows with very large apps.) To do this, *don't* 
turn on profiling from JBindery. Instead, import the class "sun.misc.VM" 
and use the following static methods:

    /** Starts/resumes profiling */
    public static void resumeJavaMonitor();

    /** Stops profiling */
    public static void suspendJavaMonitor();

    /** Clears profile data */
    public static void resetJavaMonitor();

    /** Dumps profile data to "java.prof" (overwriting) */
    public static void writeJavaMonitorReport();

Your code might look like this:

    import sun.misc.VM;
    ...
    VM.resumeJavaMonitor();
    this.verySlowOperation();   // what you're profiling
    VM.suspendJavaMonitor();
    VM.writeJavaMonitorReport();

Note that you have to write the report manually; it won't be written 
automatically at quit if you didn't activate profiling in JBindery. Also 
note that if you try to write multiple reports, each will overwrite the 
last (unless you get tricky and use File.rename to rename the old one...)

Starting ProfileViewer

To start ProfileViewer, type:

java ProfileViewer Profile

where Profile optionally specifies the name of a profile file to load. If this parameter is not specified, ProfileViewer will start without loading a file. This assumes all jar files are in your classpath. Alternatively, Windows users can simply double-click the "runit.bat" file.

It is also possible to double-click the ProfileViewer Jar file.

The Screen

The main screen consists of three lists and a status line. The list to the left shows all methods known. The list to the upper right shows all callees (methods called by the currently selected method in the list to the left). The list to the lower right shows all callers (methods calling the currently selected method in the list to the left).

The format of each line in these lists is 

time calls method
where time and calls are shown as percentages by default, but they can be changed to show absolute values (time in milliseconds and calls by count).

All percentages are relative to the lifetime of the application. In the methods list, the percentage is an overall value for each method. In the callees list, percentages shown reflect calls made to each method from the selected method to the left. In the callers list, percentages shown reflect calls made from each method to the selected method to the left.

When showing absolute values, the methods list entries are totals for each method while in the callees and callers list, these numbers are only in relation to the selected method in the list on the left.

The status line at the bottom shows the full name of the currently selected method. This helps you to see names that might be too long otherwise.

Entries of the form "...<init>" indicate the constructor of the respective class, those of the form "...<clinit>" static initializers of the class.

General Usage Notes

Caveat

The information shown here is only as good as the information produced by the java interpreter. In some cases (especially recursion), the results don't seem to make any sense at all. If someone has pointers to better documentation about the profile information, I will be glad to include information here or change ProfileViewer to accommodate it.

Also note that Sun's documentation for javaprof (a text-based report tool for the profile file) says it will not work correctly for multi-threaded applications. I expect that this warning ought to be for the profile file itself, not just for javaprof.

Optimizing Your Program

See Java Optimization by Jonathan Hardwick for some excellent reading about optimization and Java. Unfortunately, it is no longer maintained.

Some Known Problems

If you have solutions or workarounds for these, please let me know.

Can't set the width of the split panes in the main window

The JSplitPane.setDividerLocation method should do that, but there's a registered bug in Swing 1.1 that prevents that from working. The dividers are movable, though, so this shouldn't be a big problem.

Windows JDK 1.3: Exclude dialog doesn't pick up the item in the last row

Workaround is to manually select another row or field before clicking "OK". This doesn't happen uder JDK 1.1/Swing 1.1.1. I don't know about JDK 1.2.

Other Profile Formats

Supported formats

As of version 1.0, ProfileViewer has been extended to support some other profile file formats. The supported formats are: These formats are recognized automatically on loading.

Working with gprof Profiles

Here's a brief rundown on how to obtain and use gprof profiles for native code (like C/C++/Fortran77/Pascal). If you have a test.c file containing the application, ... If you run into problems where ProfileViewer doesn't recognize the file format, or omits some methods that should be there, check the command line options with which gprof is run. In particular, the "-b" and "-z" options should be set.

Adding a Format

Adding support for a new profiler output format is quite simple.

The first step is to create your own parser as a class implementing the ProfileParser interface. This interface is limited to three methods: nextInvocationLine, stopParsing and getLineNo. The easiest way to do this is to start from the existing classes (ClassicJavaProfileParser and [Abstract|GNU|OSX|Solaris]GprofProfileParser).

The second step is to register your class in the parser factory method ProfileParserFactory.buildParser. This step is merely adding a two lines test in an existing if statement.

Back To Main Page