Document how to debug and profile the plugin host

.vscode/launch.json

@@ -58,8 +58,8 @@
         "--port=3000",
         "--no-cluster",
         "--app-project-path=${workspaceRoot}/examples/browser",
-        "--no-app-auto-install",
-        "--plugins=local-dir:plugins"
+        "--plugins=local-dir:plugins",
+        "--hosted-plugin-inspect=9339"
       ],
       "env": {
         "NODE_ENV": "development"
@@ -75,6 +75,21 @@
       "internalConsoleOptions": "openOnSessionStart",
       "outputCapture": "std"
     },
+    {
+      "type": "node",
+      "request": "attach",
+      "name": "Attach to Plugin Host",
+      "port": 9339,
+      "timeout": 60000,
+      "stopOnEntry": false,
+      "smartStep": true,
+      "sourceMaps": true,
+      "internalConsoleOptions": "openOnSessionStart",
+      "outFiles": [
+        "${workspaceRoot}/packages/plugin-ext/lib/**/*.js",
+        "${workspaceRoot}/plugins/**/*.js"
+      ]
+    },
     {
       "type": "node",
       "request": "launch",

doc/Developing.md

@@ -34,6 +34,12 @@ For Windows instructions [click here](#building-on-windows).
      - [Debug the Electron example's backend](#debug-the-electron-examples-backend)
      - [Debug the Electron example's frontend](#debug-the-electron-examples-frontend)
      - [Debug IPC servers](#debug-ipc-servers)
+     - [Debug the plugin host](#debug-the-plugin-host)
+ - [**Profiling**](#profiling)
+     - [Profile the frontend process](#profile-the-frontend-process)
+     - [Profile the backend process](#profile-the-backend-process)
+     - [Profile IPC servers](#profile-ipc-servers)
+     - [Profile the plugin host](#profile-the-plugin-host)
  - [**Testing**](#testing)
  - [**Code coverage**](#code-coverage)
  - [**Building on Windows**](#building-on-windows)
@@ -219,22 +225,22 @@ Let assume you have to work for instance in the `@theia/navigator` extension. Bu
 
 ### Debug the browser example's backend
 
- - In VS Code: start the debug tab and run the `Launch Backend` configuration.
+ - Open the debug view and run the `Launch Backend` configuration.
 
 ### Debug the browser example's frontend
 
  - Start the backend by using `yarn run start`.
  - In a browser: Open http://localhost:3000/ and use the dev tools for debugging.
- - In VS Code: start the debug tab and run the `Launch Frontend` configuration.
+ - Open the debug view and run the `Launch Frontend` configuration.
 
 ### Debug the browser example's frontend and backend at the same time
 
- - In VS Code: Start the debug tab and run the `Launch Backend` configuration.
+ - Open the debug view and run the `Launch Backend` configuration.
  - Then run the `Launch Frontend` configuration.
 
 ### Debug the Electron example's backend
 
- - In VS Code: Start the debug tab and run the `Launch Electron Backend` configuration.
+ - Open the debug view and run the `Launch Electron Backend` configuration.
 
 ### Debug the Electron example's frontend
 
@@ -251,6 +257,49 @@ Let assume you have to work for instance in the `@theia/navigator` extension. Bu
 In order to look up `server-name` run the backend server with `--log-level=debug` flag to enable logging of IPC servers instantiation.
 You should be able to see message of `[${server-name}: ${server-PID}]: IPC started` format, like `[nsfw-watcher: 37557] IPC started`.
 
+### Debug the plugin host
+
+  - Pass `--hosted-plugin-inspect=9339` arg to the backend server from the command line.
+    - Instead you can run `Launch Backend` launch configuration which is already preconfigured.
+  - Open the debug view and run the `Attach to Plugin Host` launch configuration.
+    - It connects to the plugin host if at least one extension is detected, otherwise it timeouts after 60s.
+    - If you want to debug the activation then enable `stopOnEntry` flag.
+  - Open the browser page.
+
+## Profiling
+
+ - Use Chrome devtools to profile both the frontend and backend (Node.js).
+   - For Node.js: open chrome://inspect, click the configure button and ensure target host and port are listed.
+ - Learn how to get and understand CPU measurements: https://developers.google.com/web/tools/chrome-devtools/evaluate-performance/
+ - Learn how to get and understand Memory measurements: https://developers.google.com/web/tools/chrome-devtools/memory-problems/
+ - Before taking the memory snapshot always collect garbage.
+ - Make sure that Chrome extensions don't distort measurements by disabling them.
+   - For frontend: React extension is leaking components.
+ - Make measurements before and after improvements to provide them as evidence on a pull request.
+   - Also document how to reproduce improved measurements in `How to test` section of a pull request description.
+ - If objects don't have a proper class, i.e. plain JSON, then find one of them in the first snapshot
+ and check that it is garbage collected in the diff between snapshots.
+
+### Profile the frontend process
+
+  - In Browser: open the devtools.
+  - In Electron: Help -> Toggle Electron Developer Tools.
+
+### Profile the backend process
+
+  - Pass `--inspect` arg to the backend server: https://nodejs.org/en/docs/inspector/#command-line-options.
+
+### Profile IPC servers
+
+  - Pass `--${server-name}-inspect` arg to the backend server.
+    - For example `--nfsw-watcher-inspect=0` to inspect nfsw watcher processes with dynamic port allocation.
+    - All variations of `--inspect` flag are supported: https://nodejs.org/en/docs/inspector/#command-line-options.
+
+### Profile the plugin host
+
+ - Pass `--hosted-plugin-inspect` arg to the backend server.
+   - All variations of `--inspect` flag are supported: https://nodejs.org/en/docs/inspector/#command-line-options.
+
 ## Testing
 
 See the [testing](Testing.md) documentation.