docs: Explain Java heap sampler This updates the memory docs a little bit: * Renames most mentions of Java heap profiler with Java heap dump or graph, to avoid confusion with the java heap sampler. * Updates the memory flamegraph images: we've updated some of the labels since, and the images where out of date. * It renames the "Native heap profiler" page to simply "Heap profiler". * It documents the java heap sampler under the "Heap profiler" page. Bug: 218414058 Bug: 256052262 Change-Id: Id4a7fdd652bf03bfbe55bbd72931bec4c87609ac
diff --git a/docs/data-sources/java-heap-profiler.md b/docs/data-sources/java-heap-profiler.md index f67cf03..e3d5921 100644 --- a/docs/data-sources/java-heap-profiler.md +++ b/docs/data-sources/java-heap-profiler.md
@@ -1,15 +1,17 @@ -# Memory: Java heap profiler +# Memory: Java heap dumps -NOTE: The Java heap profiler requires Android 11 or higher +NOTE: Capturing Java heap dumps requires Android 11 or higher See the [Memory Guide](/docs/case-studies/memory.md#java-hprof) for getting -started with Java heap profiling. +started with Java heap dumps. -Conversely from the [Native heap profiler](native-heap-profiler.md), the Java -heap profiler reports full retention graphs of managed objects but not -call-stacks. The information recorded by the Java heap profiler is of the form: -_Object X retains object Y, which is N bytes large, through its class member -named Z_. +Conversely from [Native heap profiles](native-heap-profiler.md), Java heap dumps +report full retention graphs of managed objects but not call-stacks. The +information recorded in a Java heap dump is of the form: _Object X retains +object Y, which is N bytes large, through its class member named Z_. + +Java heap dumps are not to be confused with profiles taken by the +[Java heap sampler](native-heap-profiler.md#java-heap-sampling) ## UI @@ -17,13 +19,13 @@ diamond in the _"Heap Profile"_ track of a process. Each diamond corresponds to a heap dump. - + - + The native size of certain objects is represented as an extra child node in the flamegraph, prefixed with "[native]". The extra node counts as an extra object. -This is available only on Android T+. +This is available only on Android 13 or higher. ## SQL @@ -93,7 +95,7 @@ ## TraceConfig -The Java heap profiler is configured through the +The Java heap dump data source is configured through the [JavaHprofConfig](/docs/reference/trace-config-proto.autogen#JavaHprofConfig) section of the trace config.
diff --git a/docs/data-sources/native-heap-profiler.md b/docs/data-sources/native-heap-profiler.md index f051124..1859295 100644 --- a/docs/data-sources/native-heap-profiler.md +++ b/docs/data-sources/native-heap-profiler.md
@@ -1,13 +1,17 @@ -# Native heap profiler +# Heap profiler NOTE: **heapprofd requires Android 10 or higher** -Heapprofd is a tool that tracks native heap allocations & deallocations of an -Android process within a given time period. The resulting profile can be used to +Heapprofd is a tool that tracks heap allocations & deallocations of an Android +process within a given time period. The resulting profile can be used to attribute memory usage to particular call-stacks, supporting a mix of both native and java code. The tool can be used by Android platform and app developers to investigate memory issues. +By default, the tool records native allocations and deallocations done with +malloc/free (or new/delete). It can be configured to record java heap memory +allocations instead: see [Java heap sampling](#java-heap-sampling) below. + On debug Android builds, you can profile all apps and most system services. On "user" builds, you can only use it on apps with the debuggable or profileable manifest flag. @@ -25,7 +29,7 @@  - + ## SQL @@ -80,14 +84,14 @@ The resulting profile proto contains four views on the data -* **Unreleased size**: how many bytes were allocated but not freed at this - callstack the moment the dump was created. -* **Total size**: how many bytes were allocated (including ones freed at the - moment of the dump) at this callstack -* **Unreleased count**: how many allocations without matching frees were done at - this callstack. -* **Total count**: how many allocations (including ones with matching frees) - were done at this callstack. +* **Unreleased malloc size**: how many bytes were allocated but not freed at + this callstack the moment the dump was created. +* **Total malloc size**: how many bytes were allocated (including ones freed at + the moment of the dump) at this callstack. +* **Unreleased malloc count**: how many allocations without matching frees were + done at this callstack. +* **Total malloc count**: how many allocations (including ones with matching + frees) were done at this callstack. _(Googlers: You can also open the gzipped protos using http://pprof/)_ @@ -217,6 +221,41 @@ </manifest> ``` +## {#java-heap-sampling} Java heap sampling + +NOTE: **Java heap sampling is available on Android 12 or higher** + +NOTE: **Java heap sampling is not to be confused with [Java heap +dumps](/docs/data-sources/java-heap-profiler.md)** + +Heapprofd can be configured to track Java allocations instead of native one. +* By setting adding `heaps: "com.android.art"` in + [HeapprofdConfig](/docs/reference/trace-config-proto.autogen#HeapprofdConfig). +* By adding `--heaps com.android.art` to the invocation of + [`tools/heap_profile`](/docs/reference/heap_profile-cli). + +Unlike java heap dumps (which show the retention graph of a snapshot of the live +objects) but like native heap profiles, java heap samples show callstacks of +allocations over time of the entire profile. + +Java heap samples only show callstacks of when objects are created, not when +they're deleted or garbage collected. + + + +The resulting profile proto contains two views on the data: + +* **Total allocation size**: how many bytes were allocated at this callstack + over time of the profile until this point. The bytes might have been freed or + not, the tool does not keep track of that. +* **Total allocation count**: how many object were allocated at this callstack + over time of the profile until this point. The objects might have been freed + or not, the tool does not keep track of that. + +Java heap samples are useful to understand memory churn showing the call stack +of which parts of the code large allocations are attributed to as well as the +allocation type from the ART runtime. + ## DEDUPED frames If the name of a Java method includes `[DEDUPED]`, this means that multiple