tools/ahat/README.txt

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 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.
 * That InstanceUtils.asString properly takes into account "offset" and
   "count" fields, if they are present.

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