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.

If any of my software has been helpful to you -or your company-, and you feel like expressing your gratitude beyond saying "Thank you" -which is also appreciated-, please note that I have an Amazon Wish List containing several inexpensive items.

Download

Latest version 1.0.3 released June 16, 2009

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


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.


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.


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