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