[Guide] Debugging GitLens in an Extension Host Process After It’s Started

[gluxon]

Context

I've been running into a strange GitLens issue (#3066) for a long time, but had trouble nailing it down since the problem was always intermittent and I wasn't able to reproduce it in a Extension Development Window. When the problem did reproduce, it went away with a extension host restart, removing the repro.

Goal

It should be possible to take any production built VS Code window running an extension like GitLens and debug it without a restart that may lose the bad state. I recently worked through how to do this and wanted to write it down somewhere for others (and my future self).

Disclaimers

• This is a write-up from an external contributor. I'm not affiliated with GitLens.
• This will likely be out of date in a few years.
• There will probably be VS Code or Chrome improvements that make this easier in the future.

Let's dive in!

Finding the VS Code Extension Host Process Port

The usual trick for debugging a node process is to send it the SIGUSR1 signal.

❯ kill -SIGUSR1 <pid>

The VS Code extension host process seems to listen on a less deterministic port than node processes out of the box. Fortunately VS Code makes it easy to attach itself to its own extension host.

Hit the circle button to start profiling the extension host. Then hit the play button to the left to attach to the process. (Without hitting the profile button first, VS Code offers to restart the extension host.)

To attach Chrome's Node.js inspector, we'll need the port the process is listening on. In the debug console, we can enter:

require('inspector').url()

The port for this process is 56929.

Attaching Chrome

At chrome://inspect, we'll add the port discovered above.

This gives a new Inspect button.

From here, we can search for files loaded into the process. For GitLens, one file of interest is the bundled gitlens.js file.

Checking Out Source

The above allows us to interactively debug gitlens.js, but this file is hard to understand since it's bundled and minified. We can GitLen's source code to make this easier. To do so, we'll want to check out the source for the exact version of GitLens we're using.

~/Developer/vscode-gitlens main 
❯ git checkout v14.6.1        
Note: switching to 'v14.6.1'.

Let's make a small tweak to GitLen's webpack.config.js to create a production build with source maps. We'll want to use hidden-source-map to output our own gitlens.js file that matches the currently running one.

diff --git a/webpack.config.js b/webpack.config.js
index 84fd17e9b..097d3a4f9 100644
--- a/webpack.config.js
+++ b/webpack.config.js
@@ -150,7 +150,7 @@ function getExtensionConfig(target, mode, env) {
                },
                mode: mode,
                target: target,
-               devtool: mode === 'production' ? false : 'source-map',
+               devtool: 'hidden-source-map',
                output: {
                        chunkFilename: 'feature-[name].js',
                        filename: 'gitlens.js',

To build GitLens for production:

❯ yarn bundle

As an optional sanity check, we can make sure the built gitlens.js files are the same as what VS Code is running. If there are mismatches, the source code cloned could be subtly different than the original source of the loaded gitlens.js file, which would cause breakpoints to mismatch and other oddities when debugging.

❯ shasum ~/.vscode/extensions/eamodio.gitlens-14.6.1/dist/gitlens.js dist/gitlens.js
813627ea9dc246815b1077bed4ab4c50eda228a5  /Users/gluxon/.vscode/extensions/eamodio.gitlens-14.6.1/dist/gitlens.js
813627ea9dc246815b1077bed4ab4c50eda228a5  dist/gitlens.js

Adding Source Maps to Chrome's Inspector

Let's teach Chrome about our built dist/gitlens.js.map. We'll need the absolute path of this file.

Back in the Chrome inspector, we can right click anywhere in gitlens.js to "Add source map..."

Finally, let's add our cloned vscode-gitlens directory to make file navigation easier. Hit "Add folder" on the left sidebar.

Profit

It works! Note that the files loaded into Chrome on the left have green circles indicating their source maps are correctly associated with the generated gitlens.js production build.

[eamodio]

@gluxon This is awesome -- TY!

[gluxon]

Thank you! Appreciate all your work on GitLens. Love it.