source: README @ 0109b01

Revision 0109b01, 3.0 KB checked in by Hal Finkel <hfinkel@…>, 7 years ago (diff)

note --leaks in the README

  • Property mode set to 100644
Line 
1memlog - A Memory-Allocation Logging Tool
2
3This tool attempts to help you answer the question:
4  Why is my application using so much memory?
5
6** LINKING **
7
8How to use it depends on how your application is linked:
9
10For dynamically-linked applications, you can:
11
12 1. Use LD_PRELOAD: Set LD_PRELOAD=/path/to/memlog/libmemlog.so when you run
13    your application.
14
15 2. Link directly: Add the following to your linker flags:
16      -L/path/to/memlog -Wl,-rpath,/path/to/memlog -lmemlog
17
18For statically-linked applications, add the following to your linker flags:
19
20  -Wl,--wrap,malloc,--wrap,free,--wrap,realloc,--wrap,calloc,--wrap,memalign \
21    /path/to/memlog/memlog_s.o -lpthread -ldl
22
23** RUNNING **
24
25When your application runs, you should find in your current directory files
26named 'HOST.PID.memlog', one for each process. These contain the raw tracing
27information, and are only somewhat human readable. You can create a ps/pdf
28file detailing the memory allocated when each process reached its peak memory
29use by running:
30
31  /path/to/memlog/memlog_analyze /path/to/HOST.PID.memlog
32
33this will generate files named HOST.PID.memlog.dot, HOST.PID.memlog.ps and
34HOST.PID.memlog.pdf. You'll probably find the pdf file most convenient for
35viewing. HOST.PID.memlog.txt is also generated, providing the same information
36in textual form.
37
38If you pass the --leaks option to memlog_analyze, it will provide data on
39allocations active at the end of the program (leaks) instead of those active
40when the peak memory usage is first reached.
41
42When running under common batch systems, the files are named
43JOB_ID.HOST.PID.memlog, and when running under the BG/Q CNK, the process's rank
44is used instead of the node-local PID.
45
46Note that te peak memory usage is determined by monitoring the processes's
47maximum resident set size, not just the total allocated heap memory.
48
49memlog_analyze depends on dot (from the graphviz package) and ps2pdf (from the
50ghostscript package), plus various tools from the binutils package.
51
52** RELATED WORK **
53
54Why was memlog created? There are several other tools that can support this use
55case, but none of them would work in our environment properly. They were
56either too slow, not runnable under the BG/Q CNK, not thread safe, did not
57properly support big-endian PPC64, supported only either static or dynamic
58linking, did not collect full backtraces, or just did not produce
59sufficiently-informative peak-usage output.
60
61That having been said, some other tools that might interest you:
62  Valgrind Massif - http://valgrind.org/docs/manual/ms-manual.html
63  Google Performance Tools - http://google-perftools.googlecode.com/svn/trunk/doc/heapprofile.html
64  memtrail - https://github.com/jrfonseca/memtrail
65  LeakTracer - http://www.andreasen.org/LeakTracer/
66  glibc mtrace - http://www.gnu.org/s/hello/manual/libc/Allocation-Debugging.html
67  Heaptrack - http://milianw.de/blog/heaptrack-a-heap-memory-profiler-for-linux
68  MemProf - http://www.secretlabs.de/projects/memprof/
69
70The dot/pdf output produced by memlog was definitely inspired by that produced
71by Google's pprof tool in the aforementioned package.
72
Note: See TracBrowser for help on using the repository browser.