HProf Ant Task

About hprof

hprof is a profiler which is built into the JDK. The java interpreter runs hprof when it is invoked with the option -Xrunhprof. By default, hprof dumps profile data to the file java.hprof.txt; this can be changed using the file option.

For more information on hprof, see the prophIt hprof page.

The hprof Ant task makes it easy to profile any Java program using the standard Ant java task.

Quick Start

To get quickly up and running with hprof:

Define a java Ant task in your Ant build file. Next, define the hprof taskdef in your build file according to the following example:
```
  <taskdef name="hprof" classname="net.sf.antprof.HProf" classpath="/path/to/antprof.jar" />
```

Wrap an hprof task around the java task:

  <target name="profile">
    <hprof>
      <java classpathref="class.path" classname="your.Application" />
    </hprof>
  </target>

Generate the profile data file by running:
```
  ant.bat profile
```
This command gathers CPU profile information and dumps it to the file java.hprof.txt when the Java VM exits.
Load the profile data file into prophIt, or inspect it in a text editor.

Common Options

Note : No task attributes are required.

Attribute	Description	Default
destfile	Specify an alternate output file name, according to the following example: <hprof destfile="app.hprof.txt"> <java classpathref="class.path" classname="your.Application" /> </hprof>	java.hprof.txt (java.hprof if `binary="yes"`)

Advanced Options

In descending order of general usefulness

Note : No task attributes are required.

Attribute Description Default

cpu
samples
When the 'times' is not set, hprof is in 'samples' mode. In 'samples' mode, hprof only interrupts the execution of the program a few times a second. JVM performance is not severely impacted, but not very much data is gathered for quick-running programs.
times
Use for programs that run in less than 10 seconds. In 'times' mode, hprof counts each method entry and exit, which is comprehensive but slow.
old
Emulate java -prof
off
Disable CPU profiling
See this paper on profiling methods for a discussion of samplinig and timing methods.
samples

stackDepth Increasing the stack depth can improve the resolution of the profile, at the expense of increasing the size of the data file.
Each time the hprof CPU profile is activated (either periodically in 'samples' mode, or for each function entry and exit in 'times' mode), hprof examines the call stack of each thread. A counter is maintained for each unique call stack. When the profile data is dumped to the data file or network connection, each call stack is written along with its counter. This option specifies the depth of each call stack.
6

hotspot If you are using the JDK 1.2, AntProf automatically turns off the HotSpot interpreter. If you are having trouble with hprof in a newer version of Java, you can manually specify hotspot="no" and AntProf will turn off HotSpot. Yes

netAddress Instructs hprof to send the profile data file out to a socket connection. Specified as <host>:<port>.
netAddress and destfile cannot both be used in the same task.

dumpThread Include the thread ID in the stack traces. If this option is not enabled, all matching stack traces are grouped together regardless of which thread they come from. No

binary Instruct hprof to use its binary format for the data file. This binary format is not documented so this option is not very useful. No

Attribute	Description	Default
cpu	samples When the 'times' is not set, hprof is in 'samples' mode. In 'samples' mode, hprof only interrupts the execution of the program a few times a second. JVM performance is not severely impacted, but not very much data is gathered for quick-running programs. times Use for programs that run in less than 10 seconds. In 'times' mode, hprof counts each method entry and exit, which is comprehensive but slow. old Emulate `java -prof` off Disable CPU profiling See this paper on profiling methods for a discussion of samplinig and timing methods.	samples
stackDepth	Increasing the stack depth can improve the resolution of the profile, at the expense of increasing the size of the data file. Each time the hprof CPU profile is activated (either periodically in 'samples' mode, or for each function entry and exit in 'times' mode), hprof examines the call stack of each thread. A counter is maintained for each unique call stack. When the profile data is dumped to the data file or network connection, each call stack is written along with its counter. This option specifies the depth of each call stack.	6
hotspot	If you are using the JDK 1.2, AntProf automatically turns off the HotSpot interpreter. If you are having trouble with hprof in a newer version of Java, you can manually specify `hotspot="no"` and AntProf will turn off HotSpot.	Yes
netAddress	Instructs hprof to send the profile data file out to a socket connection. Specified as <host>:<port>. `netAddress` and `destfile` cannot both be used in the same task.
dumpThread	Include the thread ID in the stack traces. If this option is not enabled, all matching stack traces are grouped together regardless of which thread they come from.	No
binary	Instruct hprof to use its binary format for the data file. This binary format is not documented so this option is not very useful.	No

AntProf notes

The hprof task always sets the java task attribute fork="yes", because the hprof library is only loaded by the JVM when a new JVM is started
You can see hprof usage information by invoking:
```
  java -Xrunhprof:help
```
The -Xrun<name> JVM option loads the library <name>.dll or <libname>.so and initializes it to use the JVMPI and JVMDI VM extension APIs. -Xrunhprof uses this feature to load hprof.dll or libhprof.so.

Ironworks.cc