HEAP_PROFILE(1)

NAME

heap_profile - record a native heap profile on Android or local Linux

DESCRIPTION

tools/heap_profile collects native memory profiles. It exposes two subcommands:

heap_profile android - profile a process on a connected Android device via adb (the previous behavior, still the default if no subcommand is given).
heap_profile host - profile a local Linux process via LD_PRELOAD. The script auto-downloads tracebox and libheapprofd_glibc_preload.so and manages a local traced daemon for the duration of the session.

See Recording traces for more details about the data source.

usage: heap_profile [-h] [common options] {android,host} ...

positional arguments:
  {android,host}
    android   Profile a process on a connected Android device via adb
              (default).
    host      Profile a local Linux process via LD_PRELOAD.

usage: heap_profile android [-h] [-i INTERVAL] [-d DURATION] [--no-start]
                            [-p PIDS] [-n NAMES] [-c CONTINUOUS_DUMP]
                            [--heaps HEAPS] [--all-heaps]
                            [--no-android-tree-symbolization]
                            [--disable-selinux] [--no-versions] [--no-running]
                            [--no-startup] [--shmem-size SHMEM_SIZE]
                            [--block-client]
                            [--block-client-timeout BLOCK_CLIENT_TIMEOUT]
                            [--no-block-client] [--idle-allocations]
                            [--dump-at-max] [--disable-fork-teardown]
                            [--simpleperf]
                            [--traceconv-binary TRACECONV_BINARY]
                            [--no-annotations] [--print-config] [-o DIRECTORY]

usage: heap_profile host [-h] [-i INTERVAL] [-d DURATION] [--no-start]
                         [-n NAMES] [-c CONTINUOUS_DUMP]
                         [--heaps HEAPS] [--all-heaps]
                         [--shmem-size SHMEM_SIZE] [--block-client]
                         [--block-client-timeout BLOCK_CLIENT_TIMEOUT]
                         [--no-block-client] [--idle-allocations]
                         [--dump-at-max] [--disable-fork-teardown]
                         [--traceconv-binary TRACECONV_BINARY]
                         [--no-annotations] [--print-config] [-o DIRECTORY]
                         [--preload-library PRELOAD_LIBRARY]
                         [--tracebox-binary TRACEBOX_BINARY]
                         -- COMMAND [ARGS...]

COMMON OPTIONS

These flags apply to both android and host subcommands.

-n, --name NAMES: Comma-separated list of process names to profile. On host, if omitted, the basename of the command after -- is used.

-i, --interval: Sampling interval. Default 4096 (4KiB).

-o, --output DIRECTORY: Output directory. Must be empty if it already exists.

--all-heaps: Collect allocations from all heaps registered by target.

--heaps HEAPS: Comma-separated list of heaps to collect, e.g.: libc.malloc,com.android.art. Requires Android 12.

--block-client: When buffer is full, block the client to wait for buffer space. Use with caution as this can significantly slow down the client. This is the default.

--block-client-timeout: If --block-client is given, do not block any allocation for longer than this timeout (us).

--no-block-client: When buffer is full, stop the profile early.

-c, --continuous-dump: Dump interval in ms. 0 to disable continuous dump.

-d, --duration: Duration of profile (ms). 0 to run until interrupted. Default: until interrupted by user.

--disable-fork-teardown: Do not tear down client in forks. This can be useful for programs that use vfork. Android 11+ only.

--dump-at-max: Dump the maximum memory usage rather than at the time of the dump.

--idle-allocations: Keep track of how many bytes were unused since the last dump, per callstack.

--no-annotations: Do not suffix the pprof function names with Android ART mode annotations such as [jit].

--no-running: Do not target already running processes. Requires Android 11.

--no-start: No-op, kept for backwards compatibility.

--no-startup: Do not target processes that start during the profile. Requires Android 11.

--print-config: Print config instead of running. For debugging.

--shmem-size: Size of buffer between client and heapprofd. Default 8MiB. Needs to be a power of two multiple of 4096, at least 8192.

--traceconv-binary: Path to local traceconv. For debugging.

-h, --help: Show help message and exit.

ANDROID-ONLY OPTIONS

These flags are gated on args.subcommand == 'android' in the script and have no effect when passed to host.

-p, --pid PIDS: Comma-separated list of PIDs to profile.

--disable-selinux: Disable SELinux enforcement for duration of profile.

--no-android-tree-symbolization: Do not symbolize using currently lunched target in the Android tree.

--no-versions: Do not get version information about APKs.

--simpleperf: Get simpleperf profile of heapprofd. This is only for heapprofd development.

HOST-ONLY OPTIONS

--preload-library PRELOAD_LIBRARY: Path to libheapprofd_glibc_preload.so. If omitted the prebuilt is downloaded automatically (linux-amd64/arm/arm64).

--tracebox-binary TRACEBOX_BINARY: Path to a local tracebox binary. For debugging.

-- COMMAND [ARGS...]: Required positional. The command to launch under LD_PRELOAD. The binary is run with PERFETTO_HEAPPROFD_BLOCKING_INIT=1 so the first allocation blocks until heapprofd attaches.

EXAMPLES

Profile system_server on a connected Android device until interrupted:

tools/heap_profile android -n system_server

Profile a local Linux binary, capturing every allocation from startup:

tools/heap_profile host -- ./my_binary --some-flag

Periodic 5-second snapshots of com.example.app:

tools/heap_profile android -n com.example.app -c 5000

Print the trace config a given invocation would emit, without running it:

tools/heap_profile android -n system_server --print-config

NOTES

The bare invocation heap_profile -n NAME (without a subcommand) is preserved for backwards compatibility and is equivalent to heap_profile android -n NAME. New scripts should use the explicit form.
The host subcommand only runs on Linux; it errors out on other platforms.
For symbolization and Java/Kotlin deobfuscation of the resulting trace, see Symbolization and deobfuscation.