137 lines
4.4 KiB
Markdown
137 lines
4.4 KiB
Markdown
# heapprofd Custom Allocator API - Early Access
|
|
|
|
WARNING: The heapprofd Custom Allocator API is currently in **beta** stage.
|
|
Please file [bugs](https://github.com/google/perfetto/issues/new)
|
|
for any issues you encounter.
|
|
|
|
NOTE: The heapprofd Custom Allocator API requires a device running Android
|
|
10 or newer.
|
|
|
|
## Get SDK
|
|
|
|
Before instrumenting your app, you need to get the heapprofd library and
|
|
header.
|
|
|
|
### Option 1: Prebuilts
|
|
|
|
You can download the library as a binary from [Google Drive](
|
|
https://drive.google.com/drive/folders/15RPlGgAHWRSk7KquBqlQ7fsCaXnNaa6r
|
|
).
|
|
Join our [Google Group](https://groups.google.com/forum/#!forum/perfetto-dev)
|
|
to get access.
|
|
|
|
### Option 2: Build yourself (on Linux)
|
|
|
|
Alternatively, you can build the binaries yourself from AOSP.
|
|
|
|
First, [check out Perfetto](https://perfetto.dev/docs/contributing/build-instructions):
|
|
|
|
```
|
|
$ git clone https://android.googlesource.com/platform/external/perfetto/
|
|
```
|
|
|
|
Then, change to the project directory, download and build additional
|
|
dependencies, and then build the standalone library:
|
|
|
|
```
|
|
$ cd perfetto
|
|
perfetto/ $ tools/install-build-deps --android
|
|
perfetto/ $ tools/build_all_configs.py --android
|
|
perfetto/ $ ninja -C out/android_release_incl_heapprofd_arm64 \
|
|
libheapprofd_standalone_client.so
|
|
```
|
|
|
|
You will find the built library in
|
|
`out/android_release_incl_heapprofd_arm64/libheapprofd_standalone_client.so`.
|
|
The header for the API can be found in
|
|
`src/profiling/memory/include/perfetto/heap_profile.h`. This library is built
|
|
against SDK version 29, so will work on Android 10 or newer.
|
|
|
|
WARNING: Only use the header from the checkout you used to build the library,
|
|
as the API is not stable yet.
|
|
|
|
To make debugging in the future easier, make note of the revision at the time
|
|
you built.
|
|
|
|
```
|
|
git rev-parse HEAD > perfetto-version.txt
|
|
```
|
|
Please include this in any bugs you file.
|
|
|
|
## Instrument App
|
|
|
|
Let's assume your application has a very simple custom allocator that looks
|
|
like this:
|
|
|
|
```
|
|
void* my_malloc(size_t size) {
|
|
void* ptr = [code to somehow allocate get size bytes];
|
|
return ptr;
|
|
}
|
|
|
|
void my_free(void* ptr) {
|
|
[code to somehow free ptr]
|
|
}
|
|
```
|
|
|
|
To find out where in a program these two functions get called, we instrument
|
|
the allocator using this API:
|
|
|
|
```
|
|
#include "path/to/heap_profile.h"
|
|
|
|
static uint32_t g_heap_id = AHeapProfile_registerHeap(
|
|
AHeapInfo_create("invalid.example"));
|
|
void* my_malloc(size_t size) {
|
|
void* ptr = [code to somehow allocate get size bytes];
|
|
AHeapProfile_reportAllocation(g_heap_id, static_cast<uintptr_t>(ptr), size);
|
|
return ptr;
|
|
}
|
|
|
|
void my_free(void* ptr) {
|
|
AHeapProfile_reportFree(g_heap_id, static_cast<uintptr_t>(ptr));
|
|
[code to somehow free ptr]
|
|
}
|
|
```
|
|
|
|
Don't forget to link `heapprofd_standalone_client.so` and including it in
|
|
your app.
|
|
|
|
## Profile your App
|
|
|
|
Then, use the [heap_profile](
|
|
https://raw.githubusercontent.com/google/perfetto/master/tools/heap_profile)
|
|
script to get a profile to generate textpb of the config.
|
|
To convert to a binary proto, you additionally need to download
|
|
[`perfetto_trace.proto`](
|
|
https://raw.githubusercontent.com/google/perfetto/master/protos/perfetto/trace/perfetto_trace.proto)
|
|
and have recent version of the protoc compiler installed.
|
|
[Learn how to install protoc](https://grpc.io/docs/protoc-installation).
|
|
|
|
On Linux, you can start a profile using the following pipeline (substitue
|
|
`$APP_NAME` for the name of your app and `$HEAP` for the name of the heap
|
|
you registered using `AHeapProfile_registerHeap`):
|
|
|
|
```
|
|
heap_profile -n $APP_NAME --heaps $HEAP --print-config | \
|
|
path/to/protoc --encode=perfetto.protos.TraceConfig perfetto_trace.proto | \
|
|
adb shell perfetto -c - -o /data/misc/perfetto-traces/profile
|
|
```
|
|
|
|
On Windows, you will need [python 3.6](https://www.python.org/downloads/) or
|
|
later. You can start a profile using the following pipeline from a command
|
|
prompt (substitue`%APP_NAME%` for the name of your app and `%HEAP%` for
|
|
the name of the heap you registered using `AHeapProfile_registerHeap`):
|
|
|
|
```
|
|
python /path/to/heap_profile -n %APP_NAME% --heaps %HEAP% --print-config | ^
|
|
path/to/protoc --encode=perfetto.protos.TraceConfig perfetto_trace.proto | ^
|
|
adb shell perfetto -c - -o /data/misc/perfetto-traces/profile
|
|
```
|
|
|
|
Play around with the app to make it cause custom allocations, then stop the
|
|
profile using `adb shell killall perfetto`. Once it is done, pull the profile
|
|
from `/data/misc/perfetto-traces/profile` using `adb pull`.
|
|
|
|
Upload the profile to the [Perfetto UI](https://ui.perfetto.dev).
|