142 lines
4.8 KiB
Groff
142 lines
4.8 KiB
Groff
.TH memleak 8 "2016-01-14" "USER COMMANDS"
|
|
.SH NAME
|
|
memleak \- Print a summary of outstanding allocations and their call stacks to detect memory leaks. Uses Linux eBPF/bcc.
|
|
.SH SYNOPSIS
|
|
.B memleak [-h] [-p PID] [-t] [-a] [-o OLDER] [-c COMMAND] [--combined-only]
|
|
[--wa-missing-free] [-s SAMPLE_RATE] [-T TOP] [-z MIN_SIZE] [-Z MAX_SIZE]
|
|
[-O OBJ] [INTERVAL] [COUNT]
|
|
.SH DESCRIPTION
|
|
memleak traces and matches memory allocation and deallocation requests, and
|
|
collects call stacks for each allocation. memleak can then print a summary
|
|
of which call stacks performed allocations that weren't subsequently freed.
|
|
|
|
When tracing a specific process, memleak instruments a list of allocation
|
|
functions from libc, specifically: malloc, calloc, realloc, posix_memalign,
|
|
valloc, memalign, pvalloc, aligned_alloc, and free.
|
|
When tracing all processes, memleak instruments kmalloc/kfree,
|
|
kmem_cache_alloc/kmem_cache_free, and also page allocations made by
|
|
get_free_pages/free_pages.
|
|
|
|
memleak may introduce significant overhead when tracing processes that allocate
|
|
and free many blocks very quickly. See the OVERHEAD section below.
|
|
|
|
This tool only works on Linux 4.6+. Stack traces are obtained using the new BPF_STACK_TRACE` APIs.
|
|
For kernels older than 4.6, see the version under tools/old.
|
|
Kernel memory allocations are intercepted through tracepoints, which are
|
|
available on Linux 4.7+.
|
|
|
|
.SH REQUIREMENTS
|
|
CONFIG_BPF and bcc.
|
|
.SH OPTIONS
|
|
.TP
|
|
\-h
|
|
Print usage message.
|
|
.TP
|
|
\-p PID
|
|
Trace this process ID only (filtered in-kernel). This traces libc allocator.
|
|
.TP
|
|
\-t
|
|
Print a trace of all allocation and free requests and results.
|
|
.TP
|
|
\-a
|
|
Print a list of allocations that weren't freed (and their sizes) in addition to their call stacks.
|
|
.TP
|
|
\-o OLDER
|
|
Print only allocations older than OLDER milliseconds. Useful to remove false positives.
|
|
The default value is 500 milliseconds.
|
|
.TP
|
|
\-c COMMAND
|
|
Run the specified command and trace its allocations only. This traces libc allocator.
|
|
.TP
|
|
\-\-combined-only
|
|
Use statistics precalculated in kernel space. Amount of data to be pulled from
|
|
kernel significantly decreases, at the cost of losing capabilities of time-based
|
|
false positives filtering (\-o).
|
|
.TP
|
|
\-\-wa-missing-free
|
|
Make up the action of free to alleviate misjudgments when free is missing.
|
|
.TP
|
|
\-s SAMPLE_RATE
|
|
Record roughly every SAMPLE_RATE-th allocation to reduce overhead.
|
|
.TP
|
|
\-t TOP
|
|
Print only the top TOP stacks (sorted by size).
|
|
The default value is 10.
|
|
.TP
|
|
\-z MIN_SIZE
|
|
Capture only allocations that are larger than or equal to MIN_SIZE bytes.
|
|
.TP
|
|
\-Z MAX_SIZE
|
|
Capture only allocations that are smaller than or equal to MAX_SIZE bytes.
|
|
.TP
|
|
\-O OBJ
|
|
Attach to allocation functions in specified object instead of resolving libc. Ignored when kernel allocations are profiled.
|
|
.TP
|
|
INTERVAL
|
|
Print a summary of outstanding allocations and their call stacks every INTERVAL seconds.
|
|
The default interval is 5 seconds.
|
|
.TP
|
|
COUNT
|
|
Print the outstanding allocations summary COUNT times and then exit.
|
|
.SH EXAMPLES
|
|
.TP
|
|
Print outstanding kernel allocation stacks every 3 seconds:
|
|
#
|
|
.B memleak 3
|
|
.TP
|
|
Print user outstanding allocation stacks and allocation details for the process 1005:
|
|
#
|
|
.B memleak -p 1005 -a
|
|
.TP
|
|
Sample roughly every 5th allocation (~20%) of the call stacks and print the top 5
|
|
stacks 10 times before quitting.
|
|
#
|
|
.B memleak -s 5 --top=5 10
|
|
.TP
|
|
Run ./allocs and print outstanding allocation stacks for that process:
|
|
#
|
|
.B memleak -c "./allocs"
|
|
.TP
|
|
Capture only allocations between 16 and 32 bytes in size:
|
|
#
|
|
.B memleak -z 16 -Z 32
|
|
.SH OVERHEAD
|
|
memleak can have significant overhead if the target process or kernel performs
|
|
allocations at a very high rate. Pathological cases may exhibit up to 100x
|
|
degradation in running time. Most of the time, however, memleak shouldn't cause
|
|
a significant slowdown. You can use the \-s switch to reduce the overhead
|
|
further by capturing only every N-th allocation. The \-z and \-Z switches can
|
|
also reduce overhead by capturing only allocations of specific sizes.
|
|
|
|
Additionally, option \-\-combined-only saves processing time by reusing already
|
|
calculated allocation statistics from kernel. It's faster, but lacks information
|
|
about particular allocations.
|
|
|
|
Also, option \-\-wa-missing-free makes memleak more accuracy in the complicated
|
|
environment.
|
|
|
|
To determine the rate at which your application is calling malloc/free, or the
|
|
rate at which your kernel is calling kmalloc/kfree, place a probe with perf and
|
|
collect statistics. For example, to determine how many calls to __kmalloc are
|
|
placed in a typical period of 10 seconds:
|
|
|
|
#
|
|
.B perf probe '__kmalloc'
|
|
|
|
#
|
|
.B perf stat -a -e 'probe:__kmalloc' -- sleep 10
|
|
|
|
.SH SOURCE
|
|
This is from bcc.
|
|
.IP
|
|
https://github.com/iovisor/bcc
|
|
.PP
|
|
Also look in the bcc distribution for a companion _examples.txt file containing
|
|
example usage, output, and commentary for this tool.
|
|
.SH OS
|
|
Linux
|
|
.SH STABILITY
|
|
Unstable - in development.
|
|
.SH AUTHOR
|
|
Sasha Goldshtein
|