memleak(8)

💖 memleak(8) — the leak detective 💖

hey bestie, so you wanna learn about memleak(8)? okay so this is literally the manual page for a tool that goes by memleak. it's a Linux thing, it hangs out in the System Manager's Manual, and it's here to help you catch memory leaks. no cap.

---

✨ NAME ✨

memleak — print a summary of outstanding allocations and their call stacks to detect memory leaks. uses Linux eBPF/bcc, periodt.

---

🌸 SYNOPSIS 🌸

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]

---

🦋 DESCRIPTION 🦋

okay so here's the vibe: memleak traces and matches memory allocation and deallocation requests, and it collects call stacks for each allocation. then it can print a summary of which call stacks performed allocations that weren't subsequently freed. it's giving detective energy 🔍.

when it's 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, it instruments kmalloc/kfree, kmem_cache_alloc/kmem_cache_free, and also page allocations made by get_free_pages/free_pages.

bestie, memleak may introduce significant overhead when tracing processes that allocate and free many blocks very quickly. see the OVERHEAD section below, iykyk.

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+. so like, check your kernel version first, fr fr.

---

🎀 REQUIREMENTS 🎀

CONFIG_BPF and bcc. that's it, that's the list 💅.

---

👑 OPTIONS 👑

• -h — print usage message. the classic cry for help.
• -p PID — trace this process ID only (filtered in-kernel). this traces libc allocator. very main character of you to target one process.
• -t — print a trace of all allocation and free requests and results. it's giving receipts.
• -a — print a list of allocations that weren't freed (and their sizes) in addition to their call stacks. the tea is piping hot ☕.
• -o OLDER — print only allocations older than OLDER milliseconds. useful to remove false positives. the default value is 500 milliseconds. no cap, that's the default.
• -c COMMAND — run the specified command and trace its allocations only. this traces libc allocator. like, you're the director and the command is your actor.
• --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). so it's faster but you lose the filter, bestie.
• --wa-missing-free — make up the action of free to alleviate misjudgments when free is missing. it's literally improvising, but for memory.
• -s SAMPLE_RATE — record roughly every SAMPLE_RATE-th allocation to reduce overhead. sampling is slay.
• -t TOP — print only the top TOP stacks (sorted by size). the default value is 10. yes, -t does double duty, don't @ me.
• -z MIN_SIZE — capture only allocations that are larger than or equal to MIN_SIZE bytes. size queen behavior.
• -Z MAX_SIZE — capture only allocations that are smaller than or equal to MAX_SIZE bytes. keeping it cute and small.
• -O OBJ — attach to allocation functions in specified object instead of resolving libc. ignored when kernel allocations are profiled. so like, it's only for userland, periodt.
• INTERVAL — print a summary of outstanding allocations and their call stacks every INTERVAL seconds. the default interval is 5 seconds. tick tock ⏰.
• COUNT — print the outstanding allocations summary COUNT times and then exit. boundaries, bestie.

---

💜 EXAMPLES 💜

okay, example time 👑

print outstanding kernel allocation stacks every 3 seconds:

# memleak 3

print user outstanding allocation stacks and allocation details for the process 1005:

# memleak -p 1005 -a

sample roughly every 5th allocation (~20%) of the call stacks and print the top 5 stacks 10 times before quitting:

# memleak -s 5 --top=5 10

run ./allocs and print outstanding allocation stacks for that process:

# memleak -c ./allocs

capture only allocations between 16 and 32 bytes in size:

# memleak -z 16 -Z 32

---

🔥 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. so like, use the switches, bestie, your CPU will thank you.

additionally, option --combined-only saves processing time by reusing already calculated allocation statistics from kernel. it's faster, but lacks information about particular allocations. so it's a trade-off, ngl.

also, option --wa-missing-free makes memleak more accuracy in the complicated environment. yes, it literally says "more accuracy" in the original, and i'm not fixing it, i'm just delivering the facts 💅.

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:

# perf probe '__kmalloc'

# perf stat -a -e 'probe:__kmalloc' -- sleep 10

---

⭐ SOURCE ⭐

this is from bcc.

https://github.com/iovisor/bcc

also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool. it's the bonus content, the director's commentary, if you will.

---

🌈 OS 🌈

Linux. obviously, bestie.

---

🧚 STABILITY 🧚

Unstable - in development. it's giving "work in progress, handle with care". don't say i didn't warn you.

---

💀 AUTHOR 💀

Sasha Goldshtein. the icon, the legend. 👑

---

alright bestie, that's the whole manual. stay leak-free out there. 🫶

---

so like, this page is from the System Manager's Manual, it's tagged as USER COMMANDS, and the date on it is 2016-01-14. just so you have the receipts. 💖