source: README @ 3c9fc94

Revision 3c9fc94, 3.9 KB checked in by Hal Finkel <hfinkel@…>, 6 years ago (diff)

add ld cmds file

  • 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 ld's automatic wrapping functionality is
19employed, and the exact set of necessary flags is large, so a file named
20memlog_s_ld_cmds has been provided containing the necessary flags.
21
22To your linker flags add:
23
24  `cat /path/to/memlog/memlog_s_ld_cmds`
25
26or, if your compiler and wrappers support response files (gcc and clang do, for
27example), simply:
28
29  @/path/to/memlog/memlog_s_ld_cmds
30
31so your overall linking command might look something like this:
32
33  mpic++ -O3 -g -o my_program my_obj1.o my_obj2.o @/path/to/memlog/memlog_s_ld_cmds
34
35** RUNNING **
36
37When your application runs, you should find in your current directory files
38named 'HOST.PID.memlog', one for each process. These contain the raw tracing
39information, and are only somewhat human readable. You can create a ps/pdf
40file detailing the memory allocated when each process reached its peak memory
41use by running:
42
43  /path/to/memlog/memlog_analyze /path/to/HOST.PID.memlog
44
45this will generate files named HOST.PID.memlog.dot, HOST.PID.memlog.ps and
46HOST.PID.memlog.pdf. You'll probably find the pdf file most convenient for
47viewing. HOST.PID.memlog.txt is also generated, providing the same information
48in textual form.
49
50If you pass the --leaks option to memlog_analyze, it will provide data on
51allocations active at the end of the program (leaks) instead of those active
52when the peak memory usage is first reached.
53
54You might have many runs of the same application (or output from many ranks of
55an MPI job), and you'd like to pick the one for analysis with the highest
56memory usage. If you provide a glob pattern to memlog_analyze it will do this
57for you. Make sure you quote the glob pattern so that your shell does not
58expand it.
59
60  /path/to/memlog/memlog_analyze "/path/to/*.memlog"
61
62When running under common batch systems, the files are named
63JOB_ID.HOST.PID.memlog, and when running under the BG/Q CNK, the process's rank
64is used instead of the node-local PID.
65
66Note that te peak memory usage is determined by monitoring the processes's
67maximum resident set size, not just the total allocated heap memory.
68
69memlog_analyze takes, as a second optional parameter, the name of the output
70directory (the current directory is the default). If the directory does not
71exist, it will be created.
72
73memlog_analyze depends on dot (from the graphviz package) and ps2pdf (from the
74ghostscript package), plus various tools from the binutils package.
75
76** RELATED WORK **
77
78Why was memlog created? There are several other tools that can support this use
79case, but none of them would work in our environment properly. They were
80either too slow, not runnable under the BG/Q CNK, not thread safe, did not
81properly support big-endian PPC64, supported only either static or dynamic
82linking, did not collect full backtraces, or just did not produce
83sufficiently-informative peak-usage output.
84
85That having been said, some other tools that might interest you:
86  Valgrind Massif - http://valgrind.org/docs/manual/ms-manual.html
87  Google Performance Tools - http://google-perftools.googlecode.com/svn/trunk/doc/heapprofile.html
88  memtrail - https://github.com/jrfonseca/memtrail
89  LeakTracer - http://www.andreasen.org/LeakTracer/
90  glibc mtrace - http://www.gnu.org/s/hello/manual/libc/Allocation-Debugging.html
91  Heaptrack - http://milianw.de/blog/heaptrack-a-heap-memory-profiler-for-linux
92  MemProf - http://www.secretlabs.de/projects/memprof/
93
94The dot/pdf output produced by memlog was definitely inspired by that produced
95by Google's pprof tool in the aforementioned package.
96
Note: See TracBrowser for help on using the repository browser.