docs/reference/heap_profile-cli.md - third_party/perfetto - Git at Google


            
            # 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](/docs/data-sources/native-heap-profiler.md) 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.


            `-p`, `--pid` _PIDS_

            
            :    Comma-separated list of PIDs to profile.


            `-i`, `--interval`

            
            :    Sampling interval. Default 4096 (4KiB).


            `-o`, `--output` _DIRECTORY_

            
            :    Output directory. Must already exist and be empty.


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


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


            ```bash

            
            tools/heap_profile android -n system_server

            
            ```


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


            ```bash

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

            
            ```


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


            ```bash

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

            
            ```


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


            ```bash

            
            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](/docs/learning-more/symbolization.md).
	# 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](/docs/data-sources/native-heap-profiler.md) 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.

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

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

	`-o`, `--output` _DIRECTORY_
	: Output directory. Must already exist and be empty.

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

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

	```bash
	tools/heap_profile android -n system_server
	```

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

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

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

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

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

	```bash
	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](/docs/learning-more/symbolization.md).