HeatSeeker Documentation

HEATSEEKER DOCUMENTATION

Note there is a src drop in /heatseeker/ .

Introduction

This is a visual java hprof performance analyzer written in java and swing. It helps detect memory leaks and thread locks. It currently supportsthe following records.

java -Xrunhprof:help
Hprof usage: -Xrunhprof[:help]|[:<option>=<value>, ...]

Example: java -Xrunhprof:cpu=samples,file=log.txt,depth=3 FooClass

Note: format=b cannot be used with cpu=old|times

Option Name and Value	Description	Default
heap=dump\|sites\|all	heap profiling	all
cpu=samples\|times\|old	CPU usage	off
monitor=y\|n	monitor contention	n
format=a\|b	ascii or binary output	a
file=<file>	write data to file	java.hprof(.txt for ascii)
net=<host>:<port>	send data over a socket
depth=<size>	stack trace depth	4
cutoff=<value>	output cutoff point	0.0001
lineno=y\|n	line number in traces?	y
thread=y\|n	thread in traces?	n
doe=y\|n	dump on exit?	y
gc_okay=y\|n	GC okay during sampling	y

THREAD START
THREAD END
mark the lifetime of Java threads

TRACE represents a Java stack trace. Each trace consists
of a series of stack frames. Other records refer to
TRACEs to identify (1) where object allocations have
taken place, (2) the frames in which GC roots were
found, and (3) frequently executed methods.

HEAP DUMP is a complete snapshot of all live objects in the Java
heap. Following distinctions are made:

ROOT root set as determined by GC
CLS classes
OBJ instances
ARR arrays

SITES
is a sorted list of allocation sites. This identifies
the most heavily allocated object types, and the TRACE
at which those allocations occurred.

CPU SAMPLES
is a statistical profile of program execution. The VM
periodically samples all running threads, and assigns
a quantum to active TRACEs in those threads. Entries
in this record are TRACEs ranked by the percentage of
total quanta they consumed; top-ranked TRACEs are
typically hot spots in the program.

CPU TIME is a profile of program execution obtained by measuring
the time spent in individual methods (excluding the time
spent in callees), as well as by counting the number of
times each method is called. Entries in this record are
TRACEs ranked by the percentage of total CPU time. The
"count" field indicates the number of times each TRACE
is invoked.

MONITOR TIME
is a profile of monitor contention obtained by measuring
the time spent by a thread waiting to enter a monitor.
Entries in this record are TRACEs ranked by the percentage
of total monitor contention time and a brief description
of the monitor. The "count" field indicates the number of
times the monitor was contended at that TRACE.

MONITOR DUMP is a complete snapshot of all the monitors and threads in
the System.

RUNNING

Make sure you have the dependencies (crimson,jaxp,jakarta regexp) in your classpath you need to get all ther files from http://www.pointdefence.net/heatseeker/ including the .heatseeker.properties file which loads all the modules.

It looks for the properties file in the System.getProperty("user.home") directory path.

try

java -jar heatseeker.jar

java -classpath heatseeker.jar nu.datafuel.analysis.HeatSeeker [java.hprof.txt]

ANALYZING

Click the analyze button to find memory leaks, classes which match the regexp in the config window will be displayed

or run

java nu.datafuel.analysis.HeatSeeker /java.hprof.txt

DEMO

The binaries come with some examples classes that cause locks and leeks.

java -Xint -Xrunhprof:heap=all,doe=y,cpu=samples,depth=15,thread=y,monitor=y nu.datafuel.analysis.dummy.DummyLock
java -Xint -Xrunhprof:heap=all,doe=y,cpu=samples,depth=15,thread=y,monitor=y nu.datafuel.analysis.dummy.DummyLeak

or try

java -Xmx128M -Xint -Xrunhprof:net=127.0.0.1:10000,heap=all,doe=y,cpu=samples,depth=15,thread=y,monitor=y Resin $@

MODULES

In an attempt to decouple the grunt code from the application in the latest version analysis of the heapprof is done with pluggable modules ( I just couldn't resist ) simply write an implementation of Module (see javadoc) and begin to analyze the stuff yourself. Add the module class name to the heatseeker.conf module={module},{module},{module} and it will begin to use it. Really it can be a bit tricky to use and get results etc.. using my poorrly documented code. If you really need to write one let me know so I can help you =)

TROUBLESHOOTING

java.lang.OutOfMemoryError (I know theres some bad code in Heatseeker that eats memory)

or
Dumping contended monitor usage ... Java heap ...HPROF ERROR: heap dump size < 0

Increase the initial and maximum stack size used by the java virtual machine ( the default is 64M )

java
-Xms<size> set initial Java heap size
-Xmx<size> set maximum Java heap size
-Xss<size> set java thread stack size

example java -Xms128M -Xmx128M {classname} but to be safe I usually give it 1/2 a gig.

Hprof crashes

sometimes on Linux with java 1.4 I get weird hprof crashes
like seg faults or

HPROF ERROR: unable to resolve a method id
HPROF ERROR: got NULL trace in obj_alloc

I turn on -verbose and see they come from

sun.misc.Cleaner,java.lang.SystemClassLoaderAction and have a look around there..

#
# HotSpot Virtual Machine Error, Internal Error
# Please report this error at
# http://java.sun.com/cgi-bin/bugreport.cgi
#
# Java VM: Java HotSpot(TM) Client VM (1.4.1_01-b01 mixed mode)
#
# Error ID: 53414645504F494E540E4350500155
#
# Problematic Thread: prio=1 tid=0x0x8052918 nid=0x6d1 runnable
#

usually specifying

java -Xint

instead of the default

java -Xmixed

helps.

CONTACT THE AUTHOR

I would really like to hear how you use HeatSeeker. If I get no feedback it will probably become a commercial product. I am actually quite interested in providing the analysis code myself send me you tar.bz2 hprof files.

Email me heatseeker@pointdefence.net.nospam

THREAD START THREAD END	mark the lifetime of Java threads
TRACE	represents a Java stack trace. Each trace consists of a series of stack frames. Other records refer to TRACEs to identify (1) where object allocations have taken place, (2) the frames in which GC roots were found, and (3) frequently executed methods.
HEAP DUMP	is a complete snapshot of all live objects in the Java heap. Following distinctions are made: ROOT root set as determined by GC CLS classes OBJ instances ARR arrays
SITES	is a sorted list of allocation sites. This identifies the most heavily allocated object types, and the TRACE at which those allocations occurred.
CPU SAMPLES	is a statistical profile of program execution. The VM periodically samples all running threads, and assigns a quantum to active TRACEs in those threads. Entries in this record are TRACEs ranked by the percentage of total quanta they consumed; top-ranked TRACEs are typically hot spots in the program.
CPU TIME	is a profile of program execution obtained by measuring the time spent in individual methods (excluding the time spent in callees), as well as by counting the number of times each method is called. Entries in this record are TRACEs ranked by the percentage of total CPU time. The "count" field indicates the number of times each TRACE is invoked.
MONITOR TIME	is a profile of monitor contention obtained by measuring the time spent by a thread waiting to enter a monitor. Entries in this record are TRACEs ranked by the percentage of total monitor contention time and a brief description of the monitor. The "count" field indicates the number of times the monitor was contended at that TRACE.
MONITOR DUMP	is a complete snapshot of all the monitors and threads in the System.