1# heapprofd Custom Allocator API - Early Access
2
3WARNING: The heapprofd Custom Allocator API is currently in **beta** stage.
4         Please file [bugs](https://github.com/google/perfetto/issues/new)
5         for any issues you encounter.
6
7NOTE: The heapprofd Custom Allocator API requires a device running Android
8      10 or newer.
9
10## Get SDK
11
12Before instrumenting your app, you need to get the heapprofd library and
13header.
14
15### Option 1: Prebuilts
16
17You can download the library as a binary from [Google Drive](
18https://drive.google.com/drive/folders/15RPlGgAHWRSk7KquBqlQ7fsCaXnNaa6r
19).
20Join our [Google Group](https://groups.google.com/forum/#!forum/perfetto-dev)
21to get access.
22
23### Option 2: Build yourself (on Linux)
24
25Alternatively, you can build the binaries yourself from AOSP.
26
27First, [check out Perfetto](https://perfetto.dev/docs/contributing/build-instructions):
28
29```
30$ git clone https://android.googlesource.com/platform/external/perfetto/
31```
32
33Then, change to the project directory, download and build additional
34dependencies, and then build the standalone library:
35
36```
37$ cd perfetto
38perfetto/ $ tools/install-build-deps --android
39perfetto/ $ tools/build_all_configs.py --android
40perfetto/ $ ninja -C out/android_release_incl_heapprofd_arm64 \
41libheapprofd_standalone_client.so
42```
43
44You will find the built library in
45`out/android_release_incl_heapprofd_arm64/libheapprofd_standalone_client.so`.
46The header for the API can be found in
47`src/profiling/memory/include/perfetto/heap_profile.h`. This library is built
48against SDK version 29, so will work on Android 10 or newer.
49
50WARNING: Only use the header from the checkout you used to build the library,
51         as the API is not stable yet.
52
53To make debugging in the future easier, make note of the revision at the time
54you built.
55
56```
57git rev-parse HEAD > perfetto-version.txt
58```
59Please include this in any bugs you file.
60
61## Instrument App
62
63Let's assume your application has a very simple custom allocator that looks
64like this:
65
66```
67void* my_malloc(size_t size) {
68  void* ptr = [code to somehow allocate get size bytes];
69  return ptr;
70}
71
72void my_free(void* ptr) {
73  [code to somehow free ptr]
74}
75```
76
77To find out where in a program these two functions get called, we instrument
78the allocator using this API:
79
80```
81#include "path/to/heap_profile.h"
82
83static uint32_t g_heap_id = AHeapProfile_registerHeap(
84  AHeapInfo_create("invalid.example"));
85void* my_malloc(size_t size) {
86  void* ptr = [code to somehow allocate get size bytes];
87  AHeapProfile_reportAllocation(g_heap_id, static_cast<uintptr_t>(ptr), size);
88  return ptr;
89}
90
91void my_free(void* ptr) {
92  AHeapProfile_reportFree(g_heap_id, static_cast<uintptr_t>(ptr));
93  [code to somehow free ptr]
94}
95```
96
97Don't forget to link `heapprofd_standalone_client.so` and including it in
98your app.
99
100## Profile your App
101
102Then, use the [heap_profile](
103https://raw.githubusercontent.com/google/perfetto/master/tools/heap_profile)
104script to get a profile to generate textpb of the config.
105To convert to a binary proto, you additionally need to download
106[`perfetto_trace.proto`](
107https://raw.githubusercontent.com/google/perfetto/master/protos/perfetto/trace/perfetto_trace.proto)
108and have recent version of the protoc compiler installed.
109[Learn how to install protoc](https://grpc.io/docs/protoc-installation).
110
111On Linux, you can start a profile using the following pipeline (substitue
112`$APP_NAME` for the name of your app and `$HEAP` for the name of the heap
113you registered using `AHeapProfile_registerHeap`):
114
115```
116heap_profile -n $APP_NAME --heaps $HEAP --print-config | \
117 path/to/protoc --encode=perfetto.protos.TraceConfig perfetto_trace.proto | \
118 adb shell perfetto -c - -o /data/misc/perfetto-traces/profile
119```
120
121On Windows, you will need [python 3.6](https://www.python.org/downloads/) or
122later. You can start a profile using the following pipeline from a command
123prompt (substitue`%APP_NAME%` for the name of your app and `%HEAP%` for
124the name of the heap you registered using `AHeapProfile_registerHeap`):
125
126```
127python /path/to/heap_profile -n %APP_NAME% --heaps %HEAP% --print-config | ^
128 path/to/protoc --encode=perfetto.protos.TraceConfig perfetto_trace.proto | ^
129 adb shell perfetto -c - -o /data/misc/perfetto-traces/profile
130```
131
132Play around with the app to make it cause custom allocations, then stop the
133profile using `adb shell killall perfetto`. Once it is done, pull the profile
134from `/data/misc/perfetto-traces/profile` using `adb pull`.
135
136Upload the profile to the [Perfetto UI](https://ui.perfetto.dev).
137