JEPROF(1)

✨ JEPROF(1) ✨

okay so bestie, welcome to jeprof — the User Manual edition, no cap. she analyzes and prints jemalloc's heap profile dumps and she is literally iconic 💅

---

🎀 NAME 🎀

jeprof — analyze and print jemalloc's heap profile dumps. that's it, that's the vibe. 🫶

---

🌸 SYNOPSIS 🌸

jeprof [options] <program> <profiles>
jeprof [options] <symbolized-profiles>
jeprof [options] <profile>
jeprof --symbols program

four whole entry points, she contains multitudes 💖

---

🦋 DESCRIPTION 🦋

okay so jeprof can parse, analyze, and generate user-readable output from jemalloc's memory profile dumps. if you wanna know about jemalloc and the opt.prof option, go read jemalloc(3) or hit up the jemalloc website at http://jemalloc.net/ — iykyk.

ngl, jeprof is based on pprof(1), which is developed as part of the gperftools package at https://github.com/gperftools/gperftools. so if she seems familiar, that's why, she's giving gperftools energy 💜

common usage (the ones you'll actually be living in) 🍓

• jeprof [options] <program> <profiles> — interactive mode, bestie. <profiles> is a space separated list of profile names. that's it, that's the whole thing.
• jeprof [options] <symbolized-profiles> — <symbolized-profiles> is a list of profile files where each file contains the necessary symbol mappings as well as profile data (likely generated with --raw). two for one, we love to see it.
• jeprof [options] <profile> — <profile> is a remote form. and each name can be:
  • /path/to/profile — a path to a profile file. simple. clean. ✨
  • host:port[/<service]> — a location of a service to get the profile from. remote fetch era 💅

<service> can be one of these little guys: /pprof/heap, /pprof/profile, /pprof/pmuprofile, /pprof/growth, /pprof/contention, /pprof/wall, /pprof/censusprofile, or /pprof/filteredprofile.

for instance:

jeprof http://myserver.example.com:80/pprof/heap

and heads up: if you omit /<service>, the service defaults to /pprof/profile (CPU profiling). so it just decides for you. periodt.

• jeprof --symbols program — maps addresses to symbol names. in this mode, stdin should be a list of library mappings, in the same format as is found in the heap- and CPU-profile files (this loosely matches that of /proc/self/maps on Linux), followed by a list of hex addresses to map, one per line. yes, both things, in that order, from stdin. she's particular and honestly? respect. 👑

---

💖 OPTIONS AND ARGUMENTS 💖

Options

• --cum — sort by cumulative data. king behavior honestly.
• --base=base — subtract base from profile before display. math is happening.
• --interactive — run in interactive mode. (interactive help gives help) [default] — this is the default one btw, so if you don't pick anything you get the hangout mode 🫶
• --seconds=n — length of time for dynamic profiles. [default=30 secs]
• --add_lib=file — read additional symbols and line info from the given library.
• --lib_prefix=dir — comma separated list of library path prefixes.

Reporting granularity

how zoomed-in do you want it, bestie 🔍

• --addresses — report at address level. maximum zoom.
• --lines — report at source line level.
• --functions — report at function level. [default]
• --files — report at source file level.

Output type

pick your format, she does all of them, she's flexible like that 🌈

• --text — generate text report.
• --callgrind — generate callgrind format to stdout.
• --gv — generate Postscript and display.
• --evince — generate PDF and display.
• --web — generate SVG and display.
• --list=regexp — generate source listing of matching routines.
• --disasm=regexp — generate disassembly of matching routines.
• --symbols — print demangled symbol names found at given addresses.
• --dot — generate DOT file to stdout.
• --ps — generate PostScript to stdout.
• --pdf — generate PDF to stdout.
• --svg — generate SVG to stdout.
• --gif — generate GIF to stdout.
• --raw — generate symbolized jeprof data (useful with remote fetch). yes bestie, remote fetch, we love a combo move.

Heap-profile options

• --inuse_space — display in-use (mega)bytes. [default]
• --inuse_objects — display in-use objects.
• --alloc_space — display allocated (mega)bytes.
• --alloc_objects — display allocated objects.
• --show_bytes — display space in bytes. the tiny unit, for the precise girlies.
• --drop_negative — ignore negative differences. not today, negativity 🙈

Contention-profile options

• --total_delay — display total delay at each region. [default]
• --contentions — display number of delays at each region.
• --mean_delay — display mean delay at each region.

Call-graph options

• --nodecount=n — show at most so many nodes. [default=80]
• --nodefraction=f — hide nodes below f*total. [default=.005]
• --edgefraction=f — hide edges below f*total. [default=.001]
• --maxdegree=n — max incoming/outgoing edges per node. [default=8]
• --focus=regexp — focus on backtraces with nodes matching regexp.
• --thread=n — show profile for thread n.
• --ignore=regexp — ignore backtraces with nodes matching regexp.
• --scale=n — set GV scaling. [default=0]
• --heapcheck — make nodes with non-0 object counts (i.e. direct leak generators) more visible. giving those nodes main character energy fr fr 👑
• --retain=regexp — retain only nodes that match regexp.
• --exclude=regexp — exclude all nodes that match regexp.

Miscellaneous

• --tools=prefix or --tools=binary:fullpath[,...] — path for object tool pathnames. two ways to say it, both valid 💅
• --test — run unit tests.
• --help — this message.
• --version — version information.

---

🌈 ENVIRONMENT 🌈

the following environment variables affect the execution of jeprof, so set them if you want, they're listening:

• JEPROF_TMPDIR — profiles directory. defaults to $HOME/jeprof. that's where your stuff lives 🏠
• JEPROF_TOOLS — prefix for object tools pathnames.

---

⭐ EXAMPLES ⭐

okay here's where it gets fun, let me show you the moves:

jeprof /bin/ls ls.prof

enters interactive mode. cozy hangout time 💖

jeprof --text /bin/ls ls.prof

generates one line per procedure.

jeprof --web /bin/ls ls.prof

displays annotated call-graph in web browser. fancy ✨

jeprof --gv /bin/ls ls.prof

generates annotated call-graph and displays via gv.

jeprof --gv --focus=Mutex /bin/ls ls.prof

restrict to code paths that involve an entry that matches Mutex.

jeprof --gv --focus=Mutex --ignore=string /bin/ls ls.prof

restrict to code paths that involve an entry that matches Mutex and does not match string. both filters, at once, she can multitask 💅

jeprof --list=getdir /bin/ls ls.prof

generates disassembly listing of all routines with at least one sample that match getdir(). the listing is annotated with the flat and cumulative sample counts at each line.

jeprof --disasm=getdir /bin/ls ls.prof

generates disassembly listing of all routines with at least one sample that match getdir(). the listing is annotated with the flat and cumulative sample counts at each PC value.

jeprof http://localhost:1234/

enters interactive mode.

jeprof --text localhost:1234

outputs one line per procedure for localhost:1234.

jeprof --raw localhost:1234 > ./local.raw; jeprof --text ./local.raw

fetches a remote profile for later analysis and then analyzes it in text mode. grab now, analyze later, that's the strategy 🍓

---

👑 SEE ALSO 👑

• jemalloc(3)

like obviously, the whole family, go say hi.

---

okay bestie that's the whole page, you ate it 💅✨ this was jemalloc 5.1.0_0, dated 2019-01-12, and it's been a pleasure fr fr 🫶🎀 no cap, go profile something.