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
β”‚   β”œβ”€β”€24.57 MB (12.80%) -- top(http://edition.cnn.com/, id=8)
β”‚   β”‚  β”œβ”€β”€20.18 MB (10.52%) -- active
β”‚   β”‚  β”‚  β”œβ”€β”€10.57 MB (05.51%) -- window(http://edition.cnn.com/)
β”‚   β”‚  β”‚  β”‚  β”œβ”€β”€β”€4.55 MB (02.37%) ++ js-compartment(http://edition.cnn.com/)
β”‚   β”‚  β”‚  β”‚  β”œβ”€β”€β”€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)
β”‚   β”œβ”€β”€15.75 MB (08.21%) ++ top(http://techcrunch.com/, id=20)
β”‚   β”œβ”€β”€12.85 MB (06.69%) ++ top(http://arstechnica.com/, id=14)
β”‚   β”œβ”€β”€β”€6.40 MB (03.33%) ++ top(chrome://browser/content/browser.xul, id=3)
β”‚   └───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 example, the β€œtop(http://edition.cnn.com/, id=8)” sub-tree represents the tab open to cnn.com, and β€œtop(chrome://browser/content/browser.xul, id=3)” represents the 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 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
β”‚   β”‚   β”‚  β”œβ”€β”€4,175,584 B (00.43%) ++ top(chrome://chatzilla/content/chatzilla.xul, id=4293)
β”‚   β”‚   β”‚  └──1,353,696 B (00.14%) ++ top(chrome://chatzilla/content/output-window.html, id=4298)
β”‚   β”‚   └─────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.