| blob | ab9dc81062724857930bb510f88822e8d57e42a7 |
1 # about:memory
3 about:memory is a special page within Firefox that lets you view, save,
4 load, and diff detailed measurements of Firefox's memory usage. It also
5 lets you do other memory-related operations like trigger GC and CC, dump
6 GC & CC logs, and dump DMD reports. It is present in all builds and does
7 not require any preparation to be used.
9 ## How to generate memory reports
11 Let's assume that you want to measure Firefox's memory usage. Perhaps
12 you want to investigate it yourself, or perhaps someone has asked you to
13 use about:memory to generate "memory reports" so they can investigate
14 a problem you are having. Follow these steps.
16 - At the moment of interest (e.g. once Firefox's memory usage has
17 gotten high) open a new tab and type "about:memory" into the
18 address bar and hit "Enter".
19 - If you are using a communication channel where files can be sent,
20 such as Bugzilla or email, click on the "Measure and save..."
21 button. This will open a file dialog that lets you save the memory
22 reports to a file of your choosing. (The filename will have a
23 `.json.gz` suffix.) You can then attach or upload the file
24 appropriately. The recipients will be able to view the contents of
25 this file within about:memory in their own Firefox instance.
26 - If you are using a communication channel where only text can be
27 sent, such as a comment thread on a website, click on the
28 "Measure..." button. This will cause a tree-like structure to be
29 generated text within about:memory. This structure is just text, so
30 you can copy and paste some or all of this text into any kind of
31 text buffer. (You don't need to take a screenshot.) This text
32 contains fewer measurements than a memory reports file, but is often
33 good enough to diagnose problems. Don't click "Measure..."
34 repeatedly, because that will cause the memory usage of about:memory
35 itself to rise, due to it discarding and regenerating large numbers
36 of DOM nodes.
38 Note that in both cases the generated data contains privacy-sensitive
39 details such as the full list of the web pages you have open in other
40 tabs. If you do not wish to share this information, you can select the
41 "anonymize" checkbox before clicking on "Measure and save..." or
42 "Measure...". This will cause the privacy-sensitive data to be
43 stripped out, but it may also make it harder for others to investigate
44 the memory usage.
46 ## Loading memory reports from file
48 The easiest way to load memory reports from file is to use the
49 "Load..." button. You can also use the "Load and diff..." button
50 to get the difference between two memory report files.
52 Single memory report files can also be loaded automatically when
53 about:memory is loaded by appending a `file` query string, for example:
55 about:memory?file=/home/username/reports.json.gz
57 This is most useful when loading memory reports files obtained from a
58 Firefox OS device.
60 Memory reports are saved to file as gzipped JSON. These files can be
61 loaded as is, but they can also be loaded after unzipping.
63 ## Interpreting memory reports
65 Almost everything you see in about:memory has an explanatory tool-tip.
66 Hover over any button to see a description of what it does. Hover over
67 any measurement to see a description of what it means.
69 ### [Measurement basics]
71 Most measurements use bytes as their unit, but some are counts or
72 percentages.
74 Most measurements are presented within trees. For example:
76 585 (100.0%) -- preference-service
77 └──585 (100.0%) -- referent
78 ├──493 (84.27%) ── strong
79 └───92 (15.73%) -- weak
80 ├──92 (15.73%) ── alive
81 └───0 (00.00%) ── dead
83 Leaf nodes represent actual measurements; the value of each internal
84 node is the sum of all its children.
86 The use of trees allows measurements to be broken down into further
87 categories, sub-categories, sub-sub-categories, etc., to arbitrary
88 depth, as needed. All the measurements within a single tree are
89 non-overlapping.
91 Tree paths can be written using \'/\' as a separator. For example,
92 `preference/referent/weak/dead` represents the path to the final leaf
93 node in the example tree above.
95 Sub-trees can be collapsed or expanded by clicking on them. If you find
96 any particular tree overwhelming, it can be helpful to collapse all the
97 sub-trees immediately below the root, and then gradually expand the
98 sub-trees of interest.
100 ### [Sections]
102 Memory reports are displayed on a per-process basis, with one process
103 per section. Within each process's measurements, there are the
104 following subsections.
106 #### Explicit Allocations
108 This section contains a single tree, called "explicit", that measures
109 all the memory allocated via explicit calls to heap allocation functions
110 (such as `malloc` and `new`) and to non-heap allocations functions (such
111 as `mmap` and `VirtualAlloc`).
113 Here is an example for a browser session where tabs were open to
114 cnn.com, techcrunch.com, and arstechnica.com. Various sub-trees have
115 been expanded and others collapsed for the sake of presentation.
117 191.89 MB (100.0%) -- explicit
118 ├───63.15 MB (32.91%) -- window-objects
119 │ ├──24.57 MB (12.80%) -- top(http://edition.cnn.com/, id=8)
120 │ │ ├──20.18 MB (10.52%) -- active
121 │ │ │ ├──10.57 MB (05.51%) -- window(http://edition.cnn.com/)
122 │ │ │ │ ├───4.55 MB (02.37%) ++ js-compartment(http://edition.cnn.com/)
123 │ │ │ │ ├───2.60 MB (01.36%) ++ layout
124 │ │ │ │ ├───1.94 MB (01.01%) ── style-sheets
125 │ │ │ │ └───1.48 MB (00.77%) -- (2 tiny)
126 │ │ │ │ ├──1.43 MB (00.75%) ++ dom
127 │ │ │ │ └──0.05 MB (00.02%) ── property-tables
128 │ │ │ └───9.61 MB (05.01%) ++ (18 tiny)
129 │ │ └───4.39 MB (02.29%) -- js-zone(0x7f69425b5800)
130 │ ├──15.75 MB (08.21%) ++ top(http://techcrunch.com/, id=20)
131 │ ├──12.85 MB (06.69%) ++ top(http://arstechnica.com/, id=14)
132 │ ├───6.40 MB (03.33%) ++ top(chrome://browser/content/browser.xul, id=3)
133 │ └───3.59 MB (01.87%) ++ (4 tiny)
134 ├───45.74 MB (23.84%) ++ js-non-window
135 ├───33.73 MB (17.58%) ── heap-unclassified
136 ├───22.51 MB (11.73%) ++ heap-overhead
137 ├────6.62 MB (03.45%) ++ images
138 ├────5.82 MB (03.03%) ++ workers/workers(chrome)
139 ├────5.36 MB (02.80%) ++ (16 tiny)
140 ├────4.07 MB (02.12%) ++ storage
141 ├────2.74 MB (01.43%) ++ startup-cache
142 └────2.16 MB (01.12%) ++ xpconnect
144 Some expertise is required to understand the full details here, but
145 there are various things worth pointing out.
147 - This "explicit" value at the root of the tree represents all the
148 memory allocated via explicit calls to allocation functions.
149 - The "window-objects" sub-tree represents all JavaScript `window`
150 objects, which includes the browser tabs and UI windows. For
151 example, the "top(http://edition.cnn.com/, id=8)" sub-tree
152 represents the tab open to cnn.com, and
153 "top(chrome://browser/content/browser.xul, id=3)" represents the
154 main browser UI window.
155 - Within each window's measurements are sub-trees for JavaScript
156 ("js-compartment(...)" and "js-zone(...)"), layout,
157 style-sheets, the DOM, and other things.
158 - It's clear that the cnn.com tab is using more memory than the
159 techcrunch.com tab, which is using more than the arstechnica.com
160 tab.
161 - Sub-trees with names like "(2 tiny)" are artificial nodes inserted
162 to allow insignificant sub-trees to be collapsed by default. If you
163 select the "verbose" checkbox before measuring, all trees will be
164 shown fully expanded and no artificial nodes will be inserted.
165 - The "js-non-window" sub-tree represents JavaScript memory usage
166 that doesn't come from windows, but from the browser core.
167 - The "heap-unclassified" value represents heap-allocated memory
168 that is not measured by any memory reporter. This is typically
169 10--20% of "explicit". If it gets higher, it indicates that
170 additional memory reporters should be added.
171 [DMD](./dmd.md)
172 can be used to determine where these memory reporters should be
173 added.
174 - There are measurements for other content such as images and workers,
175 and for browser subsystems such as the startup cache and XPConnect.
177 Some add-on memory usage is identified, as the following example shows.
179 ├───40,214,384 B (04.17%) -- add-ons
180 │ ├──21,184,320 B (02.20%) ++ {d10d0bf8-f5b5-c8b4-a8b2-2b9879e08c5d}/js-non-window/zones/zone(0x100496800)/compartment([System Principal], jar:file:///Users/njn/Library/Application%20Support/Firefox/Profiles/puna0zr8.new/extensions/%7Bd10d0bf8-f5b5-c8b4-a8b2-2b9879e08c5d%7D.xpi!/bootstrap.js (from: resource://gre/modules/addons/XPIProvider.jsm:4307))
181 │ ├──11,583,312 B (01.20%) ++ jid1-xUfzOsOFlzSOXg@jetpack/js-non-window/zones/zone(0x100496800)
182 │ ├───5,574,608 B (00.58%) -- {59c81df5-4b7a-477b-912d-4e0fdf64e5f2}
183 │ │ ├──5,529,280 B (00.57%) -- window-objects
184 │ │ │ ├──4,175,584 B (00.43%) ++ top(chrome://chatzilla/content/chatzilla.xul, id=4293)
185 │ │ │ └──1,353,696 B (00.14%) ++ top(chrome://chatzilla/content/output-window.html, id=4298)
186 │ │ └─────45,328 B (00.00%) ++ js-non-window/zones/zone(0x100496800)/compartment([System Principal], file:///Users/njn/Library/Application%20Support/Firefox/Profiles/puna0zr8.new/extensions/%7B59c81df5-4b7a-477b-912d-4e0fdf64e5f2%7D/components/chatzilla-service.js)
187 │ └───1,872,144 B (00.19%) ++ treestyletab@piro.sakura.ne.jp/js-non-window/zones/zone(0x100496800)
189 More things worth pointing out are as follows.
191 - Some add-ons are identified by a name, such as Tree Style Tab.
192 Others are identified only by a hexadecimal identifier. You can look
193 in about:support to see which add-on a particular identifier belongs
194 to. For example, `59c81df5-4b7a-477b-912d-4e0fdf64e5f2` is
195 Chatzilla.
196 - All JavaScript memory usage for an add-on is measured separately and
197 shown in this sub-tree.
198 - For add-ons that use separate windows, such as Chatzilla, the memory
199 usage of those windows will show up in this sub-tree.
200 - For add-ons that use XUL overlays, such as AdBlock Plus, the memory
201 usage of those overlays will not show up in this sub-tree; it will
202 instead be in the non-add-on sub-trees and won't be identifiable as
203 being caused by the add-on.
205 #### Other Measurements
207 This section contains multiple trees, includes many that cross-cut the
208 measurements in the "explicit" tree. For example, in the "explicit"
209 tree all DOM and layout measurements are broken down by window by
210 window, but in "Other Measurements" those measurements are aggregated
211 into totals for the whole browser, as the following example shows.
213 26.77 MB (100.0%) -- window-objects
214 ├──14.59 MB (54.52%) -- layout
215 │ ├───6.22 MB (23.24%) ── style-sets
216 │ ├───4.00 MB (14.95%) ── pres-shell
217 │ ├───1.79 MB (06.68%) ── frames
218 │ ├───0.89 MB (03.33%) ── style-contexts
219 │ ├───0.62 MB (02.33%) ── rule-nodes
220 │ ├───0.56 MB (02.10%) ── pres-contexts
221 │ ├───0.47 MB (01.75%) ── line-boxes
222 │ └───0.04 MB (00.14%) ── text-runs
223 ├───6.53 MB (24.39%) ── style-sheets
224 ├───5.59 MB (20.89%) -- dom
225 │ ├──3.39 MB (12.66%) ── element-nodes
226 │ ├──1.56 MB (05.84%) ── text-nodes
227 │ ├──0.54 MB (02.03%) ── other
228 │ └──0.10 MB (00.36%) ++ (4 tiny)
229 └───0.06 MB (00.21%) ── property-tables
231 Some of the trees in this section measure things that do not cross-cut
232 the measurements in the "explicit" tree, such as those in the
233 "preference-service" example above.
235 Finally, at the end of this section are individual measurements, as the
236 following example shows.
238 0.00 MB ── canvas-2d-pixels
239 5.38 MB ── gfx-surface-xlib
240 0.00 MB ── gfx-textures
241 0.00 MB ── gfx-tiles-waste
242 0 ── ghost-windows
243 109.22 MB ── heap-allocated
244 164 ── heap-chunks
245 1.00 MB ── heap-chunksize
246 114.51 MB ── heap-committed
247 164.00 MB ── heap-mapped
248 4.84% ── heap-overhead-ratio
249 1 ── host-object-urls
250 0.00 MB ── imagelib-surface-cache
251 5.27 MB ── js-main-runtime-temporary-peak
252 0 ── page-faults-hard
253 203,349 ── page-faults-soft
254 274.99 MB ── resident
255 251.47 MB ── resident-unique
256 1,103.64 MB ── vsize
258 Some measurements of note are as follows.
260 - "resident". Physical memory usage. If you want a single
261 measurement to summarize memory usage, this is probably the best
262 one.
263 - "vsize". Virtual memory usage. This is often much higher than any
264 other measurement (particularly on Mac). It only really matters on
265 32-bit platforms such as Win32. There is also
266 "vsize-max-contiguous" (not measured on all platforms, and not
267 shown in this example), which indicates the largest single chunk of
268 available virtual address space. If this number is low, it's likely
269 that memory allocations will fail due to lack of virtual address
270 space quite soon.
271 - Various graphics-related measurements ("gfx-*"). The measurements
272 taken vary between platforms. Graphics is often a source of high
273 memory usage, and so these measurements can be helpful for detecting
274 such cases.