jeprof(1) · carta

NAME

jeprof - analyze and print jemalloc's heap profile dumps

SYNOPSIS

jeprof [options] <program> <profiles>

jeprof [options] <symbolized-profiles>

jeprof [options] <profile>

jeprof --symbols program

DESCRIPTION

jeprof can be used to parse, analyze and generate user-readable output from jemalloc's memory profile dumps. Refer to jemalloc(3) or the jemalloc website <http://jemalloc.net/> about jemalloc and the opt.prof option.

jeprof is based on pprof(1) that is developed as part of the <https://github.com/gperftools/gperftools> gperftools package.

Common usage:

jeprof [options] <program> <profiles>: Interactive mode. <profiles> is a space separated list of profile names.

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).

jeprof [options] <profile>

<profile> is a remote form. Each name can be:

/path/to/profile: a path to a profile file

host:port[/<service]>: a location of a service to get the profile from.

/<service> can be /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

If /<service> is omitted, the service defaults to /pprof/profile (CPU profiling).

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.

OPTIONS AND ARGUMENTS

Options

--cum: Sort by cumulative data.

--base=base: Subtract <base> from <profile> before display.

--interactive: Run in interactive mode. (interactive "help" gives help) [default]

--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

--addresses: Report at address level.

--lines: Report at source line level.

--functions: Report at function level. [default]

--files: Report at source file level.

Output type

--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).

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.

--drop_negative: Ignore negative differences.

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.

--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.

--test: Run unit tests.

--help: This message.

--version: Version information.

ENVIRONMENT

The following environment variables affect the execution of jeprof:

JEPROF_TMPDIR: Profiles directory. Defaults to $HOME/jeprof.

JEPROF_TOOLS: Prefix for object tools pathnames.

EXAMPLES

jeprof /bin/ls ls.prof: Enters interactive mode.

jeprof --text /bin/ls ls.prof: Generates one line per procedure.

jeprof --web /bin/ls ls.prof: Displays annotated call-graph in web browser.

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.

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.