From 7bf1ebe2ca811496429af3a8208a4e16021f43cd Mon Sep 17 00:00:00 2001 From: Suvesh Moza Date: Sun, 7 Jun 2026 14:34:21 +0530 Subject: [PATCH 1/5] docs: add memory usage entry to SidebarEntry --- src/glide/browser/base/content/docs.mts | 1 + src/glide/docs/memory-usage.md | 1 + 2 files changed, 2 insertions(+) create mode 100644 src/glide/docs/memory-usage.md diff --git a/src/glide/browser/base/content/docs.mts b/src/glide/browser/base/content/docs.mts index 720900ca..ee809967 100644 --- a/src/glide/browser/base/content/docs.mts +++ b/src/glide/browser/base/content/docs.mts @@ -69,6 +69,7 @@ const SIDEBAR: SidebarEntry[] = [ { name: "Privacy", href: "privacy.html" }, { name: "Changelog", href: "changelog.html" }, { name: "Contributing", href: "contributing.html" }, + { name: "Memory Usage", href: "memory-usage.html" }, { name: "Chat", href: "chat.html" }, ]; diff --git a/src/glide/docs/memory-usage.md b/src/glide/docs/memory-usage.md new file mode 100644 index 00000000..c49c4f0b --- /dev/null +++ b/src/glide/docs/memory-usage.md @@ -0,0 +1 @@ +# Memory Usage From ba67b882e50f0605137ffd6e737642f1f373be0c Mon Sep 17 00:00:00 2001 From: Suvesh Moza Date: Sun, 7 Jun 2026 14:35:15 +0530 Subject: [PATCH 2/5] docs: add memory usage guide for about:memory --- src/glide/docs/memory-usage.md | 79 ++++++++++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) diff --git a/src/glide/docs/memory-usage.md b/src/glide/docs/memory-usage.md index c49c4f0b..d58620d6 100644 --- a/src/glide/docs/memory-usage.md +++ b/src/glide/docs/memory-usage.md @@ -1 +1,80 @@ # Memory Usage + +## Introduction + +Glide is generally expected to have slightly higher memory usage than Firefox. This is due to the additional functionality and customisation that Glide provides. This section discuss various ways to measure memory usage, how to interpret the results, and making sure Glide memory usage is within acceptable limits. + +## Tools for Measuring Memory Usage + +Since Glide is a fork of Firefox, we can use the same tools to measure memory usage. Some of the tooling rely on Firefox's memory reporting system, which is not available to Glide. + +1. [`about:memory`](#about:memory) + +## about:memory + +`about:memory` page is a powerful, built-in diagnostic tool that provides detailed measurements of Firefox’s memory usage. It allows you to view, save, load, and diff detailed measurements of Firefox’s memory usage. It provides detailed breakdowns of exactly which tabs, extensions or background processes are consuming memory and allows you to force memory garbage collection. + +To open the `about:memory` page, type `about:memory` in the address bar and press Enter. + +### Generating a memory report + +1. Use Glide the way you normally would. +2. When you're ready to capture memory usage, open the `about:memory` page. +3. Click on `Measure and save` button to generate a memory report. +4. This will open a file dialog that allows you to save the file(`.json.gz` suffix) at your desired location. + +### Loading a memory report + +On the `about:memory` page. Click `Load…` and pick a saved report file (`.json.gz` suffix). The report opens on the page so you can review it. + +>[!NOTE] +It's useful to compare before and after memory usage. To do this, you can use the `Load and diff…` button to load two different memory reports and compare the differences. + +### Interpreting memory usage + +Once you’ve generated or loaded a report, you’ll see a breakdown of where Glide’s memory is going. + +The basics + +- Sizes are shown in MB, KB, or sometimes raw bytes. Some entries are plain counts with no unit. +- The percentage in brackets shows how much of the parent row that entry uses. +- Reports are split by process (main browser, tabs, GPU, etc.). +- Measurements are shown as trees — click rows to expand or collapse them. + +```txt +51.00 MB (100.0%) -- js-main-runtime-gc-heap-committed +├──38.29 MB (75.07%) -- used +│ ├──36.18 MB (70.94%) -- gc-things +│ │ ├──17.03 MB (33.39%) ── objects +│ │ ├───5.80 MB (11.37%) ── scripts +│ │ ├───4.81 MB (09.42%) ── strings +│ │ ├───3.67 MB (07.20%) ── property-maps +│ │ ├───3.49 MB (06.84%) ── scopes +│ │ ├───0.80 MB (01.57%) ── shapes +│ │ └───0.58 MB (01.14%) ++ (6 tiny) +│ ├───1.44 MB (02.82%) ── chunk-admin +│ └───0.67 MB (01.31%) ── arena-admin +└──12.71 MB (24.93%) -- unused + ├──11.10 MB (21.77%) ── arenas + ├───1.00 MB (01.96%) ── chunks + └───0.61 MB (01.20%) ++ gc-things +``` + +### How to read a tree + +- Bottom rows(Leaf nodes) are the actual measurements. +- Parent rows are the sum of everything below them. + +### What to look for + +Each process has two main parts: + +1. Explicit allocations — memory broken down by tabs, extensions, JavaScript, images, and other subsystems. Look for top(https://…) rows to see which tabs use the most memory. +2. Other measurements — totals across the whole browser. resident is the best single number for overall RAM usage. + +You don’t need to understand every line. Focus on unusually large entries and compare reports with Load and diff… to see what changed. + +>[!TIP] +Hover over any button or measurement in about:memory for a short explanation of what it means. + +For detailed information, read the [`about:memory` Firefox docs](https://firefox-source-docs.mozilla.org/performance/memory/about_colon_memory.html). From 474efab6eb2cb6724f64bd875017ae39f956185a Mon Sep 17 00:00:00 2001 From: Suvesh Moza Date: Sun, 7 Jun 2026 15:08:24 +0530 Subject: [PATCH 3/5] lint fix --- src/glide/docs/memory-usage.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/glide/docs/memory-usage.md b/src/glide/docs/memory-usage.md index d58620d6..83e58241 100644 --- a/src/glide/docs/memory-usage.md +++ b/src/glide/docs/memory-usage.md @@ -27,8 +27,8 @@ To open the `about:memory` page, type `about:memory` in the address bar and pres On the `about:memory` page. Click `Load…` and pick a saved report file (`.json.gz` suffix). The report opens on the page so you can review it. ->[!NOTE] -It's useful to compare before and after memory usage. To do this, you can use the `Load and diff…` button to load two different memory reports and compare the differences. +> [!NOTE] +> It's useful to compare before and after memory usage. To do this, you can use the `Load and diff…` button to load two different memory reports and compare the differences. ### Interpreting memory usage @@ -74,7 +74,7 @@ Each process has two main parts: You don’t need to understand every line. Focus on unusually large entries and compare reports with Load and diff… to see what changed. ->[!TIP] -Hover over any button or measurement in about:memory for a short explanation of what it means. +> [!TIP] +> Hover over any button or measurement in `about:memory` for a short explanation of what it means. For detailed information, read the [`about:memory` Firefox docs](https://firefox-source-docs.mozilla.org/performance/memory/about_colon_memory.html). From 5330d4045905114315cf43ac0a80abeb3ce1c31e Mon Sep 17 00:00:00 2001 From: Suvesh Moza Date: Wed, 10 Jun 2026 01:24:31 +0530 Subject: [PATCH 4/5] docs: add memory usage guide for AWSY --- src/glide/docs/memory-usage.md | 85 ++++++++++++++++++++++++++++++++++ 1 file changed, 85 insertions(+) diff --git a/src/glide/docs/memory-usage.md b/src/glide/docs/memory-usage.md index 83e58241..a615a924 100644 --- a/src/glide/docs/memory-usage.md +++ b/src/glide/docs/memory-usage.md @@ -9,6 +9,7 @@ Glide is generally expected to have slightly higher memory usage than Firefox. T Since Glide is a fork of Firefox, we can use the same tools to measure memory usage. Some of the tooling rely on Firefox's memory reporting system, which is not available to Glide. 1. [`about:memory`](#about:memory) +2. [AWSY](#awsy) ## about:memory @@ -78,3 +79,87 @@ You don’t need to understand every line. Focus on unusually large entries and > Hover over any button or measurement in `about:memory` for a short explanation of what it means. For detailed information, read the [`about:memory` Firefox docs](https://firefox-source-docs.mozilla.org/performance/memory/about_colon_memory.html). + +## AWSY + +AWSY (Are We Slim Yet) is Firefox’s automated memory testing suite. It loads a set of web pages and tracks memory usage. + +To run AWSY: + +```bash +pnpm mach awsy-test +``` + +> [!NOTE] +> A Glide build is required before running AWSY tests. + +The first AWSY run also downloads the test pages, so allow extra time and make sure you have network access. To verify everything works, start with `pnpm mach awsy-test --quick` before running a full test. + +### Useful flags + +| Flag | What it does | +| ------------ | -------------------------------------------------------------------- | +| `-h` | Show all options and AWSY-specific flags | +| `--quick` | Shorter run — opens 3 pages once, with minimal waiting between steps | +| `--base` | Run base memory usage tests | +| `--headless` | Run tests in headless mode | + +When the run finishes, results are saved under `engine/obj-*/_tests/awsy/results/`. The log prints the exact path: + +```bash +0:42.79 INFO Perfherder data written to engine/.../perfherder-data.json +``` + +> [!NOTE] +> Glide is based on Firefox and uses the same AWSY tests. Mozilla tracks those results on Perfherder, but Glide can't use Perfherder. For now, we rely on the memory usage data from `perfherder-data.json` to analyze memory usage. + +### Interpreting results + +The result is a JSON file that contains the memory usage data for the run. You can open it in a text editor to view the data. + +Structure of the result file: + +```txt +{ + "framework": { "name": "awsy" }, + "suites": [ + { + "name": "Explicit Memory", + "value": 490176268, + "unit": "bytes", + "lowerIsBetter": true, + "extraOptions": ["tp6", "fission"], + "subtests": [ + { "name": "Fresh start", "value": 488051251, "unit": "bytes" }, + { "name": "After tabs open", "value": 756072339, "unit": "bytes" }, + { "name": "Tabs closed [+30s, forced GC]", "value": 339143635, "unit": "bytes" } + ] + } + ] +} +``` + +| Field | Description | +| --------------- | --------------------------------------------------------------------------- | +| `suites` | The metrics AWSY tracks (Explicit, Resident, JS, Images, Heap Unclassified) | +| `subtests` | Memory at each stage of the test | +| `value` | Summary score across all checkpoints for the suite | +| `unit` | Unit of the value field e.g. `bytes` | +| `lowerIsBetter` | `true` if lower values are better, `false` if higher values are better | +| `extraOptions` | Additional options that were used to run the test | + +#### Checkpoints + +Each suite includes the same stages as the test runs: + +| Checkpoint | What it means | +| ----------------------------- | ---------------------------------------- | +| Fresh start | Memory right after launch | +| After tabs open | After opening the test pages | +| Tabs closed [+30s, forced GC] | After closing tabs and reclaiming memory | + +The file includes more checkpoints (e.g. Fresh start [+30s], After tabs open [+30s, forced GC]). The table above covers the main ones. + +Memory should increase when tabs open and decrease after they close. If it stays high at **Tabs closed**, that may indicate a leak. + +For detailed information, read the [AWSY docs](https://firefox-source-docs.mozilla.org/testing/perfdocs/awsy.html). From cb781341af9eb286a944704130064374697e2c3c Mon Sep 17 00:00:00 2001 From: Suvesh Moza Date: Wed, 10 Jun 2026 17:12:08 +0530 Subject: [PATCH 5/5] docs: polishing memory usage --- src/glide/docs/memory-usage.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/src/glide/docs/memory-usage.md b/src/glide/docs/memory-usage.md index a615a924..60d0476b 100644 --- a/src/glide/docs/memory-usage.md +++ b/src/glide/docs/memory-usage.md @@ -2,18 +2,18 @@ ## Introduction -Glide is generally expected to have slightly higher memory usage than Firefox. This is due to the additional functionality and customisation that Glide provides. This section discuss various ways to measure memory usage, how to interpret the results, and making sure Glide memory usage is within acceptable limits. +Glide is generally expected to have slightly higher memory usage than Firefox. This is due to the additional functionality and customisation that Glide provides. This section discusses various ways to measure memory usage and how to interpret the results. ## Tools for Measuring Memory Usage -Since Glide is a fork of Firefox, we can use the same tools to measure memory usage. Some of the tooling rely on Firefox's memory reporting system, which is not available to Glide. +Since Glide is a fork of Firefox, we can use the same tools to measure memory usage. Some of the tooling relies on Firefox's memory reporting system, which is not available to Glide. 1. [`about:memory`](#about:memory) 2. [AWSY](#awsy) ## about:memory -`about:memory` page is a powerful, built-in diagnostic tool that provides detailed measurements of Firefox’s memory usage. It allows you to view, save, load, and diff detailed measurements of Firefox’s memory usage. It provides detailed breakdowns of exactly which tabs, extensions or background processes are consuming memory and allows you to force memory garbage collection. +The `about:memory` page is a powerful, built-in diagnostic tool that provides detailed measurements of Firefox’s memory usage. It allows you to view, save, load, and diff detailed measurements of Firefox’s memory usage. It provides detailed breakdowns of exactly which tabs, extensions, or background processes are consuming memory and allows you to force memory garbage collection. To open the `about:memory` page, type `about:memory` in the address bar and press Enter. @@ -21,12 +21,12 @@ To open the `about:memory` page, type `about:memory` in the address bar and pres 1. Use Glide the way you normally would. 2. When you're ready to capture memory usage, open the `about:memory` page. -3. Click on `Measure and save` button to generate a memory report. -4. This will open a file dialog that allows you to save the file(`.json.gz` suffix) at your desired location. +3. Click the `Measure and save` button to generate a memory report. +4. This will open a file dialog that allows you to save the file (`.json.gz` suffix) at your desired location. ### Loading a memory report -On the `about:memory` page. Click `Load…` and pick a saved report file (`.json.gz` suffix). The report opens on the page so you can review it. +On the `about:memory` page, click `Load…` and pick a saved report file (`.json.gz` suffix). > [!NOTE] > It's useful to compare before and after memory usage. To do this, you can use the `Load and diff…` button to load two different memory reports and compare the differences. @@ -63,7 +63,7 @@ The basics ### How to read a tree -- Bottom rows(Leaf nodes) are the actual measurements. +- Bottom rows (leaf nodes) are the actual measurements. - Parent rows are the sum of everything below them. ### What to look for @@ -71,7 +71,7 @@ The basics Each process has two main parts: 1. Explicit allocations — memory broken down by tabs, extensions, JavaScript, images, and other subsystems. Look for top(https://…) rows to see which tabs use the most memory. -2. Other measurements — totals across the whole browser. resident is the best single number for overall RAM usage. +2. Other measurements — totals across the whole browser. `resident` is the best single number for overall RAM usage. You don’t need to understand every line. Focus on unusually large entries and compare reports with Load and diff… to see what changed. @@ -111,7 +111,7 @@ When the run finishes, results are saved under `engine/obj-*/_tests/awsy/results ``` > [!NOTE] -> Glide is based on Firefox and uses the same AWSY tests. Mozilla tracks those results on Perfherder, but Glide can't use Perfherder. For now, we rely on the memory usage data from `perfherder-data.json` to analyze memory usage. +> Perfherder is a dashboard intended to allow monitoring and analysis of automated performance tests run against Mozilla products (currently Firefox and Firefox for Android). Glide is not supported on Perfherder, so we rely on the memory usage data from `perfherder-data.json` to analyse memory usage. ### Interpreting results @@ -144,7 +144,7 @@ Structure of the result file: | `suites` | The metrics AWSY tracks (Explicit, Resident, JS, Images, Heap Unclassified) | | `subtests` | Memory at each stage of the test | | `value` | Summary score across all checkpoints for the suite | -| `unit` | Unit of the value field e.g. `bytes` | +| `unit` | Unit of the value field, e.g. `bytes` | | `lowerIsBetter` | `true` if lower values are better, `false` if higher values are better | | `extraOptions` | Additional options that were used to run the test |