JEPROF(1)

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.

SEE ALSO
jemalloc(3)