HPROF is a tool for heap and CPU profiling shipped with every JDK release. It is a dynamic-link library (DLL) that interfaces with the Java Virtual Machine (JVM) using the Java Virtual Machine Tool Interface (JVM TI). The tool writes profiling information either to a file or to a socket in ASCII or binary format. This information can be further processed by a profiler front end tool.
The HPROF tool is capable of presenting CPU usage, heap allocation statistics, and monitor contention profiles. In addition, it can report complete heap dumps and states of all the monitors and threads in the JVM. In terms of diagnosing problems, HPROF is useful when analyzing performance, lock contention, memory leaks, and other issues.
In addition to the HPROF library, the JDK includes the source for HPROF as JVM TI demonstration code. This code is located in the $JAVA_HOME/demo/jvmti/hprof directory.
The following sections describe troubleshooting techniques with HPROF tool.
Invoke the HPROF tool as shown in Example 2-6.
Depending on the type of profiling requested, HPROF instructs the JVM to send it the relevant events. The tool then processes the event data into profiling information. For example, the following command obtains the heap allocation profile:
The complete list of options is printed when the HPROF agent is provided with the help option, as shown in Example 2-7.
By default, heap profiling information (sites and dump) is written out to java.hprof.txt (in ASCII) in the current working directory.
The output is normally generated when the JVM exits, although this can be disabled by setting the doe (dump on exit) option to n (doe=n). In addition, a profile is generated when Ctrl+\ (on Oracle and Linux operating systems) or Ctrl-Break (on Windows) is pressed. On Oracle Solaris and Linux operating systems a profile is also generated when a QUIT signal is received by a process (kill -QUIT pid). If Ctrl+\ or Ctrl-Break is pressed multiple times, then multiple profiles are generated to the one file.
The output in most cases will contain IDs for traces, threads, and objects. Each type of ID will typically start with a different number than the other IDs. For example, traces might start with 300000.
Example 2-8 is a heap allocation profile generated by running the Java compiler (javac) on a set of input files. Only parts of the profiler output are shown here.
A crucial piece of information in the heap profile is the amount of allocation that occurs in various parts of the program. The preceding SITES records show that 44.13% of the total space was allocated for the java.util.zip.ZipEntry objects.
A good way to relate allocation sites to the source code is to record the dynamic stack traces that led to the heap allocation. Example 2-9 shows another part of the profiler output. It illustrates the stack traces referred to by the four allocation sites in the preceding output.
Each frame in the stack trace contains a class name, a method name, a 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 four. 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.
A heap dump can be obtained using the heap=dump option. The heap dump is in either ASCII or binary format, depending on the setting of the format option. Tools such as jhat use binary format and therefore, the format=b option is required. See The jhat Utility) for more details. When the binary format is specified, the dump includes primitive type instance fields and primitive array content.
Example 2-10 shows the command that produces a complete dump in ASCII text format of the current live objects in the heap from executing the javac compiler:
The output is a large file. It consists of the root set as determined by the garbage collector, and an entry for each Java object in the heap that can be reached from the root set. The following is a selection of records from a sample heap dump.
Each record is a ROOT, OBJ, CLS, or ARR to represent a root, an object instance, a class, or an array. The hexadecimal numbers are identifiers assigned by HPROF. These numbers are used to show the references from an object to another object. In the preceding example, the java.lang.Thread instance 50000114 has a reference to its thread group (50008c6c) and other objects.
In general, as the output is very large, it is necessary to use a tool to visualize or process the output of the heap dump. One such tool is jhat. See The jhat Utility.
The HPROF tool can collect CPU usage information by sampling threads. Example 2-11 shows how to generate a CPU usage sampling profile by running the javac compiler.
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 tool can collect CPU usage information by injecting code into every method entry and exit, thereby keeping track of exact method call counts and the time spent in each method. This process uses the bytecode index (BCI) and runs considerably slower than the cpu=samples option. Example 2-12 shows part of the CPU usage times profile output collected from a run of the javac compiler.
In this output, the count represents the true count of the number of times this method was entered, and the percentages represent a measure of thread CPU time spent in this method.
