1# heapprofd - Android Heap Profiler
2
3heapprofd allows you to attribute memory usage to functions for Android services
4and apps.
5
6For documentation, see https://perfetto.dev/docs/data-sources/native-heap-profiler.
7
8For design doc, see https://perfetto.dev/docs/design-docs/heapprofd-design.
9
10## GN Targets
11### Factories
12android: connects to the system heapprofd. The client API will need to have
13         been built at *exactly* the same version. This means this can only
14         be used by the API shipped in the platform.
15
16standalone: executes an in-process heapprofd. Can be used on old platform
17            versions.
18
19noop: ignores all calls to the client API. This can be used as a stand-in when
20      compiling, or when executing without profiling.
21
22### Interceptors
23bionic: uses bionic [malloc dispatch](
24https://cs.android.com/android/platform/superproject/+/master:bionic/libc/private/bionic_malloc_dispatch.h)
25to intercept allocation functions on Android. This works by placing a library
26on a pre-defined path, which gets [loaded by Bionic](
27https://cs.android.com/android/platform/superproject/+/master:bionic/libc/bionic/malloc_heapprofd.cpp).
28
29glibc: generates a library exposing the allocation functions. This library
30       should be used for `LD_PRELOAD` and uses the glibc specific symbols
31       like `__libc_malloc` to use the system allocator.
32
33### Shared libraries
34
35| GN target                   | factory    | interceptor | distribution |
36|-----------------------------|------------|-------------|--------------|
37| heapprofd_client            | android    | bionic      | platform     |
38| heapprofd_client_api        | android    | none        | platform     |
39| heapprofd_glibc_preload     | standalone | glibc       | unbundled    |
40| heapprofd_standalone_client | standalone | none        | unbundled    |
41| heapprofd_api_noop          | noop       | none        | unbundled    |
42
43
44## Heap profile heapprofd
45
46For development, you might want to get a heap profile of heapprofd while it
47is profiling something else. For that reason, we allow two heapprofds to run
48on the system. The secondary heapprofd can then profile your primary one.
49
50To do this, first make sure that heapprofd is running by setting the property
51
52```
53adb shell su root setprop persist.heapprofd.enable 1
54```
55
56Take note of its PID.
57
58```
59adb shell ps -e | grep heapprofd
60```
61
62Then, move away the primary heapprofd socket to make space for the secondary
63one
64
65```
66adb shell su root mv /dev/socket/heapprofd /dev/socket/heapprofd_primary
67```
68
69Start the secondary heapprofd
70
71```
72adb shell su root start heapprofd_secondary
73```
74
75Now we can start the profile of the primary heapprofd (using the secondary).
76Leave this session running.
77
78```
79tools/heap_profile -p ${PID_FROM_ABOVE}
80```
81
82Now move back the original socket
83
84```
85adb shell su root unlink /dev/socket/heapprofd
86adb shell su root mv /dev/socket/heapprofd_primary /dev/socket/heapprofd
87```
88
89Now all subsequent profiles will be done on the primary heapprofd again, with
90the secondary observing it.
91