heap_profile - record a native heap profile on Android or local Linux
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...]
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.
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.
--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.
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
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.host subcommand only runs on Linux; it errors out on other platforms.