Document the heap profile format.

This resolves #258.
This commit is contained in:
Jason Evans 2016-02-24 15:35:24 -08:00
parent f591d2611a
commit 5ec703dd33

View File

@ -1191,7 +1191,8 @@ malloc_conf = "xmalloc:true";]]></programlisting>
the <command>jeprof</command> command, which is based on the
<command>pprof</command> that is developed as part of the <ulink
url="http://code.google.com/p/gperftools/">gperftools
package</ulink>.</para></listitem>
package</ulink>. See <link linkend="heap_profile_format">HEAP PROFILE
FORMAT</link> for heap profile format documentation.</para></listitem>
</varlistentry>
<varlistentry id="opt.prof_prefix">
@ -2623,6 +2624,53 @@ typedef struct {
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="heap_profile_format">
<title>HEAP PROFILE FORMAT</title>
<para>Although the heap profiling functionality was originally designed to
be compatible with the
<command>pprof</command> command that is developed as part of the <ulink
url="http://code.google.com/p/gperftools/">gperftools
package</ulink>, the addition of per thread heap profiling functionality
required a different heap profile format. The <command>jeprof</command>
command is derived from <command>pprof</command>, with enhancements to
support the heap profile format described here.</para>
<para>In the following hypothetical heap profile, <constant>[...]</constant>
indicates elision for the sake of compactness. <programlisting><![CDATA[
heap_v2/524288
t*: 28106: 56637512 [0: 0]
[...]
t3: 352: 16777344 [0: 0]
[...]
t99: 17754: 29341640 [0: 0]
[...]
@ 0x5f86da8 0x5f5a1dc [...] 0x29e4d4e 0xa200316 0xabb2988 [...]
t*: 13: 6688 [0: 0]
t3: 12: 6496 [0: ]
t99: 1: 192 [0: 0]
[...]
MAPPED_LIBRARIES:
[...]]]></programlisting> The following matches the above heap profile, but most
tokens are replaced with <constant>&lt;description&gt;</constant> to indicate
descriptions of the corresponding fields. <programlisting><![CDATA[
<heap_profile_format_version>/<mean_sample_interval>
<aggregate>: <curobjs>: <curbytes> [<cumobjs>: <cumbytes>]
[...]
<thread_3_aggregate>: <curobjs>: <curbytes>[<cumobjs>: <cumbytes>]
[...]
<thread_99_aggregate>: <curobjs>: <curbytes>[<cumobjs>: <cumbytes>]
[...]
@ <top_frame> <frame> [...] <frame> <frame> <frame> [...]
<backtrace_aggregate>: <curobjs>: <curbytes> [<cumobjs>: <cumbytes>]
<backtrace_thread_3>: <curobjs>: <curbytes> [<cumobjs>: <cumbytes>]
<backtrace_thread_99>: <curobjs>: <curbytes> [<cumobjs>: <cumbytes>]
[...]
MAPPED_LIBRARIES:
</proc/<pid>/maps>]]></programlisting></para>
</refsect1>
<refsect1 id="debugging_malloc_problems">
<title>DEBUGGING MALLOC PROBLEMS</title>
<para>When debugging, it is a good idea to configure/build jemalloc with