Gitiles
Code Review Sign In
realtimeroboticsgroup.org / RealtimeRoboticsGroup / test / 745610d16119f59479f84918a66456ece9d6d461 / . / doc / heapprofile.html
blob: 3986a25fc97aa9fc12c799697c4414cea880f3cc [file] [log] [blame]
Austin Schuh745610d2015-09-06 18:19:50 -0700[diff] [blame^]1<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
2<HTML>
3
4<HEAD>
5 <link rel="stylesheet" href="designstyle.css">
6 <title>Gperftools Heap Profiler</title>
7</HEAD>
8
9<BODY>
10
11<p align=right>
12 <i>Last modified
13 <script type=text/javascript>
14 var lm = new Date(document.lastModified);
15 document.write(lm.toDateString());
16 </script></i>
17</p>
18
19<p>This is the heap profiler we use at Google, to explore how C++
20programs manage memory. This facility can be useful for</p>
21<ul>
22 <li> Figuring out what is in the program heap at any given time
23 <li> Locating memory leaks
24 <li> Finding places that do a lot of allocation
25</ul>
26
27<p>The profiling system instruments all allocations and frees. It
28keeps track of various pieces of information per allocation site. An
29allocation site is defined as the active stack trace at the call to
30<code>malloc</code>, <code>calloc</code>, <code>realloc</code>, or,
31<code>new</code>.</p>
32
33<p>There are three parts to using it: linking the library into an
34application, running the code, and analyzing the output.</p>
35
36
37<h1>Linking in the Library</h1>
38
39<p>To install the heap profiler into your executable, add
40<code>-ltcmalloc</code> to the link-time step for your executable.
41Also, while we don't necessarily recommend this form of usage, it's
42possible to add in the profiler at run-time using
43<code>LD_PRELOAD</code>:
44<pre>% env LD_PRELOAD="/usr/lib/libtcmalloc.so" &lt;binary&gt;</pre>
45
46<p>This does <i>not</i> turn on heap profiling; it just inserts the
47code. For that reason, it's practical to just always link
48<code>-ltcmalloc</code> into a binary while developing; that's what we
49do at Google. (However, since any user can turn on the profiler by
50setting an environment variable, it's not necessarily recommended to
51install profiler-linked binaries into a production, running
52system.) Note that if you wish to use the heap profiler, you must
53also use the tcmalloc memory-allocation library. There is no way
54currently to use the heap profiler separate from tcmalloc.</p>
55
56
57<h1>Running the Code</h1>
58
59<p>There are several alternatives to actually turn on heap profiling
60for a given run of an executable:</p>
61
62<ol>
63 <li> <p>Define the environment variable HEAPPROFILE to the filename
64 to dump the profile to. For instance, to profile
65 <code>/usr/local/bin/my_binary_compiled_with_tcmalloc</code>:</p>
66 <pre>% env HEAPPROFILE=/tmp/mybin.hprof /usr/local/bin/my_binary_compiled_with_tcmalloc</pre>
67 <li> <p>In your code, bracket the code you want profiled in calls to
68 <code>HeapProfilerStart()</code> and <code>HeapProfilerStop()</code>.
69 (These functions are declared in <code>&lt;gperftools/heap-profiler.h&gt;</code>.)
70 <code>HeapProfilerStart()</code> will take the
71 profile-filename-prefix as an argument. Then, as often as
72 you'd like before calling <code>HeapProfilerStop()</code>, you
73 can use <code>HeapProfilerDump()</code> or
74 <code>GetHeapProfile()</code> to examine the profile. In case
75 it's useful, <code>IsHeapProfilerRunning()</code> will tell you
76 whether you've already called HeapProfilerStart() or not.</p>
77</ol>
78
79
80<p>For security reasons, heap profiling will not write to a file --
81and is thus not usable -- for setuid programs.</p>
82
83<H2>Modifying Runtime Behavior</H2>
84
85<p>You can more finely control the behavior of the heap profiler via
86environment variables.</p>
87
88<table frame=box rules=sides cellpadding=5 width=100%>
89
90<tr valign=top>
91 <td><code>HEAP_PROFILE_ALLOCATION_INTERVAL</code></td>
92 <td>default: 1073741824 (1 Gb)</td>
93 <td>
94 Dump heap profiling information each time the specified number of
95 bytes has been allocated by the program.
96 </td>
97</tr>
98
99<tr valign=top>
100 <td><code>HEAP_PROFILE_INUSE_INTERVAL</code></td>
101 <td>default: 104857600 (100 Mb)</td>
102 <td>
103 Dump heap profiling information whenever the high-water memory
104 usage mark increases by the specified number of bytes.
105 </td>
106</tr>
107
108<tr valign=top>
109 <td><code>HEAP_PROFILE_TIME_INTERVAL</code></td>
110 <td>default: 0</td>
111 <td>
112 Dump heap profiling information each time the specified
113 number of seconds has elapsed.
114 </td>
115</tr>
116
117<tr valign=top>
118 <td><code>HEAP_PROFILE_MMAP</code></td>
119 <td>default: false</td>
120 <td>
121 Profile <code>mmap</code>, <code>mremap</code> and <code>sbrk</code>
122 calls in addition
123 to <code>malloc</code>, <code>calloc</code>, <code>realloc</code>,
124 and <code>new</code>. <b>NOTE:</b> this causes the profiler to
125 profile calls internal to tcmalloc, since tcmalloc and friends use
126 mmap and sbrk internally for allocations. One partial solution is
127 to filter these allocations out when running <code>pprof</code>,
128 with something like
129 <code>pprof --ignore='DoAllocWithArena|SbrkSysAllocator::Alloc|MmapSysAllocator::Alloc</code>.
130 </td>
131</tr>
132
133<tr valign=top>
134 <td><code>HEAP_PROFILE_ONLY_MMAP</code></td>
135 <td>default: false</td>
136 <td>
137 Only profile <code>mmap</code>, <code>mremap</code>, and <code>sbrk</code>
138 calls; do not profile
139 <code>malloc</code>, <code>calloc</code>, <code>realloc</code>,
140 or <code>new</code>.
141 </td>
142</tr>
143
144<tr valign=top>
145 <td><code>HEAP_PROFILE_MMAP_LOG</code></td>
146 <td>default: false</td>
147 <td>
148 Log <code>mmap</code>/<code>munmap</code> calls.
149 </td>
150</tr>
151
152</table>
153
154<H2>Checking for Leaks</H2>
155
156<p>You can use the heap profiler to manually check for leaks, for
157instance by reading the profiler output and looking for large
158allocations. However, for that task, it's easier to use the <A
159HREF="heap_checker.html">automatic heap-checking facility</A> built
160into tcmalloc.</p>
161
162
163<h1><a name="pprof">Analyzing the Output</a></h1>
164
165<p>If heap-profiling is turned on in a program, the program will
166periodically write profiles to the filesystem. The sequence of
167profiles will be named:</p>
168<pre>
169 &lt;prefix&gt;.0000.heap
170 &lt;prefix&gt;.0001.heap
171 &lt;prefix&gt;.0002.heap
172 ...
173</pre>
174<p>where <code>&lt;prefix&gt;</code> is the filename-prefix supplied
175when running the code (e.g. via the <code>HEAPPROFILE</code>
176environment variable). Note that if the supplied prefix
177does not start with a <code>/</code>, the profile files will be
178written to the program's working directory.</p>
179
180<p>The profile output can be viewed by passing it to the
181<code>pprof</code> tool -- the same tool that's used to analyze <A
182HREF="cpuprofile.html">CPU profiles</A>.
183
184<p>Here are some examples. These examples assume the binary is named
185<code>gfs_master</code>, and a sequence of heap profile files can be
186found in files named:</p>
187<pre>
188 /tmp/profile.0001.heap
189 /tmp/profile.0002.heap
190 ...
191 /tmp/profile.0100.heap
192</pre>
193
194<h3>Why is a process so big</h3>
195
196<pre>
197 % pprof --gv gfs_master /tmp/profile.0100.heap
198</pre>
199
200<p>This command will pop-up a <code>gv</code> window that displays
201the profile information as a directed graph. Here is a portion
202of the resulting output:</p>
203
204<p><center>
205<img src="heap-example1.png">
206</center></p>
207
208A few explanations:
209<ul>
210<li> <code>GFS_MasterChunk::AddServer</code> accounts for 255.6 MB
211 of the live memory, which is 25% of the total live memory.
212<li> <code>GFS_MasterChunkTable::UpdateState</code> is directly
213 accountable for 176.2 MB of the live memory (i.e., it directly
214 allocated 176.2 MB that has not been freed yet). Furthermore,
215 it and its callees are responsible for 729.9 MB. The
216 labels on the outgoing edges give a good indication of the
217 amount allocated by each callee.
218</ul>
219
220<h3>Comparing Profiles</h3>
221
222<p>You often want to skip allocations during the initialization phase
223of a program so you can find gradual memory leaks. One simple way to
224do this is to compare two profiles -- both collected after the program
225has been running for a while. Specify the name of the first profile
226using the <code>--base</code> option. For example:</p>
227<pre>
228 % pprof --base=/tmp/profile.0004.heap gfs_master /tmp/profile.0100.heap
229</pre>
230
231<p>The memory-usage in <code>/tmp/profile.0004.heap</code> will be
232subtracted from the memory-usage in
233<code>/tmp/profile.0100.heap</code> and the result will be
234displayed.</p>
235
236<h3>Text display</h3>
237
238<pre>
239% pprof --text gfs_master /tmp/profile.0100.heap
240 255.6 24.7% 24.7% 255.6 24.7% GFS_MasterChunk::AddServer
241 184.6 17.8% 42.5% 298.8 28.8% GFS_MasterChunkTable::Create
242 176.2 17.0% 59.5% 729.9 70.5% GFS_MasterChunkTable::UpdateState
243 169.8 16.4% 75.9% 169.8 16.4% PendingClone::PendingClone
244 76.3 7.4% 83.3% 76.3 7.4% __default_alloc_template::_S_chunk_alloc
245 49.5 4.8% 88.0% 49.5 4.8% hashtable::resize
246 ...
247</pre>
248
249<p>
250<ul>
251 <li> The first column contains the direct memory use in MB.
252 <li> The fourth column contains memory use by the procedure
253 and all of its callees.
254 <li> The second and fifth columns are just percentage
255 representations of the numbers in the first and fourth columns.
256 <li> The third column is a cumulative sum of the second column
257 (i.e., the <code>k</code>th entry in the third column is the
258 sum of the first <code>k</code> entries in the second column.)
259</ul>
260
261<h3>Ignoring or focusing on specific regions</h3>
262
263<p>The following command will give a graphical display of a subset of
264the call-graph. Only paths in the call-graph that match the regular
265expression <code>DataBuffer</code> are included:</p>
266<pre>
267% pprof --gv --focus=DataBuffer gfs_master /tmp/profile.0100.heap
268</pre>
269
270<p>Similarly, the following command will omit all paths subset of the
271call-graph. All paths in the call-graph that match the regular
272expression <code>DataBuffer</code> are discarded:</p>
273<pre>
274% pprof --gv --ignore=DataBuffer gfs_master /tmp/profile.0100.heap
275</pre>
276
277<h3>Total allocations + object-level information</h3>
278
279<p>All of the previous examples have displayed the amount of in-use
280space. I.e., the number of bytes that have been allocated but not
281freed. You can also get other types of information by supplying a
282flag to <code>pprof</code>:</p>
283
284<center>
285<table frame=box rules=sides cellpadding=5 width=100%>
286
287<tr valign=top>
288 <td><code>--inuse_space</code></td>
289 <td>
290 Display the number of in-use megabytes (i.e. space that has
291 been allocated but not freed). This is the default.
292 </td>
293</tr>
294
295<tr valign=top>
296 <td><code>--inuse_objects</code></td>
297 <td>
298 Display the number of in-use objects (i.e. number of
299 objects that have been allocated but not freed).
300 </td>
301</tr>
302
303<tr valign=top>
304 <td><code>--alloc_space</code></td>
305 <td>
306 Display the number of allocated megabytes. This includes
307 the space that has since been de-allocated. Use this
308 if you want to find the main allocation sites in the
309 program.
310 </td>
311</tr>
312
313<tr valign=top>
314 <td><code>--alloc_objects</code></td>
315 <td>
316 Display the number of allocated objects. This includes
317 the objects that have since been de-allocated. Use this
318 if you want to find the main allocation sites in the
319 program.
320 </td>
321
322</table>
323</center>
324
325
326<h3>Interactive mode</a></h3>
327
328<p>By default -- if you don't specify any flags to the contrary --
329pprof runs in interactive mode. At the <code>(pprof)</code> prompt,
330you can run many of the commands described above. You can type
331<code>help</code> for a list of what commands are available in
332interactive mode.</p>
333
334
335<h1>Caveats</h1>
336
337<ul>
338 <li> Heap profiling requires the use of libtcmalloc. This
339 requirement may be removed in a future version of the heap
340 profiler, and the heap profiler separated out into its own
341 library.
342
343 <li> If the program linked in a library that was not compiled
344 with enough symbolic information, all samples associated
345 with the library may be charged to the last symbol found
346 in the program before the library. This will artificially
347 inflate the count for that symbol.
348
349 <li> If you run the program on one machine, and profile it on
350 another, and the shared libraries are different on the two
351 machines, the profiling output may be confusing: samples that
352 fall within the shared libaries may be assigned to arbitrary
353 procedures.
354
355 <li> Several libraries, such as some STL implementations, do their
356 own memory management. This may cause strange profiling
357 results. We have code in libtcmalloc to cause STL to use
358 tcmalloc for memory management (which in our tests is better
359 than STL's internal management), though it only works for some
360 STL implementations.
361
362 <li> If your program forks, the children will also be profiled
363 (since they inherit the same HEAPPROFILE setting). Each
364 process is profiled separately; to distinguish the child
365 profiles from the parent profile and from each other, all
366 children will have their process-id attached to the HEAPPROFILE
367 name.
368
369 <li> Due to a hack we make to work around a possible gcc bug, your
370 profiles may end up named strangely if the first character of
371 your HEAPPROFILE variable has ascii value greater than 127.
372 This should be exceedingly rare, but if you need to use such a
373 name, just set prepend <code>./</code> to your filename:
374 <code>HEAPPROFILE=./&Auml;gypten</code>.
375</ul>
376
377<hr>
378<address>Sanjay Ghemawat
379<!-- Created: Tue Dec 19 10:43:14 PST 2000 -->
380</address>
381</body>
382</html>