Bug 1582140 - Create more detailed docs for the profiler popup; r=julienw a=doc
authorGreg Tatum <gtatum@mozilla.com>
Fri, 20 Sep 2019 16:33:16 +0000
changeset 494300 8daa0d686ff2068e4b3ecf8ce7a54594b0f043f4
parent 494299 635b7dd1a4680932306cc41eeca30f8bf6708607
child 494301 1e934531dc8e7625b2a7691db726d47b2e79b7d3
push id114114
push userdluca@mozilla.com
push dateFri, 20 Sep 2019 22:00:08 +0000
treeherdermozilla-inbound@56e11fddf939 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersjulienw, doc
bugs1582140
milestone71.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1582140 - Create more detailed docs for the profiler popup; r=julienw a=doc And also the DevTools new performance panel. Differential Revision: https://phabricator.services.mozilla.com/D46288
devtools/client/performance-new/README.md
devtools/client/performance-new/initializer.js
devtools/client/performance-new/panel.js
devtools/client/performance-new/popup/initializer.js
devtools/client/performance-new/store/README.md
new file mode 100644
--- /dev/null
+++ b/devtools/client/performance-new/README.md
@@ -0,0 +1,21 @@
+# Performance New
+
+This folder contains the code for the new performance panel that is a simplified recorder that works to record a performance profile, and inject it into profiler.firefox.com. This tool is not in charge of any of the analysis, only the recording.
+
+## Overall Architecture
+
+The performance panel is split into two different modes. There is the DevTools panel mode, and the browser menu bar "popup" mode. The UI is implemented for both in `devtools/client/performance-new`, and many codepaths are shared. Both use the same React/Redux setup, but then each are configured with slightly different workflows. These are documented below.
+
+### DevTools Panel
+
+This panel works similarly to the other DevTools panels. The `devtools/client/performance-new/initializer.js` is in charge of initializing the page specifically for the DevTools workflow. This script creates a `PerfActor` that is then used for talking to the Gecko Profiler component on the debuggee. This path is specifically optimized for targeting Firefox running on Android phones. This workflow can also target the current browser, but the overhead from DevTools can skew the results, making the performance profile less accurate.
+
+### Profiler Popup
+
+The popup can be enabled by going to `Tools -> Web Developer -> Enable Profiler Toolbar Icon". This then runs the initializer in`devtools/client/performance-new/popup/initializer.js`, and configures the UI to work in a configuration that is optimized for profiling the current browser. The Gecko Profiler is turned on (using the ActorReadyGeckoProfilerInterface), and is queried directly–bypassing the DevTools' remote debugging protocol.
+
+## Injecting profiles into [profiler.firefox.com]
+
+After a profile has been collected, it needs to be sent to [profiler.firefox.com] for analysis. This is done by using browser APIs to open a new tab, and then injecting the profile into the page through a frame script. See `frame-script.js` for implementation details. Both the DevTools Panel and the Popup use this frame script.
+
+[profiler.firefox.com]: https://profiler.firefox.com
--- a/devtools/client/performance-new/initializer.js
+++ b/devtools/client/performance-new/initializer.js
@@ -22,16 +22,22 @@ const actions = require("devtools/client
 const { Provider } = require("devtools/client/shared/vendor/react-redux");
 const {
   receiveProfile,
   getRecordingPreferencesFromDebuggee,
   setRecordingPreferencesOnDebuggee,
 } = require("devtools/client/performance-new/browser");
 
 /**
+ * This file initializes the DevTools Panel UI. It is in charge of initializing
+ * the DevTools specific environment, and then passing those requirements into
+ * the UI.
+ */
+
+/**
  * Initialize the panel by creating a redux store, and render the root component.
  *
  * @param perfFront - The Perf actor's front. Used to start and stop recordings.
  * @param preferenceFront - Used to get the recording preferences from the device.
  */
 async function gInit(perfFront, preferenceFront) {
   const store = createStore(reducers);
 
--- a/devtools/client/performance-new/panel.js
+++ b/devtools/client/performance-new/panel.js
@@ -1,15 +1,22 @@
 /* This Source Code Form is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 "use strict";
 
 loader.lazyRequireGetter(this, "EventEmitter", "devtools/shared/event-emitter");
 
+/**
+ * This file contains the PerformancePanel, which uses a common API for DevTools to
+ * start and load everything. This will call `gInit` from the initializer.js file,
+ * which does the important initialization for the panel. This code is more concerned
+ * with wiring this panel into the rest of DevTools and fetching the Actor's fronts.
+ */
+
 class PerformancePanel {
   constructor(iframeWindow, toolbox) {
     this.panelWin = iframeWindow;
     this.toolbox = toolbox;
 
     EventEmitter.decorate(this);
   }
 
--- a/devtools/client/performance-new/popup/initializer.js
+++ b/devtools/client/performance-new/popup/initializer.js
@@ -1,15 +1,23 @@
 /* This Source Code Form is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
 "use strict";
 
 /**
+ * This file initializes the profiler popup UI. It is in charge of initializing
+ * the browser specific environment, and then passing those requirements into
+ * the UI. The popup is enabled by toggle the following in the browser menu:
+ *
+ * Tools -> Web Developer -> Enable Profiler Toolbar Icon
+ */
+
+/**
  * Initialize the require function through a BrowserLoader. This loader ensures
  * that the popup can use require and has access to the window object.
  */
 const { BrowserLoader } = ChromeUtils.import(
   "resource://devtools/client/shared/browser-loader.js"
 );
 const { require } = BrowserLoader({
   baseURI: "resource://devtools/client/performance-new/popup/",
new file mode 100644
--- /dev/null
+++ b/devtools/client/performance-new/store/README.md
@@ -0,0 +1,3 @@
+# Performance New Store
+
+This folder contains the Redux store logic for both the DevTools Panel and the Profiler Popup.