HPROF Binary Format

Taken from the HPROF manual (demo/jvmti/hprof/src/manual.html) delivered with the JDK.

The basic fields in the binary output are u1 (1 byte), u2 (2 byte), u4 (4 byte), and u8 (8 byte). An ID in this implementation is a u4, however the size of an ID is really determined by the "size of identifiers" field in the header.

WARNING: This format is still considered highly experimental, however, all attempts were made to match the format of past HPROF implementations.

The binary output begins with the information:

[u1]*
An initial NULL terminated series of bytes representing the format name and version, in this implementation and historically, the string "JAVA PROFILE 1.0.1" (18 u1 bytes) followed by a NULL byte. If the TAG "HEAP DUMP SEGMENT" is used this string will be "JAVA PROFILE 1.0.2".
u4
size of identifiers. Identifiers are used to represent UTF8 strings, objects, stack traces, etc. They can have the same size as host pointers or sizeof(void*), but are not required to be.
u4
high word of number of milliseconds since 0:00 GMT, 1/1/70
u4
low word of number of milliseconds since 0:00 GMT, 1/1/70

Followed by a sequence of records that look like:

u1
TAG: denoting the type of the record
u4
TIME: number of microseconds since the time stamp in the header
u4
LENGTH: number of bytes that follow this u4 field and belong to this record
[u1]*
BODY: as many bytes as specified in the above u4 field


The following TAGs are supported:

STRING IN UTF8
0x01
ID
ID for this string
[u1]*
UTF8 characters for string (NOT NULL terminated)

LOAD CLASS
0x02
u4
class serial number (always > 0)
ID
class object ID
u4
stack trace serial number
ID
class name string ID

UNLOAD CLASS
0x03
u4
class serial number

STACK FRAME
0x04
ID
stack frame ID
ID
method name string ID
ID
method signature string ID
ID
source file name string ID
u4
class serial number
u4
> 0
line number
0
no line information available
-1
unknown location
-2
compiled method (Not implemented)
-3
native method (Not implemented)


STACK TRACE
0x05
u4
stack trace serial number
u4
thread serial number
u4
number of frames
[ID]*
series of stack frame ID's

ALLOC SITES
0x06
u2
Bit mask flags:
0x1
incremental vs. complete
0x2
sorted by allocation vs. line
0x4
whether to force GC (Not Implemented)

u4
cutoff ratio (floating point)
u4
total live bytes
u4
total live instances
u8
total bytes allocated
u8
total instances allocated
u4
number of sites that follow:
u1
array indicator: 0 means not an array, non-zero means an array of this type (See Basic Type)
u4
class serial number
u4
stack trace serial number
u4
number of live bytes
u4
number of live instances
u4
number of bytes allocated
u4
number of instances allocated


HEAP SUMMARY
0x07
u4
total live bytes
u4
total live instances
u8
total bytes allocated
u8
total instances allocated

START THREAD
0x0A
u4
thread serial number
ID
thread object ID
u4
stack trace serial number
ID
thread name string ID
ID
thread group name ID
ID
thread parent group name ID

END THREAD
0x0B
u4
thread serial number

HEAP DUMP
or
HEAP DUMP SEGMENT
0x0C
or
0x1C
Contains any number of sub-tags, each begins a u1 field (no order implied here):
ROOT UNKNOWN
0xFF
ID
object ID

ROOT JNI GLOBAL
0x01
ID
object ID
ID
JNI global ref ID

ROOT JNI LOCAL
0x02
ID
object ID
u4
thread serial number
u4
frame number in stack trace (-1 for empty)

ROOT JAVA FRAME
0x03
ID
object ID
u4
thread serial number
u4
frame number in stack trace (-1 for empty)

ROOT NATIVE STACK
0x04
ID
object ID
u4
thread serial number

ROOT STICKY CLASS
0x05
ID
object ID

ROOT THREAD BLOCK
0x06
ID
object ID
u4
thread serial number

ROOT MONITOR USED
0x07
ID
object ID

ROOT THREAD OBJECT
0x08
ID
thread object ID
u4
thread serial number
u4
stack trace serial number

CLASS DUMP
0x20
ID
class object ID
u4
stack trace serial number
ID
super class object ID
ID
class loader object ID
ID
signers object ID
ID
protection domain object ID
ID
reserved
ID
reserved
u4
instance size (in bytes)
u2
size of constant pool and number of records that follow:
u2
constant pool index
u1
type of entry: (See Basic Type)
value
value of entry (u1, u2, u4, or u8 based on type of entry)

u2
Number of static fields:
ID
static field name string ID
u1
type of field: (See Basic Type)
value
value of entry (u1, u2, u4, or u8 based on type of field)

u2
Number of instance fields (not including super class's)
ID
field name string ID
u1
type of field: (See Basic Type)


INSTANCE DUMP
0x21

ID
object ID
u4
stack trace serial number
ID
class object ID
u4
number of bytes that follow
[value]*
instance field values (this class, followed by super class, etc)

OBJECT ARRAY DUMP
0x22

ID
array object ID
u4
stack trace serial number
u4
number of elements
ID
array class object ID
[ID]*
elements

PRIMITIVE ARRAY DUMP
0x23
ID
array object ID
u4
stack trace serial number
u4
number of elements
u1
element type (See Basic Type)
[u1]*
elements (packed array)


HEAP DUMP END
0x2C
Terminates a series of HEAP DUMP SEGMENTS.  Concatenation of HEAP DUMP SEGMENTS equals a HEAP DUMP.
CPU SAMPLES
0x0D
u4
total number of samples
u4
number of traces that follow:
u4
number of samples
u4
stack trace serial number


CONTROL SETTINGS
0x0E
u4
Bit mask flags:
0x1
alloc traces on/off
0x2
cpu sampling on/off

u2
stack trace depth


Basic Type
2
object
4
boolean
5
char
6
float
7
double
8
byte
9
short
10
int
11
long

Handling of Arrays

There will be a "LOAD CLASS" tag for type type of each array in the dump. In the LOAD CLASS record, the class name string ID will refer to a string with a human-readable name of the array type that is formatted as the type name would be in Java source code. Thus, the LOAD CLASS record for the type char[] will be "char[]", for short[][][] will be "short[][][]" and for MyType[] will be "MyType[]".

Source Code

The source to HPROF is available in the JDK download in the demo/jvmti/hprof directory.

*As used on this web site, the terms "Java Virtual Machine" or "JVM" mean a virtual machine for the Java platform.