diff options
Diffstat (limited to 'docs/heapprofd.md')
| -rw-r--r-- | docs/heapprofd.md | 129 |
1 files changed, 21 insertions, 108 deletions
diff --git a/docs/heapprofd.md b/docs/heapprofd.md index 469ebacdd..a34334bf3 100644 --- a/docs/heapprofd.md +++ b/docs/heapprofd.md @@ -1,12 +1,14 @@ # heapprofd - Android Heap Profiler -**heapprofd requires Android 10.** +Googlers, for design doc see: http://go/heapprofd-design + +**heapprofd requires Android Q.** heapprofd is a tool that tracks native heap allocations & deallocations of an Android process within a given time period. The resulting profile can be used to attribute memory usage to particular function callstacks, supporting a mix -of both native and java code. The tool can be used by Android platform and app -developers to investigate memory issues. +of both native and java code. The tool should be useful to Android platform +developers, and app developers investigating memory issues. On debug Android builds, you can profile all apps and most system services. On "user" builds, you can only use it on apps with the debuggable or @@ -16,9 +18,8 @@ profileable manifest flag. <!-- This uses github because gitiles does not allow to get the raw file. --> -On Linux / MacOS, use the `tools/heap_profile` script to heap profile a -process. If you are having trouble make sure you are using the -[latest version]( +Use the `tools/heap_profile` script to heap profile a process. If you are +having trouble make sure you are using the [latest version]( https://raw.githubusercontent.com/catapult-project/perfetto/master/tools/heap_profile). See all the arguments using `tools/heap_profile -h`, or use the defaults @@ -37,29 +38,22 @@ This will create a pprof-compatible heap dump when Ctrl+C is pressed. The resulting profile proto contains four views on the data -* **space**: how many bytes were allocated but not freed at this callstack the +* space: how many bytes were allocated but not freed at this callstack the moment the dump was created. -* **alloc\_space**: how many bytes were allocated (including ones freed at the +* alloc\_space: how many bytes were allocated (including ones freed at the moment of the dump) at this callstack -* **idle\_space**: if [idle page tracking](#idle-page-tracking) is being used, - the number of bytes that were allocated at this callstack and are on pages - that have not been touched since the last dump. -* **objects**: how many allocations without matching frees were done at this +* objects: how many allocations without matching frees were done at this callstack. -* **alloc\_objects**: how many allocations (including ones with matching frees) - were done at this callstack. +* alloc\_objects: how many allocations (including ones with matching frees) were + done at this callstack. **Googlers:** Head to http://pprof/ and upload the gzipped protos to get a visualization. *Tip: you might want to put `libart.so` as a "Hide regex" when profiling apps.* -You can use the [Perfetto UI](https://ui.perfetto.dev) to visualize heap dumps. -Upload the `raw-trace` file in your output directory. You will see all heap -dumps as diamonds on the timeline, click any of them to get a flamegraph. - -Alternatively [Speedscope](https://speedscope.app) can be used to visualize -the gzipped protos, but will only show the space view. -*Tip: Click Left Heavy on the top left for a good visualisation.* +[Speedscope](https://speedscope.app) can also be used to visualize the heap +dump, but will only show the space view. *Tip: Click Left Heavy on the top +left for a good visualisation.* ## Sampling interval heapprofd samples heap allocations. Given a sampling interval of n bytes, @@ -128,16 +122,13 @@ Depending on the build of Android that heapprofd is run on, some processes are not be eligible to be profiled. On user builds, only Java applications with either the profileable or the -debuggable manifest flag set can be profiled. Profiling requests for other +debugable manifest flag set can be profiled. Profiling requests for other processes will result in an empty profile. On userdebug builds, all processes except for a small blacklist of critical -services can be profiled (to find the blacklist, look for -`never_profile_heap` in [heapprofd.te]( -https://android.googlesource.com/platform/system/sepolicy/+/refs/heads/master/private/heapprofd.te)). -This restriction can be lifted by disabling SELinux by running -`adb shell su root setenforce 0` or by passing `--disable-selinux` to the -`heap_profile` script. +services can be profiled. This restriction can be lifted by disabling +SELinux by running `adb shell su root setenforce 0` or by passing +`--disable-selinux` to the `heap_profile` script. | | userdebug setenforce 0 | userdebug | user | |-------------------------|------------------------|-----------|------| @@ -145,72 +136,7 @@ This restriction can be lifted by disabling SELinux by running | native service | y | y | n | | app | y | y | n | | profileable app | y | y | y | -| debuggable app | y | y | y | - -## DEDUPED frames -If the name of a Java method includes `[DEDUPED]`, this means that multiple -methods share the same code. ART only stores the name of a single one in its -metadata, which is displayed here. This is not necessarily the one that was -called. - -## Manual dumping -You can trigger a manual dump of all currently profiled processes by running -`adb killall -USR1 heapprofd`. This can be useful for seeing the current memory -usage of the target in a specific state. - -This dump will show up in addition to the dump at the end of the profile that is -always produced. You can create multiple of these dumps, and they will be -enumerated in the output directory. - -## Symbolization -If the profiled binary or libraries do not have debug symbols, you can use -pprof to symbolize offline. - -To do so, copy symbolized versions of your binary and/or libraries into a -directory. Then run -`PPROF_BINARY_PATH=thatdirectory pprof heap_profile.${n}.${pid}.gz`, and pprof -will read symbol information from these files. - -You can save the symbolized version by issuing the `proto` command in pprof. - -## Idle page tracking -This is only available in Android versions newer than 10. - -Idle page tracking allows you to analyze which allocations made by your -program are being used by a workload. This can be useful for finding leaks -as well as unused cached values. - -**Do not follow these instructions on devices containing valuable data.** -They require you turn off SELinux on your device, significantly lowering -your device's security level. - -Use the following command to profile the next startup of your program with idle -tracking enabled. - -1. `$ adb root` -2. `$ tools/heap_profile -n ${NAME} --no-running --disable-selinux ---idle-allocations` - -Then run the following commands in a separate shell. - -1. `$ adb shell killall ${ROOT}` to restart your program. -2. Wait for your program to finish starting. -3. `adb shell killall -USR1 heapprofd` to trigger the first dump (see -[Manual Dumping](#manual-dumping) above). This will mark all allocations as -idle. -4. Interact with your program. - -Once you are done interacting, `Ctrl-C` the invokation of -`tools/heap_profile`, and upload the `heap_dump.2.*.pb.gz` file to pprof. -You can then see the memory that was idle in the `idle_space` tab. - -This will show allocations that are on pages that have not been touched since -the last dump. Small allocations that are not touched might not show up, as -they might share a page with an allocation that was. - -If heapprofd is operating in sampling mode (i.e. `--interval` is larger than 1), -the values in `idle_space` will not correct for the sampling, so they are not -comparable to values in `space` and `alloc_space`, which do. +| debugable app | y | y | y | ## Troubleshooting @@ -226,22 +152,9 @@ accuracy in the resulting profile) by passing `--interval` to heap\_profile. Check whether your target process is eligible to be profiled by consulting [Target processes](#target-processes) above. -Also check the [Known Issues](#known-issues). - - -### Impossible callstacks -If you see a callstack that seems to impossible from looking at the code, make -sure no [DEDUPED frames](#deduped-frames) are involved. - ## Known Issues -### Android 10 * Does not work on x86 platforms (including the Android cuttlefish emulator). -* If heapprofd is run standalone (by running `heapprofd` in a root shell, rather - than through init), `/dev/socket/heapprofd` get assigned an incorrect SELinux - domain. You will not be able to profile any processes unless you disable - SELinux enforcement. - Run `restorecon /dev/socket/heapprofd` in a root shell to resolve. ## Ways to count memory @@ -252,7 +165,7 @@ operating system. **heapprofd** gives you the number of bytes the target program requested from the allocator. If you are profiling a Java app from startup, allocations that happen early in the application's initialization will not be -visible to heapprofd. Native services that do not fork from the Zygote +visibile to heapprofd. Native services that do not fork from the Zygote are not affected by this. **malloc\_info** is a libc function that gives you information about the |