profile-viewer 0.0.4 → 0.0.5

data/dist/docs/async-posix-signal-control.md

@@ -1,4 +1,3 @@
-
 # Profiler control using POSIX signals
 
 The Firefox profiler supports the use of asynchronous POSIX signals for a
@@ -72,21 +71,21 @@ needing to directly load the profile.
 The current implementation of POSIX signal support has a number of important
 limitations that potential users need to be aware of:
 
-* The profiler currently uses a set of "default"
+- The profiler currently uses a set of "default"
   [values](https://searchfox.org/mozilla-central/rev/7a8904165618818f73ab7fc692ace4a57ecd38c9/tools/profiler/core/platform.cpp#633)
   when started using signals. There are currently plans to support configuration
   (see [Bug 1866007](https://bugzilla.mozilla.org/show_bug.cgi?id=1866007) for
   further information).
-* Async signal handling is currently only supported and tested on POSIX native
+- Async signal handling is currently only supported and tested on POSIX native
   platforms, i.e. Linux and MacOS. Support for Windows is planned, but not yet
   implemented (see [Bug
   1867328](https://bugzilla.mozilla.org/show_bug.cgi?id=1867328) for further
   information).
-* The "stop" signal must be sent to Firefox's "main" process. This is due to
+- The "stop" signal must be sent to Firefox's "main" process. This is due to
   Firefox's sandboxing rules, which disallow non-main processes (in general)
   from opening file handles. Because of this, individual processes cannot dump
   their own data to disk, so cannot individually handle the stop signal.
-* Signal support in the Firefox profiler is incompatible with Firefox's [code
+- Signal support in the Firefox profiler is incompatible with Firefox's [code
   coverage](https://firefox-source-docs.mozilla.org/tools/code-coverage/index.html)
   tooling, as both rely on the same POSIX signals (`SIGUSR1` and `SIGUSR2`). In
   an ideal world we could use Linux's
@@ -95,7 +94,7 @@ limitations that potential users need to be aware of:
   not clash with the signals used by the code coverage tool. Unfortunately,
   MacOS does not support these signals, so we are limited to the smaller set of
   signals in order to support a wider set of platforms.
-* Although signals are used to start/stop the profiler, the aggregation of
+- Although signals are used to start/stop the profiler, the aggregation of
   content-process profiles is still done using "traditional" Firefox IPC calls.
   If, therefore, you are using signals to diagnose issues with a "stuck" main
   thread in the main process, Firefox may not be able to aggregate child content

data/dist/docs/bunny-2.md

@@ -1,4 +1,5 @@
 # Case Study
+
 ## Harnessing parallelism
 
 Consider the [previous case study](bunny.md). The amount of work being done was reduced by some performance fixes, allowing for a much faster frame rate. However, there is still a problem with this code. It's not taking advantage of the parallelism of having a worker thread.
@@ -14,7 +15,7 @@ Looking at a zoomed-in view of the thread stack graph shows how the content proc
 In a simplified code example, the iframe that is drawing using the [`CanvasRenderingContext2D`](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D API) runs code that looks something like this:
 
 ```js
-worker.addEventListener('message', message => {
+worker.addEventListener('message', (message) => {
   if (message.data.type === 'draw') {
     requestAnimationFrame(() => {
       // Draw the current set of rectangles.
@@ -29,7 +30,7 @@ worker.addEventListener('message', message => {
 In this example, the iframe draws to the canvas, and once it's done, it posts a message to the worker asking it to generate a new list of the draw calls. While this works, it's not harnessing the fact that the worker can run code in parallel. The fix luckily is clear. Swap the order of the `drawRect` and `worker.postMessage` calls.
 
 ```js
-worker.addEventListener('message', message => {
+worker.addEventListener('message', (message) => {
   if (message.data.type === 'draw') {
     requestAnimationFrame(() => {
       // Ask the worker to generate the new draw calls for the NEXT frame.

data/dist/docs/bunny.md

@@ -1,14 +1,15 @@
 # Case Study
+
 ## 2D canvas and worker messaging
 
 The following article is a case study in using the profiler to identify performance issues. The fixes made the code run four times faster and changed the frame rate from a fairly slow 15fps to a smooth 60fps. The process for this analysis follows a common pattern:
 
- * Profile the code
- * Identify slow areas
- * Form a hypothesis as to why it's slow
- * Act upon the hypothesis and change the code
- * Profile the code to measure the difference
- * Evaluate the effectiveness of the code change
+- Profile the code
+- Identify slow areas
+- Form a hypothesis as to why it's slow
+- Act upon the hypothesis and change the code
+- Profile the code to measure the difference
+- Evaluate the effectiveness of the code change
 
 ## The project description
 
@@ -41,7 +42,7 @@ self.postMessage({
 Then the iframe would draw the code using:
 
 ```js
-worker.addEventListener('message', message => {
+worker.addEventListener('message', (message) => {
   const { data } = message;
   for (let i = 0; i < data.color.length; i++) {
     ctx.fillStyle = data.color[i];
@@ -58,16 +59,16 @@ Baseline profile: https://perfht.ml/2IxTwqi
 
 This code ended up not scaling well for large sets of rectangles being drawn to the screen. There were lots of stutters and a slow frame rate. The user's impact for fixing this problem would be to have a smoother frame rate, plus the ability to draw many more rectangles to the screen without slowing things down. In order to validate fixes, the following steps were used to reproduce the issue.
 
- * Load the page with the bunny visualization.
- * Hit Ctrl Shift 1 to turn on the Gecko Profiler.
- * Wait around 5 seconds.
- * Hit Ctrl Shift 2 to capture the profile.
- * Set the range to 3.0 seconds of relatively stable frames that don't have stutters or GC pauses.
- * Hide idle stacks by right clicking `__psync_cvwait` and `mach_msg_trap` in the Flame Graph, and choosing **"Drop samples with this function"**.
- * Filter the threads to:
-   * The relevant content process
-   * The relevant DOM Worker
-   * The compositor
+- Load the page with the bunny visualization.
+- Hit Ctrl Shift 1 to turn on the Gecko Profiler.
+- Wait around 5 seconds.
+- Hit Ctrl Shift 2 to capture the profile.
+- Set the range to 3.0 seconds of relatively stable frames that don't have stutters or GC pauses.
+- Hide idle stacks by right clicking `__psync_cvwait` and `mach_msg_trap` in the Flame Graph, and choosing **"Drop samples with this function"**.
+- Filter the threads to:
+  - The relevant content process
+  - The relevant DOM Worker
+  - The compositor
 
 ### Getting oriented
 
@@ -124,10 +125,10 @@ The repeated calls to `set fillStyle` are unnecessary for the bunny, as there ar
 The fix for this would be of only setting the color when it's been changed.
 
 ```js
-worker.addEventListener('message', message => {
+worker.addEventListener('message', (message) => {
   const { data } = message;
   for (let i = 0; i < data.color.length; i++) {
-    const nextColor = data.color[i]
+    const nextColor = data.color[i];
     if (prevColor !== nextColor) {
       // Only update the color if it's changed.
       ctx.fillStyle = nextColor;
@@ -240,9 +241,11 @@ self.postMessage({
   h: hArray._array,
   w: wArray._array,
   length: colorArray.length,
-})
+});
 ```
+
 <!--alex ignore simple-->
+
 This makes the code much more complex and hard to maintain, but it could be the key to better performance. This is a common trade-off with fast code and simple code. It's important that any additional complexities are backed by an analysis that it actually affects user-perceived performance.
 
 ### The resulting structured clone profile:
@@ -273,9 +276,9 @@ In the analysis, only the functions that were taking the most time were consider
 
 A good follow-up would be to do more analysis on a variety of different test cases to ensure that these changes didn't regress performance on a different example.
 
-| Metric | Baseline | Fix 1 | Fix 2 | Magnitude Change |
-| --- | --- | --- | --- | --- |
-| Time per frame | ~65ms | ~40ms | ~16ms | 4x (faster) |
-| Frames per second | ~15fps | ~25fps | ~60fps | 4x (faster) |
-| non-idle time in `(root)` on the content process | 2107ms | 1613ms | 725ms | 2.9x (faster) |
-| non-idle time in `(root)` on the worker | 666ms | 814ms | 725ms | 0.9x (slower) |
+| Metric                                           | Baseline | Fix 1  | Fix 2  | Magnitude Change |
+| ------------------------------------------------ | -------- | ------ | ------ | ---------------- |
+| Time per frame                                   | ~65ms    | ~40ms  | ~16ms  | 4x (faster)      |
+| Frames per second                                | ~15fps   | ~25fps | ~60fps | 4x (faster)      |
+| non-idle time in `(root)` on the content process | 2107ms   | 1613ms | 725ms  | 2.9x (faster)    |
+| non-idle time in `(root)` on the worker          | 666ms    | 814ms  | 725ms  | 0.9x (slower)    |

data/dist/docs/gitpod.md

@@ -1,6 +1,6 @@
 # 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.
+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)
@@ -9,7 +9,7 @@ Click the link below. An automatic workspace will be created.
 
 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. 
+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
 
@@ -23,17 +23,12 @@ If you want to load profiles for development, you can follow the steps described
 
 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. 
+- 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.
+- 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. 
-
-
-
-
-
+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

@@ -1,6 +1,8 @@
 # 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 visualize the CPU profiles exported from [Android Studio CPU Profiler](https://developer.android.com/studio/profile/cpu-profiler) as `*.trace` files. Load the exported file into [profiler.firefox.com](https://profiler.firefox.com), using drag-and-drop or "Load a profile from file".
+
+Alternatively, Android ndk provides [`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. Android Studio CPU profiler also uses `simpleperf` internally.
 
 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)).
 
@@ -29,6 +31,20 @@ This records the profile into a `perf.data` file, and pulls it to your host.
 
 ### Step 2: Convert the profile
 
+You can convert the `perf.data` file to one of the format supported by Firefox Profiler.
+
+#### Option 1: Simpleperf trace file
+
+Convert `perf.data` to the Simpleperf trace file format. You can also modify this command to provide proguard mapping file or unstripped SOs to symbolicate.
+
+```bash
+# Convert perf.data to perf.trace
+# If on Mac/Windows, use simpleperf host executable for those platforms instead.
+./bin/linux/x86_64/simpleperf report-sample --show-callchain --protobuf -i perf.data -o perf.trace
+```
+
+#### Option 2: Using gecko_profile_generator.py
+
 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
@@ -39,7 +55,7 @@ Then convert to a Gecko Profile (Firefox Profiler) format, using [`gecko_profile
 
 ### 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".
+Load the `perf.trace` or `profile.json.gz` created in previous step into [profiler.firefox.com](https://profiler.firefox.com), using drag-and-drop or "Load a profile from file".
 
 ## See also
 

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

@@ -4,12 +4,12 @@ Call trees can grow to be quite large, especially when profiling a browser engin
 
 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. |
+| 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
 
@@ -21,14 +21,14 @@ Searching will exclude samples that do not match a search string. The search fil
 
 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)
+- 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.
+- `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
 

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

@@ -76,17 +76,17 @@ UI.
 
 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
+- `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.
+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.
+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')
 
@@ -112,4 +112,3 @@ you uploaded from the same browser instance.
 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

@@ -8,9 +8,9 @@ Linux has a native profiler called 'perf' that can profile any application. This
 
 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.
+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.
 
@@ -20,9 +20,9 @@ As a consequence of point 2, perf has far lower overhead than the Gecko Profiler
 
 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).
+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
 
@@ -63,11 +63,11 @@ The `perf script` command takes the `perf.data` file that was written by the `pe
 ### 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.
+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.
+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.
 

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

@@ -1,34 +1,35 @@
 # 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 
+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).
+- 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.
+- 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.
+- 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

@@ -2,6 +2,5 @@
 
 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.
-
+- [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

@@ -9,38 +9,39 @@ In order to do so, you need both your phone with the mobile Gecko-based browser,
 ## 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.
+- 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".
+- 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.
+- 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.
+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.
+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)
@@ -49,8 +50,8 @@ Make any necessary adjustments in the presented options, like threads to sample
 
 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.
+- 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?
 
@@ -73,18 +74,18 @@ additional guide on the dedicated page](./guide-startup-shutdown#firefox-for-and
 
 ### 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.
+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.
+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.
+- 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

@@ -1,4 +1,5 @@
 # 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

@@ -13,6 +13,7 @@ These examples assume the profiler is configured to collect samples every 1 mill
 ![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)
@@ -38,6 +39,7 @@ In summary, self time is where work was actually happening when observed by the
 > 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)

data/dist/docs/guide-startup-shutdown.md

@@ -7,15 +7,21 @@ please go to https://profiler.firefox.com to add it first to your Firefox.
 
 1. Start your Firefox with the environment variable `MOZ_PROFILER_STARTUP=1` set. This way, the profiler is started as early as possible during startup.
 
+   This can also be done inline when running Firefox [Mach](https://firefox-source-docs.mozilla.org/mach/):
+
+   ```bash
+   $ MOZ_PROFILER_STARTUP=1 ./mach run
+   ```
+
 2. Then capture the profile using the popup, as usual.
 
 Startup profiling does not use the settings that you configured in the `about:profiling`. It uses settings that can be configured with the environment variables `MOZ_PROFILER_STARTUP_ENTRIES`, `MOZ_PROFILER_STARTUP_INTERVAL`, and more:
 
-* If it looks like the buffer is not large enough, you can tweak the buffer size with the env var `MOZ_PROFILER_STARTUP_ENTRIES`. This defaults to 1000000, which is 9MB. If you want 90MB, use 10000000, and for 180MB, use 20000000, which are good values to debug long startups.
+- If it looks like the buffer is not large enough, you can tweak the buffer size with the env var `MOZ_PROFILER_STARTUP_ENTRIES`. This defaults to 1000000, which is 9MB. If you want 90MB, use 10000000, and for 180MB, use 20000000, which are good values to debug long startups.
 
-* If you'd like a coarser resolution, you can also choose a different interval using `MOZ_PROFILER_STARTUP_INTERVAL`, which defaults to 1 (unit is millisecond). You can't go below 1 ms, but you can use e.g. 10 ms.
+- If you'd like a coarser resolution, you can also choose a different interval using `MOZ_PROFILER_STARTUP_INTERVAL`, which defaults to 1 (unit is millisecond). You can't go below 1 ms, but you can use e.g. 10 ms.
 
-* More environment variables are available to control the profiler settings. They can be listed by setting `MOZ_PROFILER_HELP=1` and running Firefox from a command line inside a terminal; Firefox will exit immediately, and display all accepted variables in the terminal.
+- More environment variables are available to control the profiler settings. They can be listed by setting `MOZ_PROFILER_HELP=1` and running Firefox from a command line inside a terminal; Firefox will exit immediately, and display all accepted variables in the terminal.
 
 ## Shutdown
 
@@ -27,7 +33,6 @@ Startup profiling does not use the settings that you configured in the `about:pr
 
 For startup profiling, similar to [startup profiling on Desktop](https://developer.mozilla.org/en-US/docs/Mozilla/Performance/Profiling_with_the_Built-in_Profiler#Profiling_Firefox_Startup), you will need to manually set some `MOZ_PROFILER_STARTUP*` environment variables. The way to do this varies based on the app you want to profile (more details below). Once the app has been started with these environment variables, the profiler will be running. Then you can connect to the app using `about:debugging` as usual, and capture the profile with the regular UI.
 
-
 ## Firefox for Android
 
 First, you'll need to use [the general information about profiling on Android](./guide-remote-profiling.md).
@@ -59,6 +64,7 @@ adb shell am start -n org.mozilla.geckoview_example/.App \
 Fenix has a [different way](https://firefox-source-docs.mozilla.org/mobile/android/geckoview/consumer/automation.html#reading-configuration-from-a-file) to specify environment variables: it uses a yaml file.
 
 The easiest way to set up startup profiling is to run the `<mozilla-central-repo>/mobile/android/fenix/tools/setup-startup-profiling.py` script. For example:
+
 ```bash
 ./mobile/android/fenix/tools/setup-startup-profiling.py activate nightly  # To activate startup profiling on nightly.
 ./mobile/android/fenix/tools/setup-startup-profiling.py deactivate beta  # To deactivate startup profiling on beta.
@@ -72,7 +78,7 @@ If you don't want to check out [mozilla-central](https://hg.mozilla.org/mozilla-
 
 The filename of the YAML file mentioned above depends on the bundle ID of your Fenix app. The instructions below assume you want to profile the Fenix Nightly app, with the bundle ID `org.mozilla.fenix`.
 
- 1. Create a file with the name `org.mozilla.fenix-geckoview-config.yaml` on your desktop machine and content of the following form:
+1.  Create a file with the name `org.mozilla.fenix-geckoview-config.yaml` on your desktop machine and content of the following form:
 
     ```
     env:
@@ -81,8 +87,9 @@ The filename of the YAML file mentioned above depends on the bundle ID of your F
       MOZ_PROFILER_STARTUP_FEATURES: js,stackwalk,screenshots,ipcmessages,java,processcpu,cpu
       MOZ_PROFILER_STARTUP_FILTERS: GeckoMain,Compositor,Renderer,IPDL Background
     ```
- 2. Push this file to the device with `adb push org.mozilla.fenix-geckoview-config.yaml /data/local/tmp/`.
- 3. Run `adb shell am set-debug-app --persistent org.mozilla.fenix` to make sure the file is respected.
+
+2.  Push this file to the device with `adb push org.mozilla.fenix-geckoview-config.yaml /data/local/tmp/`.
+3.  Run `adb shell am set-debug-app --persistent org.mozilla.fenix` to make sure the file is respected.
 
 From now on, whenever you open the Fenix app, Gecko will be profiling itself automatically from the start, even if remote debugging is turned off. Then you can enable remote debugging, connect to the browser with `about:debugging`, and capture the profiling run.
 
@@ -104,5 +111,3 @@ adb shell am start-activity -d "https://www.mozilla.org/" \
 When combined with the startup profiling `.yaml` file as described in the previous section, this allows profiling GeckoView during the App Link startup path. This is the scenario of a user opening a link from a different Android app in the default browser.
 
 Startup from App Link is the most important GeckoView startup scenario. In this scenario, GeckoView startup is directly in the critical path between the user action (tapping the link) and the first useful result (the web page being shown on the screen). This is different from the scenario of launching Fenix from the home screen - in that case, Fenix can show meaningful content even before Gecko is initialized, so Gecko's startup time is not as crucial to the experience.
-
-