The HPROF Agent

To illustrate the power of the JVMPI and show how it may be utilized, we describe some of the features in the HPROF agent, a simple profiler agent shipped with JDK 1.2. The HPROF agent is a dynamically-linked library shipped with JDK 1.2. It interacts with the JVMPI and presents profiling information either to the user directly or through profiler front-ends.

We can invoke the HPROF agent by passing a special option to the Java virtual machine:

ProgName is the name of a Java application. Note that we pass the -Xrunhprof option to java, the optimized version of the Java virtual machine. We need not rely on a specially instrumented version of the virtual machine to support profiling.

Depending on the type of profiling requested, HPROF instructs the virtual machine to send it the relevant profiling events. It gathers the event data into profiling information and outputs the result by default to a file. For example, the following command obtains the heap allocation profile for running a program:

Figure 2 contains the heap allocation profile generated by running the Java compiler (javac) on a set of input files. We only show parts of the profiler output here due to the lack of space. A crucial piece of information in heap profile is the amount of allocation that occurs in various parts of the program. The SITES record above tells us that 9.18% of live objects are character arrays. Note that the amount of live data is only a fraction of the total allocation that has occurred at a given site; the rest has been garbage collected.

**Figure 2:** HPROF Heap Allocation Profile
$\begin{figure}{\small \begin{tex2html_preform}\begin{verbatim}SITES BEGIN (orde... ...verbatim}\end{tex2html_preform}} \vspace{-2ex} \vspace{3ex} \hrule \end{figure}$

A good way to relate allocation sites to the source code is to record the dynamic stack traces that led to the heap allocation. Figure 3 shows another part of the profiler output that illustrates the stack traces referred to by the four allocation sites presented in Figure 2.

**Figure 3:** HPROF Stack Traces
$\begin{figure}{\small \begin{tex2html_preform}\begin{verbatim}THREAD START (obj... ...verbatim}\end{tex2html_preform}} \vspace{-2ex} \vspace{3ex} \hrule \end{figure}$

Each frame in the stack trace contains class name, method name, source file name, and the line number. The user can set the maximum number of frames collected by the HPROF agent. The default limit is 4. Stack traces reveal not only which methods performed heap allocation, but also which methods were ultimately responsible for making calls that resulted in memory allocation. For example, in the heap profile above, instances of the same java/util/Hashtable$Entry class are allocated in traces 1091 and 1264, each originated from different methods.

The HPROF agent has built-in support for profiling CPU usage. For example, Figure 4 is part of the generated output after the HPROF agent performs sampling-based CPU time profiling on the javac compiler.

**Figure:** HPROF Profile of CPU Usage Hot Spots
$\begin{figure}{\small \begin{tex2html_preform}\begin{verbatim}CPU SAMPLES BEGIN... ...CPU SAMPLES END\end{verbatim}\end{tex2html_preform}} \vspace{-2ex} \end{figure}$

The HPROF agent periodically samples the stack of all running threads to record the most frequently active stack traces. The count field above indicates how many times a particular stack trace was found to be active. These stack traces correspond to the CPU usage hot spots in the application.

The HPROF agent can also report complete heap dumps and monitor contention information. Due to the lack of space, we will not list more examples of how the HPROF agent presents the information obtained through the profiling interface. However, we are ready to explain the details of how various profiling interface features are supported in the virtual machine.