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.