1# about:memory
2
3about:memory is a special page within Firefox that lets you view, save,
4load, and diff detailed measurements of Firefox's memory usage. It also
5lets you do other memory-related operations like trigger GC and CC, dump
6GC & CC logs, and dump DMD reports. It is present in all builds and does
7not require any preparation to be used.
8
9## How to generate memory reports
10
11Let's assume that you want to measure Firefox's memory usage. Perhaps
12you want to investigate it yourself, or perhaps someone has asked you to
13use about:memory to generate "memory reports" so they can investigate
14a problem you are having. Follow these steps.
15
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.
37
38Note that in both cases the generated data contains privacy-sensitive
39details such as the full list of the web pages you have open in other
40tabs. 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
43stripped out, but it may also make it harder for others to investigate
44the memory usage.
45
46## Loading memory reports from file
47
48The easiest way to load memory reports from file is to use the
49"Load..." button. You can also use the "Load and diff..." button
50to get the difference between two memory report files.
51
52Single memory report files can also be loaded automatically when
53about:memory is loaded by appending a `file` query string, for example:
54
55    about:memory?file=/home/username/reports.json.gz
56
57This is most useful when loading memory reports files obtained from a
58Firefox OS device.
59
60Memory reports are saved to file as gzipped JSON. These files can be
61loaded as is, but they can also be loaded after unzipping.
62
63## Interpreting memory reports
64
65Almost everything you see in about:memory has an explanatory tool-tip.
66Hover over any button to see a description of what it does. Hover over
67any measurement to see a description of what it means.
68
69### [Measurement basics]
70
71Most measurements use bytes as their unit, but some are counts or
72percentages.
73
74Most measurements are presented within trees. For example:
75
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
82
83Leaf nodes represent actual measurements; the value of each internal
84node is the sum of all its children.
85
86The use of trees allows measurements to be broken down into further
87categories, sub-categories, sub-sub-categories, etc., to arbitrary
88depth, as needed. All the measurements within a single tree are
89non-overlapping.
90
91Tree paths can be written using \'/\' as a separator. For example,
92`preference/referent/weak/dead` represents the path to the final leaf
93node in the example tree above.
94
95Sub-trees can be collapsed or expanded by clicking on them. If you find
96any particular tree overwhelming, it can be helpful to collapse all the
97sub-trees immediately below the root, and then gradually expand the
98sub-trees of interest.
99
100### [Sections]
101
102Memory reports are displayed on a per-process basis, with one process
103per section. Within each process's measurements, there are the
104following subsections.
105
106#### Explicit Allocations
107
108This section contains a single tree, called "explicit", that measures
109all the memory allocated via explicit calls to heap allocation functions
110(such as `malloc` and `new`) and to non-heap allocations functions (such
111as `mmap` and `VirtualAlloc`).
112
113Here is an example for a browser session where tabs were open to
114cnn.com, techcrunch.com, and arstechnica.com. Various sub-trees have
115been expanded and others collapsed for the sake of presentation.
116
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
143
144Some expertise is required to understand the full details here, but
145there are various things worth pointing out.
146
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.
176
177Some add-on memory usage is identified, as the following example shows.
178
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)
188
189More things worth pointing out are as follows.
190
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.
204
205#### Other Measurements
206
207This section contains multiple trees, includes many that cross-cut the
208measurements in the "explicit" tree. For example, in the "explicit"
209tree all DOM and layout measurements are broken down by window by
210window, but in "Other Measurements" those measurements are aggregated
211into totals for the whole browser, as the following example shows.
212
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
230
231Some of the trees in this section measure things that do not cross-cut
232the measurements in the "explicit" tree, such as those in the
233"preference-service" example above.
234
235Finally, at the end of this section are individual measurements, as the
236following example shows.
237
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
257
258Some measurements of note are as follows.
259
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.
275