README.txt
1AHAT - Android Heap Analysis Tool
2
3Usage:
4 java -jar ahat.jar [OPTIONS] FILE
5 Launch an http server for viewing the given Android heap dump FILE.
6
7 OPTIONS:
8 -p <port>
9 Serve pages on the given port. Defaults to 7100.
10 --proguard-map FILE
11 Use the proguard map FILE to deobfuscate the heap dump.
12 --baseline FILE
13 Diff the heap dump against the given baseline heap dump FILE.
14 --baseline-proguard-map FILE
15 Use the proguard map FILE to deobfuscate the baseline heap dump.
16 --retained [strong | soft | finalizer | weak | phantom | unreachable]
17 The weakest reachability of instances to treat as retained.
18 Defaults to soft
19
20TODO:
21 * Add a user guide.
22 * Dim 'image' and 'zygote' heap sizes slightly? Why do we even show these?
23 * Let user re-sort sites objects info by clicking column headers.
24 * Let user re-sort "Objects" list.
25 * Show site context and heap and class filter in "Objects" view?
26 * Have a menu at the top of an object view with links to the sections?
27 * Include ahat version and hprof file in the menu at the top of the page?
28 * Heaped Table
29 - Make sortable by clicking on headers.
30 * For HeapTable with single heap shown, the heap name isn't centered?
31 * Consistently document functions.
32 * Show version number with --version.
33 * Show somewhere where to send bugs.
34 * Include a link to /objects in the overview and menu?
35 * Turn on LOCAL_JAVACFLAGS := -Xlint:unchecked -Werror
36
37 * [low priority] by site allocations won't line up if the stack has been
38 truncated. Is there any way to manually line them up in that case?
39
40Things to Test:
41 * That we can open a hprof without an 'app' heap and show a tabulation of
42 objects normally sorted by 'app' heap by default.
43 * Visit /objects without parameters and verify it doesn't throw an exception.
44 * Visit /objects with an invalid site, verify it doesn't throw an exception.
45 * That we can view the list of all objects in a reasonably short amount of
46 time.
47 * That we don't show the 'extra' column in the DominatedList if we are
48 showing all the instances.
49 * Instance.getDexCacheLocation
50
51Reported Issues:
52 * Request to be able to sort tables by size.
53
54Known Issues:
55 * Line number decoding for allocations in proguarded classes.
56
57Release History:
58 1.8 January 02, 2025
59 Show string values of byte[] instances.
60 Fix accounting for cleaned native registrations
61 Add option to download the contents of a byte[] as a file.
62 Show retained size in allocations view.
63
64 1.7.3 June 27, 2024
65 Add support to display bitmaps included in heapdump. To use this
66 functionality, collect the heapdump with `adb shell am dumpheap -b <fmt>`,
67 <fmt> can be `png`, `jpg` or `webp`.
68
69 1.7.2 March 2, 2022
70 Fix ahat parsing to allow leading whitespaces for comments.
71 Hide Value class constructor.
72
73 1.7.1 September 30, 2020
74 Fix issue parsing proguard maps with comments.
75
76 1.7 August 8, 2019
77 Annotate binder services, tokens, and proxies.
78 Add option for viewing subclass instances of a class.
79 Recognize java.lang.ref.Finalizer as a finalizer reference.
80 Minor bug fixes and API improvements.
81
82 1.6 July 24, 2018
83 Distinguish between soft/weak/phantom/etc references.
84 Annotate $classOverhead byte[] arrays with their class.
85 Show progress of heap dump processing.
86 Add --retained command line option to ahat.
87 Support heap dumps generated with HotSpotDiagnosticMXBean.
88 Updated public APIs for dominators computation, reachability and parser.
89 AhatInstance no longer implements DominatorsComputation.Node
90 Bug fixes.
91
92 1.5 December 05, 2017
93 Distinguish between weakly reachable and unreachable instances.
94 Allow hex ids to be used for objects in query parameters.
95 Restore old presentation of sample paths from gc roots.
96 Fix bug in selection of sample paths from gc root.
97 Fix bug in proguard deobfuscation of stack frames.
98 Tighten up and document ahat public API.
99
100 1.4 October 03, 2017
101 Give better error messages on failure to launch ahat.
102 Properly mark thread and non-default root objects as roots.
103 Improve startup performance, in some cases significantly.
104 Other miscellaneous bug fixes.
105
106 1.3.1 August 22, 2017
107 Don't include weak references in sample paths.
108
109 1.3 July 25, 2017
110 Improve diffing of static and instance fields.
111 Improve startup performance by roughly 25%.
112
113 1.2 May 26, 2017
114 Show registered native sizes of objects.
115 Simplify presentation of sample path from gc root.
116
117 1.1 Feb 21, 2017
118 Show java.lang.ref.Reference referents as "unreachable" instead of null.
119
120 1.0 Dec 20, 2016
121 Add support for diffing two heap dumps.
122 Remove native allocations view.
123 Remove outdated help page.
124 Significant refactoring of ahat internals.
125
126 0.8 Oct 18, 2016
127 Show sample path from GC root with field names in place of dominator path.
128
129 0.7 Aug 16, 2016
130 Launch ahat server before processing the heap dump.
131 Target Java 1.7.
132
133 0.6 Jun 21, 2016
134 Add support for proguard deobfuscation.
135
136 0.5 Apr 19, 2016
137 Update perflib to perflib-25.0.0 to improve processing performance.
138
139 0.4 Feb 23, 2016
140 Annotate char[] objects with their string values.
141 Show registered native allocations for heap dumps that support it.
142
143 0.3 Dec 15, 2015
144 Fix page loading performance by showing a limited number of entries by default.
145 Fix mismatch between overview and "roots" totals.
146 Annotate root objects and show their types.
147 Annotate references with their referents.
148
149 0.2 Oct 20, 2015
150 Take into account 'count' and 'offset' when displaying strings.
151
152 0.1ss Aug 04, 2015
153 Enable stack allocations code (using custom modified perflib).
154 Sort objects in 'objects/' with default sort.
155
156 0.1-stacks Aug 03, 2015
157 Enable stack allocations code (using custom modified perflib).
158
159 0.1 July 30, 2015
160 Initial Release
161
162