derek.holloway
7502bf64a4
4.4 KiB
heapprofd Custom Allocator API - Early Access
WARNING: The heapprofd Custom Allocator API is currently in beta stage. Please file bugs 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. Join our Google Group to get access.
Option 2: Build yourself (on Linux)
Alternatively, you can build the binaries yourself from AOSP.
First, check out Perfetto:
$ 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/setup_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
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
and have recent version of the protoc compiler installed.
Learn how to install protoc.
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 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.