Source code
Revision control
Copy as Markdown
Other Tools
# about:memory
about:memory is a special page within Firefox that lets you view, save,
load, and diff detailed measurements of Firefox's memory usage. It also
lets you do other memory-related operations like trigger GC and CC, dump
GC & CC logs, and dump DMD reports. It is present in all builds and does
not require any preparation to be used.
## How to generate memory reports
Let's assume that you want to measure Firefox's memory usage. Perhaps
you want to investigate it yourself, or perhaps someone has asked you to
use about:memory to generate "memory reports" so they can investigate
a problem you are having. Follow these steps.
- At the moment of interest (e.g. once Firefox's memory usage has
gotten high) open a new tab and type "about:memory" into the
address bar and hit "Enter".
- If you are using a communication channel where files can be sent,
such as Bugzilla or email, click on the "Measure and save..."
button. This will open a file dialog that lets you save the memory
reports to a file of your choosing. (The filename will have a
`.json.gz` suffix.) You can then attach or upload the file
appropriately. The recipients will be able to view the contents of
this file within about:memory in their own Firefox instance.
- If you are using a communication channel where only text can be
sent, such as a comment thread on a website, click on the
"Measure..." button. This will cause a tree-like structure to be
generated text within about:memory. This structure is just text, so
you can copy and paste some or all of this text into any kind of
text buffer. (You don't need to take a screenshot.) This text
contains fewer measurements than a memory reports file, but is often
good enough to diagnose problems. Don't click "Measure..."
repeatedly, because that will cause the memory usage of about:memory
itself to rise, due to it discarding and regenerating large numbers
of DOM nodes.
Note that in both cases the generated data contains privacy-sensitive
details such as the full list of the web pages you have open in other
tabs. If you do not wish to share this information, you can select the
"anonymize" checkbox before clicking on "Measure and save..." or
"Measure...". This will cause the privacy-sensitive data to be
stripped out, but it may also make it harder for others to investigate
the memory usage.
## Loading memory reports from file
The easiest way to load memory reports from file is to use the
"Load..." button. You can also use the "Load and diff..." button
to get the difference between two memory report files.
Single memory report files can also be loaded automatically when
about:memory is loaded by appending a `file` query string, for example:
about:memory?file=/home/username/reports.json.gz
This is most useful when loading memory reports files obtained from a
Firefox OS device.
Memory reports are saved to file as gzipped JSON. These files can be
loaded as is, but they can also be loaded after unzipping.
## Interpreting memory reports
Almost everything you see in about:memory has an explanatory tool-tip.
Hover over any button to see a description of what it does. Hover over
any measurement to see a description of what it means.
### [Measurement basics]
Most measurements use bytes as their unit, but some are counts or
percentages.
Most measurements are presented within trees. For example:
585 (100.0%) -- preference-service
└──585 (100.0%) -- referent
├──493 (84.27%) ── strong
└───92 (15.73%) -- weak
├──92 (15.73%) ── alive
└───0 (00.00%) ── dead
Leaf nodes represent actual measurements; the value of each internal
node is the sum of all its children.
The use of trees allows measurements to be broken down into further
categories, sub-categories, sub-sub-categories, etc., to arbitrary
depth, as needed. All the measurements within a single tree are
non-overlapping.
Tree paths can be written using \'/\' as a separator. For example,
`preference/referent/weak/dead` represents the path to the final leaf
node in the example tree above.
Sub-trees can be collapsed or expanded by clicking on them. If you find
any particular tree overwhelming, it can be helpful to collapse all the
sub-trees immediately below the root, and then gradually expand the
sub-trees of interest.
### [Sections]
Memory reports are displayed on a per-process basis, with one process
per section. Within each process's measurements, there are the
following subsections.
#### Explicit Allocations
This section contains a single tree, called "explicit", that measures
all the memory allocated via explicit calls to heap allocation functions
(such as `malloc` and `new`) and to non-heap allocations functions (such
as `mmap` and `VirtualAlloc`).
Here is an example for a browser session where tabs were open to
cnn.com, techcrunch.com, and arstechnica.com. Various sub-trees have
been expanded and others collapsed for the sake of presentation.
191.89 MB (100.0%) -- explicit
├───63.15 MB (32.91%) -- window-objects
│ │ ├──20.18 MB (10.52%) -- active
│ │ │ │ ├───2.60 MB (01.36%) ++ layout
│ │ │ │ ├───1.94 MB (01.01%) ── style-sheets
│ │ │ │ └───1.48 MB (00.77%) -- (2 tiny)
│ │ │ │ ├──1.43 MB (00.75%) ++ dom
│ │ │ │ └──0.05 MB (00.02%) ── property-tables
│ │ │ └───9.61 MB (05.01%) ++ (18 tiny)
│ │ └───4.39 MB (02.29%) -- js-zone(0x7f69425b5800)
│ └───3.59 MB (01.87%) ++ (4 tiny)
├───45.74 MB (23.84%) ++ js-non-window
├───33.73 MB (17.58%) ── heap-unclassified
├───22.51 MB (11.73%) ++ heap-overhead
├────6.62 MB (03.45%) ++ images
├────5.82 MB (03.03%) ++ workers/workers(chrome)
├────5.36 MB (02.80%) ++ (16 tiny)
├────4.07 MB (02.12%) ++ storage
├────2.74 MB (01.43%) ++ startup-cache
└────2.16 MB (01.12%) ++ xpconnect
Some expertise is required to understand the full details here, but
there are various things worth pointing out.
- This "explicit" value at the root of the tree represents all the
memory allocated via explicit calls to allocation functions.
- The "window-objects" sub-tree represents all JavaScript `window`
objects, which includes the browser tabs and UI windows. For
represents the tab open to cnn.com, and
main browser UI window.
- Within each window's measurements are sub-trees for JavaScript
("js-compartment(...)" and "js-zone(...)"), layout,
style-sheets, the DOM, and other things.
- It's clear that the cnn.com tab is using more memory than the
techcrunch.com tab, which is using more than the arstechnica.com
tab.
- Sub-trees with names like "(2 tiny)" are artificial nodes inserted
to allow insignificant sub-trees to be collapsed by default. If you
select the "verbose" checkbox before measuring, all trees will be
shown fully expanded and no artificial nodes will be inserted.
- The "js-non-window" sub-tree represents JavaScript memory usage
that doesn't come from windows, but from the browser core.
- The "heap-unclassified" value represents heap-allocated memory
that is not measured by any memory reporter. This is typically
10--20% of "explicit". If it gets higher, it indicates that
additional memory reporters should be added.
[DMD](./dmd.md)
can be used to determine where these memory reporters should be
added.
- There are measurements for other content such as images and workers,
and for browser subsystems such as the startup cache and XPConnect.
Some add-on memory usage is identified, as the following example shows.
├───40,214,384 B (04.17%) -- add-ons
│ ├──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))
│ ├──11,583,312 B (01.20%) ++ jid1-xUfzOsOFlzSOXg@jetpack/js-non-window/zones/zone(0x100496800)
│ ├───5,574,608 B (00.58%) -- {59c81df5-4b7a-477b-912d-4e0fdf64e5f2}
│ │ ├──5,529,280 B (00.57%) -- window-objects
│ │ └─────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)
│ └───1,872,144 B (00.19%) ++ treestyletab@piro.sakura.ne.jp/js-non-window/zones/zone(0x100496800)
More things worth pointing out are as follows.
- Some add-ons are identified by a name, such as Tree Style Tab.
Others are identified only by a hexadecimal identifier. You can look
in about:support to see which add-on a particular identifier belongs
to. For example, `59c81df5-4b7a-477b-912d-4e0fdf64e5f2` is
Chatzilla.
- All JavaScript memory usage for an add-on is measured separately and
shown in this sub-tree.
- For add-ons that use separate windows, such as Chatzilla, the memory
usage of those windows will show up in this sub-tree.
- For add-ons that use XUL overlays, such as AdBlock Plus, the memory
usage of those overlays will not show up in this sub-tree; it will
instead be in the non-add-on sub-trees and won't be identifiable as
being caused by the add-on.
#### Other Measurements
This section contains multiple trees, includes many that cross-cut the
measurements in the "explicit" tree. For example, in the "explicit"
tree all DOM and layout measurements are broken down by window by
window, but in "Other Measurements" those measurements are aggregated
into totals for the whole browser, as the following example shows.
26.77 MB (100.0%) -- window-objects
├──14.59 MB (54.52%) -- layout
│ ├───6.22 MB (23.24%) ── style-sets
│ ├───4.00 MB (14.95%) ── pres-shell
│ ├───1.79 MB (06.68%) ── frames
│ ├───0.89 MB (03.33%) ── style-contexts
│ ├───0.62 MB (02.33%) ── rule-nodes
│ ├───0.56 MB (02.10%) ── pres-contexts
│ ├───0.47 MB (01.75%) ── line-boxes
│ └───0.04 MB (00.14%) ── text-runs
├───6.53 MB (24.39%) ── style-sheets
├───5.59 MB (20.89%) -- dom
│ ├──3.39 MB (12.66%) ── element-nodes
│ ├──1.56 MB (05.84%) ── text-nodes
│ ├──0.54 MB (02.03%) ── other
│ └──0.10 MB (00.36%) ++ (4 tiny)
└───0.06 MB (00.21%) ── property-tables
Some of the trees in this section measure things that do not cross-cut
the measurements in the "explicit" tree, such as those in the
"preference-service" example above.
Finally, at the end of this section are individual measurements, as the
following example shows.
0.00 MB ── canvas-2d-pixels
5.38 MB ── gfx-surface-xlib
0.00 MB ── gfx-textures
0.00 MB ── gfx-tiles-waste
0 ── ghost-windows
109.22 MB ── heap-allocated
164 ── heap-chunks
1.00 MB ── heap-chunksize
114.51 MB ── heap-committed
164.00 MB ── heap-mapped
4.84% ── heap-overhead-ratio
1 ── host-object-urls
0.00 MB ── imagelib-surface-cache
5.27 MB ── js-main-runtime-temporary-peak
0 ── page-faults-hard
203,349 ── page-faults-soft
274.99 MB ── resident
251.47 MB ── resident-unique
1,103.64 MB ── vsize
Some measurements of note are as follows.
- "resident". Physical memory usage. If you want a single
measurement to summarize memory usage, this is probably the best
one.
- "vsize". Virtual memory usage. This is often much higher than any
other measurement (particularly on Mac). It only really matters on
32-bit platforms such as Win32. There is also
"vsize-max-contiguous" (not measured on all platforms, and not
shown in this example), which indicates the largest single chunk of
available virtual address space. If this number is low, it's likely
that memory allocations will fail due to lack of virtual address
space quite soon.
- Various graphics-related measurements ("gfx-*"). The measurements
taken vary between platforms. Graphics is often a source of high
memory usage, and so these measurements can be helpful for detecting
such cases.