profile-viewer 0.0.0

data/dist/docs/gitpod.md

@@ -0,0 +1,39 @@
+# Setting up profiler on gitpod
+
+Instead of configuring a local setup, you can also use [gitpod](https://www.gitpod.io/), an online continuous development environment  with minimum setup.
+Click the link below. An automatic workspace will be created.
+
+[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/firefox-devtools/profiler)
+
+## Authorize with github
+
+If you are using gitpod for the first time, you will have to authorize access to your GitHub account.This is necessary so you can access your data from within Gitpod.
+
+To authorize access, click your avatar/profile picture at the top right hand section of the setup. A dropdown menu will be displayed. In the dropdown menu, click `Open Access Control`. It will open Access Control page from where you can check the checkboxes and click update. 
+
+## Open the profiler UI in your web browser
+
+A popup box, `Open Ports View`, also appears at the bottom right hand section of the setup with the message `A service is available on port 4242`. You can click `Open Browser` which will open profiler UI, [profiler.firefox.com](https://profiler.firefox.com/), for your setup in a separate tab. If you have closed `Open Ports View`, you can display it by clicking `PORTS` at the right hand section of the bottom bar.
+
+## Load custom profiles
+
+If you want to load profiles for development, you can follow the steps described in [Loading in profiles for development](../CONTRIBUTING.md#loading-in-profiles-for-development) section.
+
+## Advanced usage
+
+As an alternative to following the link above, you can also login using your gitHub account and then follow the sets below.
+
+- Change the URL of your browser to the respository, pull request or issue you want to open on gitpod e.g. for the [profiler project](https://github.com/firefox-devtools/profiler), URL of the upstream repository is `https://github.com/firefox-devtools/profiler`. You can also use the forked repository if you wish to start contributing to the project. 
+- Prefix the URL in the address bar of your browser with `gitpod.io/#` e.g. `https://github.com/firefox-devtools/profiler` becomes `https://gitpod.io/#https://github.com/firefox-devtools/profiler`.
+- Gitpod will then  launch a workspace for you and clone the repository, branch, commit or pull request depending on the URL in the first step.
+
+## Using the gitpod browser extension (optional)
+
+You can also install the [gitpod browser extension](https://addons.mozilla.org/en-GB/firefox/addon/gitpod/) if you wish instead of prefixing the URL of your browser with `gitpod.io/#` as described in the first step of **Advanced usage** section.
+
+The browser extension, if you choose to install, will add a button on each repository on Github. Clicking the button will trigger creation of an automatic gitpod setup. 
+
+
+
+
+

data/dist/docs/guide-android-profiling.md

@@ -0,0 +1,46 @@
+# Perf Profiling on Android
+
+Android has an application [`simpleperf`](https://android.googlesource.com/platform/system/extras/+/master/simpleperf/doc/README.md) which can profile any Android process. Simpleperf is mostly a drop-in replacement for the Linux `perf` tool.
+
+Firefox Profiler can visualise these `simpleperf` profiles, augmenting the viewers that ship with `simpleperf` (e.g. [`report_html.py`](https://android.googlesource.com/platform/system/extras/+/master/simpleperf/doc/scripts_reference.md#report_html_py)).
+
+For specifically profiling Firefox for Android, see [Remote Profiling Firefox for Android](guide-remote-profiling.md).
+
+## Install simpleperf
+
+Install the latest version of `simpleperf`, which can output profiles for Firefox Profiler:
+
+```bash
+git clone https://android.googlesource.com/platform/system/extras
+cd extras/simpleperf
+```
+
+## Usage instructions
+
+### Step 1: Capture the profile
+
+Record a profile following [the simpleperf instructions](https://android.googlesource.com/platform/system/extras/+/master/simpleperf/doc/scripts_reference.md#app_profiler_py), e.g. to profile the startup of `MyActivity` within app `com.example.myapplication`, run:
+
+```bash
+./app_profiler.py -p com.example.myapplication -a .MyActivity
+```
+
+This records the profile into a `perf.data` file, and pulls it to your host.
+
+### Step 2: Convert the profile
+
+Then convert to a Gecko Profile (Firefox Profiler) format, using [`gecko_profile_generator.py`](https://android.googlesource.com/platform/system/extras/+/master/simpleperf/doc/scripts_reference.md#gecko_profile_generator_py):
+
+```bash
+./gecko_profile_generator.py | gzip > profile.json.gz
+```
+
+`gecko_profile_generator.py` takes the `perf.data` file that was written before as its implicit input.
+
+### Step 3: View the profile in profiler.firefox.com
+
+Load `profile.json.gz` into [profiler.firefox.com](https://profiler.firefox.com), using drag-and-drop or "Load a profile from file".
+
+## See also
+
+The tips in [Perf Profiling for Linux](guide-perf-profiling.md).

data/dist/docs/guide-filtering-call-trees.md

@@ -0,0 +1,87 @@
+# Filtering call trees
+
+Call trees can grow to be quite large, especially when profiling a browser engine. Typically, only portions of the tree are actually useful for any given analysis. The Firefox Profiler provides a variety of tools for filtering and transforming a tree in order to only show the relevant parts. It's important when filtering to know the difference between filtering out samples and transforming stacks. When removing samples, the tree will essentially be the same shape, but may be missing certain branches that were only present in certain samples. When transforming the tree, the shape of the sample's stacks will be modified. Samples will only be dropped if their stacks are completely removed during the transformation operation.
+
+The following are the different types of filtering operations that are supported.
+
+| Filter type | Description |
+| ----------- | ----------- |
+| Search filter | Drop samples that do not match a text string. |
+| Implementation filter | Restrict stacks to an implementation—native (C++) stacks, or to JavaScript stacks. |
+| Invert call stack | Flip the sample's stacks upside down and build a new call tree. |
+| Transforms | Modify the shape of the call tree according to some operation. Typically, this only modifies the stacks. |
+
+## Search filter
+
+![A screenshot of the search box](./images/search-2022-06-16.png)
+
+Searching will exclude samples that do not match a search string. The search filter looks at every function in the sample's stack. If the function's name, resource, or URL match, then the sample will be retained; otherwise, it will be filtered out. Multiple search terms can be added, as long as they are separated by commas.
+
+![The image demonstrates the search filter. On the left is a call tree that has all stacks, and on the right is the filtered call tree that does not have any stacks that do not have the function C.](./images/filter-search.svg)
+
+The above diagram is reproduced in the profile below:
+
+* Before searching: [https://perfht.ml/2I3SMsR](https://perfht.ml/2I3SMsR)
+* After searching: [https://perfht.ml/2rbcj0N](https://perfht.ml/2rbcj0N)
+
+The following are some ideas on how to use search terms:
+
+ * `js::` - Filter for a C++ namespace.
+ * `www.example.com` - Filter for a domain name.
+ * `www.example.com/assets/scripts.js` - Filter for a single script.
+
+## Implementation filter
+
+![A screenshot of the implementation filter dropdown.](./images/implementation-2022-06-16.png)
+
+The implementation filter is useful for narrowing down the call tree to a subset of stack types. For instance, it can be useful to only show native stacks (C++ and Rust) or to only show JavaScript stacks.
+
+The following graphic demonstrates how it can be useful to filter to only JavaScript stacks.
+
+![This graphic shows going from a combination of mixed native stacks and JavaScript stacks to only JavaScript stacks. The shape JavaScript stacks are interleaved on the mixed graph, but form a single non-branching tree in the JavaScript only version.](./images/implementation-filter.svg)
+
+Before the implementation filter, the call tree contains both C++ JavaScript internals, as well as the JavaScript stacks. This interleaving could be useful when diagnosing how the JS engine is optimizing code, but for normal JS performance, profiling this could be confusing to find hot JS functions. When the native stacks are removed, the call tree that is generated is much more sensible for representing the execution of JavaScript code.
+
+The implementation filter will modify the shape of stacks and generate a completely new call tree. If any of the filtered stacks in a sample are empty (for instance filtering on JavaScript when there are only C++ stacks), then those samples with empty stacks will be dropped from the analysis.
+
+## Invert call stack
+
+![A screenshot of the "Invert call stacks" checkbox.](./images/invert-2022-06-16.png)
+
+Inverting the call stacks of samples will produce an entirely new call tree. All of the self time will be at the roots of the call tree. The implications to the shape of the call tree may be surprising, but consider the following graphics.
+
+![An image showing samples on the left and the call tree on the right. This is before the invert operation.](./images/invert-before.svg)
+
+In this profile, for the sake of brevity, there are only 3 samples that were collected 1ms apart. In most uninverted call trees, there is only one root node. In this case, `A` calls `B` and it's not until the third stack frames where the calls diverge to function `X` and function `C`. The call tree on the right is what is produced from these samples. Now consider inverting all of the stacks in the samples.
+
+![An image showing samples on the left and the call tree on the right. This is after the invert operation.](./images/invert-after.svg)
+
+Previously, the stacks `X -> Y -> Z` were each at different levels. However, in the inverted view, the stacks are now at the same level. When the call tree is created from these samples, there are now two different roots, starting from the function `Z` and the function `E`. The inversion made the `Z -> Y -> X` portions of the stacks fall into the same level.
+
+Inversion is most useful in surfacing the functions where time is actually being spent. The trees are typically much larger and noisier than uninverted call trees.
+
+## Transforms
+
+Call tree transforms provide a finer grain control over how to modify the call tree. They modify the stack in different operations. They can operate at individual call nodes on the tree, or across the entire tree for a given function. Different programs use different terms to describe these operations, but the Firefox Profiler has defined certain operations.
+
+![A screenshot of the transforms in the contextmenu.](./images/transforms-2022-06-16.png)
+
+### Merge
+
+Merging takes a call node and removes it from the call tree. Any self time for that node is then charged to its parent node. This can be done for a single call node, or for all functions in the tree. This type of operation can be useful for modifying the shape of the tree and removing unhelpful functions from the call tree.
+
+### Focus
+
+Focusing on a function or call node removes all of the ancestor call nodes—the children call nodes remain. If a stack does not contain that function or node, then it is removed. This effectively focuses on a subtree or a set of subtrees on the call tree.
+
+### Focus on Category
+
+Focusing on the nodes that belong to the same category as the selected node, thereby merging all nodes that belong to another category.
+
+### Collapse
+
+Collapsing functions is an operation that takes multiple call nodes and combines them all together into a new single call node. This can be done for an entire subtree, in order to reduce the amount of nodes in the tree. This can also be done for contiguous call nodes. For example, it can be useful to collapse functions that are all part of some library or call nodes that are recursing.
+
+### Drop
+
+Dropping is used to mean removing samples, but not changing any properties of the stacks. This could be useful for dropping functions that are prevalent like idle functions, but that gets in the way of analysis.

data/dist/docs/guide-getting-started.md

@@ -0,0 +1,115 @@
+# Getting Started
+
+This page is an overview of the general process of capturing a profile.
+
+## Access the Firefox Profiler controls
+
+The Firefox Profiler can be used with 2 entry points: either from the popup, or
+from the devtools panel.
+
+?> We recommend using the popup so that the overhead
+caused by the other devtools is avoided.
+
+### Enable the popup
+
+The simplest way to enable the popup is going to https://profiler.firefox.com
+and clicking the big button `Enable Firefox Profiler Menu Button` in the page.
+
+![A screenshot of the profiler website homepage highlighting the button](images/getting-started-enable-popup.png)
+
+You can also drag and drop the icon from the toolbar customization
+interface.
+
+### Open the popup
+
+You open the popup by clicking the small arrow on the side of the profiler icon.
+
+![A screenshot of the profiler popup](images/getting-started-popup.png)
+
+There you can change the preset as well as access the advanced settings.
+
+?> We
+suggest using the preset `Firefox` (also called `Nightly` if running in the
+nightly version of Firefox) if you want to profile the full browser (for
+example to [report a performance problem in Firefox](https://firefox-source-docs.mozilla.org/performance/reporting_a_performance_problem.html)),
+and `Web Developer` if you want to profile a web site.
+
+### Using the Devtools panel
+
+The same settings are available in the devtools panel.
+
+![A screenshot of the Devtools performance panel](images/getting-started-devtools-panel.png)
+
+!> As explained above, when opening the Devtools toolbox there's an
+overhead, due to additional open panels. We try to maintain a minimal overhead,
+but you need to keep this into account when looking at profiles that were
+captured from this panel.
+
+## Capture a profile
+
+### Using the popup or the devtools panel
+
+[A video showing how to use the profiler popup](images/getting-started-use-popup.webm ':include :type=video controls')
+
+You can use the popup from the icon, or similarly the devtools panel, by
+clicking on `Start Recording`, then `Capture`. Then the profiler user interface
+will open to show the captured data.
+
+Note that the profiler user interface is an external web page, however it's
+cached locally the first time you access it. This means you'll need a network
+connection to download it the first time you use it. If you have a network
+connection in later uses and a new version is available, the UI will offer to
+switch to the new version.
+
+It's also important to know that the data stays local to your computer until you
+upload it (see below).
+
+### Using the profiler button
+
+It's possible to click on the button to start the profiler with current
+settings. Then click it again to capture the profile and the open the profiler
+UI.
+
+[A video showing how to use the profiler icon](images/getting-started-use-icon.webm ':include :type=video controls')
+
+### Using keyboard shortcuts
+
+The following keyboard shortcuts are available:
+
+* `Ctrl + Shift + 1`: start the profiler, or stop and discard the data if it's already running.
+* `Ctrl + Shift + 2`: capture the profile from the currently running session. It
+  has no effect if the profiler isn't running.
+
+## Share a profile
+
+![A screenshot highlighting the toolbar's upload profile button.](images/getting-started-upload.png)
+
+One of the most powerful and useful features of the Firefox Profiler is the ability to upload and share profiles. The first step is to hit the *Upload Local Profile* button. You'll be able to exclude some information before uploading. Then the profile will be uploaded to an online storage. This profile can then be shared in online chat, emails, and bug reports. Note that anybody that has the link will be able to access the uploaded data, as it's not protected otherwise.
+
+The current view and all of the filters applied to the profile will be encoded into the URL. After initially sharing the profile, a *Permalink* button will be added, that can then be used to provide a handy shortened URL to the current view.
+
+[A video showing how to upload a profile and how to get the permalink](images/getting-started-upload-permalink.webm ':include :type=video controls')
+
+?> Profiles can also be saved to file, although the current view into the UI will not be saved. The file can be reloaded through the [profiler.firefox.com](https://profiler.firefox.com) interface by either drag and drop, or the file upload interface.
+
+## Delete an uploaded profile
+
+After uploading a profile, you can delete it from the `Profile info` panel.
+
+![A screenshot showing the delete button in the profile info panel](images/getting-started-delete-profile.png)
+
+You can also go to the [Uploaded Recordings page](/uploaded-recordings/ ':ignore') to list
+all profiles you uploaded and delete them. Note that this list is only stored
+locally in your Firefox, and for this reason you can delete only profiles that
+you uploaded from the same browser instance.
+
+![A screenshot showing the list of uploaded profiles](images/getting-started-list-uploaded-profiles.png)
+
+## Name a profile
+
+![A screenshot highlighting the location for the name of a profile](images/getting-started-naming-profiles.png)
+
+It's possible to name a profile so that it's conveniently findable later by
+searching in the address bar. The name is part of the URL you'll share to others,
+but otherwise isn't stored in the profile data.
+

data/dist/docs/guide-perf-profiling.md

@@ -0,0 +1,76 @@
+# Profiling with Linux perf
+
+Linux has a native profiler called 'perf' that can profile any application. This profiler has a built-in profile viewer in the form of the `perf report` command, but you may not like its UI.
+
+[The Firefox Profiler](https://profiler.firefox.com/) provides an alternative UI for these profiles; it knows how to display profiles from perf.
+
+(Importing other profile sources is being investigated, such as in [issue #1138](https://github.com/firefox-devtools/profiler/issues/1138), and [issue #1553](https://github.com/firefox-devtools/profiler/issues/1553).)
+
+There are three major differences between the Gecko profiler and perf:
+
+ 1. The Gecko profiler can only profile Gecko. Perf can profile any process on the system.
+ 2. The Gecko profiler samples at a fixed rate based on wall-clock time. Perf samples based on elapsed CPU time per thread.
+ 3. The Gecko profiler only samples a small set of threads by default. Perf samples all threads of the given process or process tree.
+
+As a consequence of point 2, perf has far lower overhead than the Gecko Profiler when profiling many threads: perf only takes a sample whenever a thread is running, whereas the Gecko profiler will keep sampling all profiled threads at a fixed rate even when those threads are idle.
+
+## Usage instructions
+
+(This assumes you've installed perf.)
+
+There are three steps to obtaining a perf profile and loading it in the Firefox Profiler:
+
+ 1. Capture a profile with perf.
+ 2. Convert it into a text form.
+ 3. Load the text file in [profiler.firefox.com](https://profiler.firefox.com).
+
+### Step 1: Capture the profile
+
+You can attach perf to an existing (running) process, or you can launch a new process from it and profile it from the start, including the entire process tree launched from it.
+
+To attach to an existing process with PID `<pid>`, use:
+
+```bash
+perf record -g -F 999 -p <pid>
+# Stop with Ctrl+C once you've collected enough
+```
+
+To launch a new process under the profiler, use
+
+```bash
+perf record -g -F 999 program options
+# Stop with Ctrl+C once you've collected enough
+```
+
+For Firefox, this would be:
+
+```bash
+perf record -g -F 999 firefox -P profile -no-remote
+```
+
+The `perf record` command writes the profile into a file called `perf.data` in the current directory.
+
+### Step 2: Convert the profile
+
+After exiting perf, convert the perf data into something the Firefox Profiler can read:
+
+```bash
+perf script -F +pid > /tmp/test.perf
+```
+
+The `perf script` command takes the `perf.data` file that was written by the `perf record` command as its implicit input.
+
+### Step 3: View the profile in profiler.firefox.com
+
+You can now load the .perf file into [profiler.firefox.com](https://profiler.firefox.com): tell the Firefox Profiler to open the file and it should be auto-identified and loaded.
+Note that there will be no markers and no categories.  Many stack frames will say `[unknown]`.  There will be no JavaScript stacks, unless you do extra work as described below.  Symbols might be mangled.
+
+## Analyzing perf traces and tips
+
+Remember that 'perf' only records a sample if the thread is executing; samples are omitted if the thread is sleeping.  This means in many cases there will be gaps between samples, often large ones.  You probably want to switch from "Categories" to "Stack height" mode in the top left corner in order to see when samples were taken across the different threads.
+
+Perf sometimes has trouble walking the stack, and you'll get mis-rooted subtrees at the top level.
+
+Perf can include kernel callstacks in the profile. They might show up as `[unknown]` frames from the `[kernel.kallsyms]` library. Setting `/proc/sys/kernel/perf_event_paranoid` to 1 or less can potentially help with this.
+
+If you need JavaScript stacks, you can build Firefox with `--enable-perf` and then run it with the env variable `IONPERF=func`. This will allow some of the `[unknown]` frames to be resolved to JS source files/functions. Doing so does have some impact on the recorded profile, but it's generally small.

data/dist/docs/guide-profiler-fundamentals.md

@@ -0,0 +1,33 @@
+# Profiler Fundamentals
+
+When profiling code, there are two primary sources of information—stack: samples and markers.
+
+## Samples
+
+For samples, the profiler stops the execution of the profiled code at a fixed rate, for example, every 1ms and records relevant information like the current stack. These samples are aggregated together and provide a statistical look into the execution of the program. There is no guarantee that all of the code that is running will be sampled, but with enough samples, it provides a good look into where time was spent while running the targeted code.
+
+### Statistical significance and the overhead of samples
+
+There are two ways to get more samples to provide more statistical significance. The first way is to increase the sampling rate. The sampling rate can be changed by tweaking the sampling interval in about:profiling.
+
+![A picture of the UI in about:profiling to adjust the sampling interval.](images/interval-2020-05.png)
+
+For example, the sampling rate could be increased by changing the interval from 1ms to 0.1ms to collect 10 times more samples. This makes it possible to run the profiled program fewer times, but comes with a trade-off. When the profiler is collecting more samples, the profiler needs to do more work to collect these samples and thus, there is more overhead from the profiler. This can skew the results by measuring more of the overhead of profiling, compared to the actual program that is being run.
+
+The other way to increase the number of samples is to run the code more often and not increase the sampling rate. For instance, to profile a mouse click event, one click event would not be sampled much with a frequency of 1ms. However, performing the click event multiple times over the course of a minute would increase the amount of samples collected, without introducing additional overhead from the profiler.
+
+## Markers
+
+Samples provide a view into the profiled program that is based on probability. Over time, with enough samples, the analysis will most likely contain samples of the code that was run. However, it can miss important events that happen quickly.
+
+Markers provide a view into the executing code that does not miss anything. Markers are small pieces of data that are collected every time a specific event happens. For instance, when clicking the mouse, the C++ implementation could call a function that collects the current mouse coordinates and timestamp of the event. This information would then be stored in the profiler's buffer. This mouse click could happen very quickly and most likely it would be missed by the profiler if not for the marker.
+
+Samples are a general-purpose solution to understand what is going on in the code, while markers provide a specific opinionated view. A very fast mouse event will have a high probability of being missed on a low sampling rate, but will always be collected as a marker. The problem with markers is that they must be hand-instrumented in the code and kept up to date. They are a great way for engineers with domain-specific information to surface more information about how a program is executing. The marker information can be cross-referenced with the samples to provide a better understanding of what code is doing.
+
+Markers can be used for stack-like purposes as well. For instance, when working with React or any front-end component system, the JavaScript stacks will all be framework internals. The internals are resolving work requested by the components, but they do not directly map to the code that the component author wrote. To get around this, components could emit markers with start and end timestamps for when they are updated. These markers can then be turned into a chart that shows how components are rendering according to a hierarchy and how much time is being spent updating them. This labeled information can then be cross referenced with the statistically collected samples.
+
+### Overhead and trade-offs with markers
+
+While markers can provide very detailed information about a given system, they do come with some trade-offs. Unlike samples which are a generalized solution, each type of marker must be written and maintained as lines of code in the source. This requires a domain-expert's time and bandwidth to create. In addition, if this information is not correctly maintained, it could potentially be out of date and provide faulty information.
+
+The process of collecting samples has a convenient knob to tune the overhead—the sample rate. Markers will be collected every time an event happens. This is really nice for interesting parts of the profiled program, but can start to fall apart if overused. For instance, if every single part of the JavaScript engine was instrumented to collect a marker for how it executed, this would quickly turn into gigabytes of memory that would be slow to process, difficult to store and probably skew the results with a large amount of overhead.

data/dist/docs/guide-profiling-android-directly-on-device.md

@@ -0,0 +1,34 @@
+# Profiling Firefox for Android directly on device
+
+The Firefox Profiler can be used without the remote debugging option. It offers a little less flexibility (can't edit the options and the profile is 
+automatically uploaded). However, it does allow you to capture a profile without the need of a PC.
+
+## Setup
+
+### Pick a build to profile
+We recommend profiling a Firefox build from any release channel (i.e. not debug), whether downloaded from Google Play, Taskcluster, or built locally.
+
+### Enable secret settings on the mobile device
+
+To enable secret settings, follow these steps:
+
+ - Click on the [three dot icon next to the URL bar](./images/about-url.png)
+ - Select the ["Settings" option](./images/settings-menu.png).
+ - Scroll to the bottom of the settings page and select the "About Firefox"
+ - Click the "Firefox" logo 5 times. [A toast should appear at the bottom of your screen with the number of click left before unlocking the secret menu](./images/secret-menu-toast.png).
+ - Go back to the "Settings" screen and scroll to the bottom where you should see the ["Start Profiler" option](./images/start-profiler.png).
+
+## Usage instructions
+
+### To start the profiler
+
+ - Click on "Start Profiler" and you should see a dialogue appear.
+ - Choose one of the four options that matches the closest to what you're trying to profile.
+ - Click "Start Profiler" and a toast should appear with the "Profiler started" message.
+
+### To stop the profiler
+
+  - Go back to the Settings screen
+  - Scroll to the bottom and you should see a "Stop profiler" option has replaced the "Start Profiler" one.
+  - After you click it, you should see a dialogue with a warning regarding the information contained in the profile.
+  - Once stopped, the URL for the profile that finished recording will be copied to your clipboard which you can then use to share.

data/dist/docs/guide-profiling-firefox-android.md

@@ -0,0 +1,7 @@
+# Profiling Firefox for Android
+
+Two options are possible:
+
+* [Remote Profiling Firefox for Android](./guide-remote-profiling.md) provides the most options but can be cumbersome to set up;
+* [Profiling Firefox for Android directly on the device](./guide-profiling-android-directly-on-device.md) has fewer options but should be easier to set up.
+

data/dist/docs/guide-remote-profiling.md

@@ -0,0 +1,90 @@
+# Remote Profiling Firefox for Android
+
+You can use the Firefox Profiler to investigate performance issues on Android, not only Windows, macOS and Linux.
+
+In order to do so, you need both your phone with the mobile Gecko-based browser, and a machine running Firefox Desktop. You also need a USB connection between the two devices. Then you can use [about:debugging](https://developer.mozilla.org/en-US/docs/Tools/about:debugging) in Firefox Desktop to connect to the phone and control profiling from there. The result will be shown in Firefox Desktop.
+
+[In this 1 minute video demonstration](https://www.youtube.com/watch?v=TxAlQBv6-yg) you can see the few steps needed to capture a profile from Fenix. For additional details and troubleshooting info, see below.
+
+## Setup
+
+### Pick a build to profile
+We recommend profiling a Firefox build from any release channel (i.e. not debug), whether downloaded from Google Play, Taskcluster, or built locally. Alternatively, you may wish to profile GeckoView-example. For more details, see the [Which mobile browser? section below](#which-mobile-browser).
+
+### Enable remote debugging on the mobile device
+
+Your device needs to be connected to your computer before recording. You also need to have your Gecko-based Android app (such as Firefox Preview) running and set up for remote debugging via USB. This usually requires **two** settings:
+
+ - Android itself needs to be configured to allow remote debugging over USB. This can be done in the system settings after entering "developer mode", which can be done by tapping on the Android build number repeatedly. See [the Android documentation](https://developer.android.com/studio/debug/dev-options.html) for details.
+ - The app needs to be configured to allow remote debugging. There's usually a checkbox in the app's settings menu for that.
+
+### Prepare `about:debugging`
+
+To profile a Gecko Android build, you have to connect it to a Desktop Firefox browser. Please use [Firefox Nightly](https://www.mozilla.org/en-US/firefox/channel/desktop/#nightly) for this.
+
+* Open the `about:debugging` page in Desktop Firefox by typing `about:debugging` in the URL bar, or via Tools > Web Developer > Remote Debugging.
+* If necessary, click "Enable USB Devices".
+
+## Recording
+
+On `about:debugging`, find your device/browser in the sidebar on the left and connect to it. If your device is not listed, check the following things:
+
+ - Is USB debugging enabled in the Android system preferences?
+ - Is the browser you want to profile running? Try navigating to a page in order to make sure that Gecko has been initialized.
+ - Is remote debugging enabled in the browser on the phone? If you've recently pushed a new version of this app to your phone, the settings from the previous version may have been lost, so you may need to enable the pref again.
+ - Is your phone's screen unlocked?
+ - Double-check your cable connections.
+ - If you have `adb` on your Desktop machine, check if `adb devices` sees the phone. If not, try to fix that first.
+
+Once you have connected to the phone browser successfully, read on.
+
+Click the sidebar item for your phone / browser. Then, in the main section of the page, click the *Profile Performance* button.
+
+Make any necessary adjustments in the presented options, like threads to sample or profiler features to enable, and then click *Start recording*. Perform the interactions you intend to profile on the Android device and then click *Capture Recording* in the Performance panel. A new tab will open in [https://profiler.firefox.com/](https://profiler.firefox.com/) with the collected profile ready for inspection.
+
+![A screenshot of about:debugging after connecting](./images/about-debugging-remote.png)
+![A screenshot of about:debugging after clicking Profile Performance](./images/about-debugging-remote-profiling-panel.png)
+
+## Symbols and symbol sources
+
+If you've been profiling a browser from the Google Play Store, your profile should contain fully symbolicated C++ call stacks at least for libxul.so. If it doesn't, check the following:
+
+ - Are you profiling a "shippable" GeckoView build? A common mistake is to profile a regular "opt" build from treeherder, i.e. one that was not compiled with the "shippable" configuration. Unfortunately, those regular treeherder builds do not upload symbol information to the Mozilla symbol server. Please use a different build in that case.
+ - Are you profiling a build from the tryserver or a local build? Read on below for how to obtain symbol information in those cases.
+
+## Which mobile browser?
+
+(The following is true as of August 2021.)
+
+You probably want to profile [Firefox Nightly](https://play.google.com/store/apps/details?id=org.mozilla.fenix) from the Google Play Store. Read on for more details, or skip to the next section if you already know exactly which browser you want to profile.
+
+Mozilla's current development efforts on mobile are focused on GeckoView and Firefox for Android (["Fenix"](https://github.com/mozilla-mobile/fenix)). You can [install Firefox Nightly from the Google Play Store](https://play.google.com/store/apps/details?id=org.mozilla.fenix), or you can download the APK ([32 bit](https://firefox-ci-tc.services.mozilla.com/api/index/v1/task/mobile.v3.firefox-android.apks.fenix-nightly.latest.armeabi-v7a/artifacts/public/build/fenix/armeabi-v7a/target.apk), [64 bit](https://firefox-ci-tc.services.mozilla.com/api/index/v1/task/mobile.v3.firefox-android.apks.fenix-nightly.latest.arm64-v8a/artifacts/public/build/fenix/arm64-v8a/target.apk)). Firefox Nightly is the preferred profiling target. It uses a [recent](https://github.com/mozilla-mobile/android-components/blob/master/buildSrc/src/main/java/Gecko.kt#L9) version of Gecko and updates frequently and automatically.
+
+The other reasonable profiling target is something called ["GeckoView-example"](https://searchfox.org/mozilla-central/source/mobile/android/geckoview_example). This is a small Android app that isn't much more than a demo of GeckoView and doesn't have much UI. You can download the most recent GeckoView-example.apk ([32 bit](https://firefox-ci-tc.services.mozilla.com/api/index/v1/task/gecko.v2.mozilla-central.shippable.latest.mobile.android-arm-opt/artifacts/public/build/geckoview_example.apk), [64 bit](https://firefox-ci-tc.services.mozilla.com/api/index/v1/task/gecko.v2.mozilla-central.shippable.latest.mobile.android-aarch64-opt/artifacts/public/build/geckoview_example.apk)) from TaskCluster, or you can compile Gecko yourself and [push Geckoview-example to the phone using `mach run`](https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/for-gecko-engineers.html#geckoview-example-app) or [using Android Studio](https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/geckoview-quick-start.html#build-using-android-studio). In fact, if you're working on Gecko, this is the most low-friction workflow if you want to quickly verify the performance impact of your changes on Android.
+
+In general, profiling Fenix is preferable over profiling GeckoView-example because you'll be able to see impact from Fenix-specific performance issues. If you're compiling and modifying Gecko locally, you can create a version of Fenix that uses your custom Gecko [by making a small tweak to a `local.properties` file](https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/geckoview-quick-start.html#dependency-substiting-your-local-geckoview-into-a-mozilla-project) in your local clone of [the Fenix repository](https://github.com/mozilla-mobile/fenix).
+
+You can also profile local builds or Try builds. This requires some extra steps which are described further down in this document.
+
+## Startup profiling
+
+To profile the startup of GeckoView or Firefox for Android, please look at [the
+additional guide on the dedicated page](./guide-startup-shutdown#firefox-for-android).
+
+### Try builds
+
+If you want to profile an Android build that the tryserver created for you, you have to kick off a "Sym" job (run time: about 3 minutes) on treeherder: Using treeherder's *Add new jobs* UI, schedule a "Sym" job for each platform whose "B" job you want symbols for. These jobs gather symbol information from the corresponding build job and upload it to the Mozilla symbol server so that the Firefox Profiler can use it.
+
+### Local builds
+
+If you've compiled an Android Gecko build locally, and want to profile it, you have to jump through one small extra hoop: Before profiling, in the *Profile Performance* panel in `about:debugging`, go to *Settings*, scroll down to the *Local build* section and add your Android build's objdir to the list. Then profile as usual, and you should be getting full symbol information.
+
+## Tips
+
+* Enable the "Screenshots" feature before profiling. Then you can see what's going on on the screen during your profiling run, which can be extremely helpful.
+* Limit the duration of the profiling run. This will cut down on the profile size, which will reduce the time you have to wait when you click "Capture Profile". Smaller profiles are also less likely to crash the app due to memory limitations.
+* Avoid clicking on any of the open tabs that are listed on the `about:debugging` page. Clicking on a tab will open a toolbox and add overhead by initializing content-side devtools code. For that reason, the profiling panel is separate from the toolbox.
+* Choose a more relaxed profiling interval in order to reduce profiling overhead. 2ms to 5ms work well. This will give you less data but more accurate timings.
+* To get maximally-realistic timings, consider using the "No Periodic Sampling" feature: This will cut down profiling overhead dramatically, but you won't have any stacks. If your workload is reproducible enough, you can take two profiles: one with stacks and one without. Then you can take your timings from the former and your information from the latter.
+* Startup profiling reveals some overhead caused by devtools code that is only run when remote debugging is enabled. In order to see what startup does when remote debugging is turned off, you can deactivate remote debugging before you quit the app, and re-activate it after startup.
+* If the recording doesn't start after clicking the start button, or if the button is inactive or in an otherwise confused state, it might be necessary to disconnect and reconnect to the phone to reset some state.

data/dist/docs/guide-removing-profiler.md

@@ -0,0 +1,4 @@
+# Removing profiler
+To remove the Firefox Profiler from the toolbar, right-click on the Profiler icon and choose "Remove from Toolbar" in the context menu.
+
+The Firefox Profiler is built in Firefox. The icon is only a menu button (that you can remove). There is no need and no way to remove the whole Firefox Profiler.

data/dist/docs/guide-stack-samples-and-call-trees.md

@@ -0,0 +1,57 @@
+# Stack Samples and Call Trees
+
+While samples can collect any type of arbitrary information, arguably the most useful is the call stack of the currently executing program. This document explores how to aggregate and analyze these stacks. It may be helpful to have first read the [profiler fundamentals](./guide-profiler-fundamentals) document for some of the theory behind how sampling works, and how the samples differ from markers.
+
+## Stacks gathered over time
+
+![This image shows contiguous stacks, and how they are sampled over time. It fades out as it goes left to right to indicate that samples are gathered for long periods of time. The stacks are labeled by 1 millisecond intervals. The stacks are labeled by functions that are single capital letters, ranged A to H.](./images/samples.svg)
+
+These examples assume the profiler is configured to collect samples every 1 millisecond. As the targeted code runs, the profiler stops the program execution, and samples the stack. Often, the roots of the stacks will look very similar, but then the leaves will vary wildly as the code calls into different parts of the program. If a program is profiled for 3 seconds, at the rate of 1 millisecond per sample, then there would be 3000 samples. It is not practical to view samples individually, so these samples will be aggregated together to provide a more useful look into profile execution. This aggregated data structure is the call tree.
+
+## A simplified call tree
+
+![This image shows stacks going from left to right. They are at 1 millisecond intervals. Each stack is composed of the function, A, B, C, and doWork. There are 5 samples](./images/simple-stacks.svg)
+
+<!--alex ignore simple-->
+This example creates a fairly contrived and simple example. `A` calls `B`, which calls `C`, then calls `doWork`. `A`, `B`, `C` are very quick to run, and the profiler never directly samples them. However, `doWork` is sampled 5 times. An aggregation of this profile would smush everything into one graph.
+
+![This graphic demonstrates a call tree. It is a chart of the stacks A, B, C, and doWork, each connected by an arrow going from the root A to the leaf doWork. The running time of all the samples is 5ms. The self time is 0ms, except for doWork, which has a self time of 5ms.](./images/simple-call-tree.svg)
+
+This graph is a simplified call tree. Notice that there is no branching, as the samples that are aggregated all share the same stacks. The profiler only samples the function `doWork`, but the rest of the stack is in the report. This means that the running time for every node on the call tree is 5ms. (From here on out a node on a call tree will be referred to as a "call node"). However, since only the `doWork` function was observed, it is the only node to have self time of 5ms, as it was itself observed to be running. `A`, `B`, `C` all have a self time of 0ms.
+
+## Self time in the call tree
+
+Self time does not actually need to be found at the leaves of the call tree. In fact it can be located at any node in the tree. Self time is where the profiler observed a function running. Imagine in the previous example that the function `B` also required a bit of time to run.
+
+![This image shows stacks going from left to right. They are at 1 millisecond intervals. The first and last stack are A, B, the middle three are A, B, C, and doWork.](./images/simple-stacks-self-time.svg)
+
+This image shows that the profiler sampled `B` at the beginning and end of the profiling. This will not change the shape of the call tree, but it will change the self and running times reported.
+
+![This graphic demonstrates the modified call tree. It is a chart of the stacks A, B, C, and doWork, each connected by an arrow going from the root A to the leaf doWork. A has a running time of 5ms, and a self time of 0ms. B has a running time of 5ms, and a self time of 2ms. C has a running time of 3ms, and a self time of 0ms. doWork has a running time of 3ms, and a self time of 3ms.](./images/simple-call-tree-self-time.svg)
+
+The call node with the function `B` continues to have the running time of 5ms, but also has a self time of 2ms. Function `C` has a reduced running time of `3ms` and finally `doWork` was only observed `3ms` for both the running and self time.
+
+In summary, self time is where work was actually happening when observed by the profiler.
+
+## How to form a call tree
+
+> Note: Feel free to follow along with a real call tree that reproduces this structure: [https://perfht.ml/2w45IdC](https://perfht.ml/2w45IdC)
+
+<!--alex ignore simple-->
+The simple call tree above did not take into account any branching stacks. It only concerned itself with running and self time. This section will dive into how the call tree handles stacks of different shapes.
+
+![This image shows contiguous stacks, and how they are sampled over time. It fades out as it goes left to right to indicate that samples are gathered for long periods of time. The stacks are labeled by 1 millisecond intervals. The stacks are labeled by functions that are single capital letters, ranged A to H.](./images/samples.svg)
+
+Consider the first 3 samples in this profile.
+
+![On the left of this graph are three samples with different stacks. A, B, C, D, E. A, B, C, F, G. A, B, H, F, G. The bottom row with A is all grouped together. The second row with B is all grouped together. The third row has the two C functions grouped together, and the H distinct. All the rest of the function sare not grouped. The right graphic demonstrates the shape of the call tree.](./images/call-tree.svg)
+
+These three samples share things in common. The root of each stack is the function `A`. These could be aggregated together into a single node. The same happens for node `B`. However the next level with the function `C` and `H` differ. At this point the call tree splits into two different nodes. There is a node for the function `C`, and the function `H`.
+
+The call tree will continue merging functions that are at the same level, but only if they are part of the current branching pattern. For instance, consider function `F` and `G`. While both functions are at the same level of the stack, they are at different branching points. The middle `F -> G` stacks have `C` as their ancestor, and the right `F -> G` stacks have `H` as their ancestor, and thus are not grouped together.
+
+A useful exercise at this point would be to consider [the running time](./images/call-tree-running-time.svg) and [self time](./images/call-tree-self-time.svg) of each node this call tree.
+
+# Referring to call nodes in the call tree
+
+The above example shows how functions F and G can appear multiple times in a call tree, thus it's ambiguous to refer to a call node by only its function name. Call nodes can be referred to by their call node paths, which are composed of a list of functions from root to leaf. The middle `G` call node in the tree would have the call node path `A, B, C, F, G`, while the one on the right would have the call node path `A, B, H, F, G`.