heapprofd Custom Allocator API - Early Access

WARNING: The heapprofd Custom Allocator API is currently in pre-alpha stage. The API is subject to change, and the implementation might still be unstable. Please file bugs for any issues you encounter.

NOTE: The heapprofd Custom Allocator API requires a device running Android 10 or newer.

Give us a head's up

Thanks for trying out the Custom Allocator API! As this is pre-alpha, we would ask you to file a tracking GitHub issue so we can communicate with you in case we have updated information. You do not need to wait for any reply on the bug before proceeding.

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 AOSP:

$ mkdir aosp && cd aosp
$ repo init -u  https://android.googlesource.com/platform/manifest -b master --partial-clone
$ repo sync -c -j8

Then, build heapprofd_standalone_client for arm64.

$ source build/envsetup.sh
$ lunch aosp_arm64-eng
$ make heapprofd_standalone_client

You will find the built library in out/target/product/generic_arm64/system/lib64/heapprofd_standalone_client.so. The header for the API can be found in external/perfetto/include/perfetto/profiling/memory/heap_profile.h.

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 state of your checkout at the time you built.

repo info > repo-info.txt

Please attach this file to 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):

heap_profile -n $APP_NAME --all-heaps --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):

python /path/to/heap_profile -n %APP_NAME% --all-heaps --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.