ahat - An android heap dump viewer. Initial checkin.
ahat is an android-aware heap dump viewer based on perflib with a
simple html interface.
Change-Id: I7c18a7603dbbe735f778a95cd047f4f9ec1705ef
diff --git a/tools/ahat/README.txt b/tools/ahat/README.txt
new file mode 100644
index 0000000..a8e3884
--- /dev/null
+++ b/tools/ahat/README.txt
@@ -0,0 +1,110 @@
+AHAT - Android Heap Analysis Tool
+
+Usage:
+ java -jar ahat.jar [-p port] FILE
+ Launch an http server for viewing the given Android heap-dump FILE.
+
+ Options:
+ -p <port>
+ Serve pages on the given port. Defaults to 7100.
+
+TODO:
+ * Add more tips to the help page.
+ - Note that only 'app' heap matters, not 'zygote' or 'image'.
+ - Say what a dex cache is.
+ - Recommend how to start looking at a heap dump.
+ - Say how to enable allocation sites.
+ - Where to submit feedback, questions, and bug reports.
+ * Submit perflib fix for getting stack traces, then uncomment that code in
+ AhatSnapshot to use that.
+ * Dim 'image' and 'zygote' heap sizes slightly? Why do we even show these?
+ * Filter out RootObjs in mSnapshot.getGCRoots, not RootsHandler.
+ * Let user re-sort sites objects info by clicking column headers.
+ * Let user re-sort "Objects" list.
+ * Show site context and heap and class filter in "Objects" view?
+ * Have a menu at the top of an object view with links to the sections?
+ * Include ahat version and hprof file in the menu at the top of the page?
+ * Heaped Table
+ - Make sortable by clicking on headers.
+ - Use consistent order for heap columns.
+ Sometimes I see "app" first, sometimes last (from one heap dump to
+ another) How about, always sort by name?
+ * For long strings, limit the string length shown in the summary view to
+ something reasonable. Say 50 chars, then add a "..." at the end.
+ * For string summaries, if the string is an offset into a bigger byte array,
+ make sure to show just the part that's in the bigger byte array, not the
+ entire byte array.
+ * For HeapTable with single heap shown, the heap name isn't centered?
+ * Consistently document functions.
+ * Should help be part of an AhatHandler, that automatically gets the menu and
+ stylesheet link rather than duplicating that?
+ * Show version number with --version.
+ * Show somewhere where to send bugs.
+ * /objects query takes a long time to load without parameters.
+ * Include a link to /objects in the overview and menu?
+ * Turn on LOCAL_JAVACFLAGS := -Xlint:unchecked -Werror
+ * Use hex for object ids in URLs?
+ * In general, all tables and descriptions should show a limited amount to
+ start, and only show more when requested by the user.
+ * Don't have handlers inherit from HttpHandler
+ - because they should be independent from http.
+
+ * [low priority] by site allocations won't line up if the stack has been
+ truncated. Is there any way to manually line them up in that case?
+
+ * [low priority] Have a switch to choose whether unreachable objects are
+ ignored or not? Is there any interest in what's unreachable, or is it only
+ reachable objects that people care about?
+
+ * [low priority] Have a way to diff two heap dumps by site.
+ This should be pretty easy to do, actually. The interface is the real
+ question. Maybe: augment each byte count field on every page with the diff
+ if a baseline has been provided, and allow the user to sort by the diff.
+
+Things to Test:
+ * That we can open a hprof without an 'app' heap and show a tabulation of
+ objects normally sorted by 'app' heap by default.
+ * Visit /objects without parameters and verify it doesn't throw an exception.
+ * Visit /objects with an invalid site, verify it doesn't throw an exception.
+ * That we can view an array with 3 million elements in a reasonably short
+ amount of time (not more than 1 second?)
+ * That we can view the list of all objects in a reasonably short amount of
+ time.
+ * That we don't show the 'extra' column in the DominatedList if we are
+ showing all the instances.
+
+Reported Issues:
+ * Request to be able to sort tables by size.
+ * Hangs on showing large arrays, where hat does not hang.
+ - Solution is probably to not show all the array elements by default.
+
+Perflib Requests:
+ * Class objects should have java.lang.Class as their class object, not null.
+ * ArrayInstance should have asString() to get the string, without requiring a
+ length function.
+ * Document that getHeapIndex returns -1 for no such heap.
+ * Look up totalRetainedSize for a heap by Heap object, not by a separate heap
+ index.
+ * What's the difference between getId and getUniqueId?
+ * I see objects with duplicate references.
+ * Don't store stack trace by heap (CL 157252)
+ * A way to get overall retained size by heap.
+ * A method Instance.isReachable()
+
+Things to move to perflib:
+ * Extracting the string from a String Instance.
+ * Extracting bitmap data from bitmap instances.
+ * Adding up allocations by stack frame.
+ * Computing, for each instance, the other instances it dominates.
+
+Release History:
+ 0.1ss Aug 04, 2015
+ Enable stack allocations code (using custom modified perflib).
+ Sort objects in 'objects/' with default sort.
+
+ 0.1-stacks Aug 03, 2015
+ Enable stack allocations code (using custom modified perflib).
+
+ 0.1 July 30, 2015
+ Initial Release
+