Display debugged sub-processes as a treeview

[DonJayamanne]

Terms

• sub-process: It’s basically a process started by a parent process (analogous to spawn in node).

Debug toolbar should show run configurations in drop-down, not processes

• The current solution implemented within the python extension for sub-process debugging is as follows:
  • User launches some python code in VSC debugger
  • The user code in the python program then spins up a sub process
  • The Python debug adapter intercepts the above call, and launches a sub-process in a remote debugging manner (so that the VS Code debugger can attach to it).
  • The extension gets a notification about this with the new process ID and starts a debug session by attaching to the above sub-process
  • We now have a dropdown in the debug toolbar with two items:
  • First item – Original debug configuration name
  • Second item – “Child Process xyz” (name provided by the extension when starting the new debug session)

Expected behavior

• VSC needs to provide a way to display child processes in the UI.
• Single click to stop debugging (when debugging child processes)

Current behavior

• Python Extension is displaying child process as another debug configuration.
• This leads to confusions amongst users.
  • The user launched one program for debugging, why are they now getting two debug sessions, with a stop and detach button?
  • The user has to click on the red icon to stop debugging twice (first Detach then Stop).
• If the user were to start debugging some other application such as React/node.js (or similar), then this additional item in the dropdown of the debug toolbar adds to the confusion.
  • As before, the user started debugging two applications, but they have 3 items in the dropdown.

[qubitron]

I wanted to add a few more details using an example.

Currently if I start two different debug configurations (one flask, one django) with auto-reload enabled, I see the following in the debug dropdown:

... and the following in the call stack window:

What we're saying is that the sub-processes automatically spawned by the parent process should be treated logically as part of one application, but associated with the debug configuration.

So for this example we would be proposing :

• The debug dropdown only lists Flask and Django (debug configurations I have explicitly launched), the call stack window already lists all processes so they don't need to be repeated in the debug dropdown.
• The stop button would stop a debug configuration and all of its sub processes automatically, in our case it can simply stop the parent process and then we would clean up sub processes
• The pause button would pause all processes in that debug configuration
• The call stack window can continue to show all running processes for all debug configurations, but perhaps if there are multiple processes per debug configuration we could show the relationship as a tree structure, e.g.:

- Django
   - Parent Process
   - Sub Process
- Flask
   - Parent Process
   - Sub Process

[weinand]

Clarification:
The dropdown menu in the debug toolbar shows "debug sessions" not "debug configurations".

Today both VS Code and the Debug Adapter Protocol (DAP) knows nothing about child processes. All functionality supported in the scenarios from above works either automatically or through a small amount of glue code in the debugger extension.

Making VS Code's debugger multi-process aware would be a big effort which not only affects VS Code but the DAP as well. Currently we do not see a big need for this and consequently it is not on our roadmap.

So the only feature that I could imagine to offer for VS Code is some sort of "visual grouping mechanism". So when creating new debug sessions via the extension API (e.g. "startDebugging" call), we could support to pass in a parent debug session and VS Code would honour that by indenting the debug sessions to form a tree.

As a workaround for now you could just prepend some non-breakable whitespace characters (\u00A0) to the generated debug configuration name. I tried this for the node.js Cluster and it looks like this:

/cc @isidorn

[qubitron]

Coming back to this, we were blocked on another issue on our side but will soon be able to make progress.

I don't think we need the DAP to be multi-process aware, if VS Code could be made aware of "Child Debug Sessions" on create as you proposed, what we'd be asking for in the UI would be to:

• Not show child debug sessions in the debug toolbar dropdown, only the parent
• Stop debugging on the parent would stop the child debug sessions as well

So in the typical case when you start debugging once, but the app spawns multiple child debug sessions, the user would have a single stop button that would stop all child sessions.

Visual indenting in the call stack window as you've shown would be nice as well, but this is not essential as it would only be for the less common case when the user has intentionally started debugging two different parent debug sessions.

[weinand]

@qubitron we are planning to implement the "visual grouping of child processes" approach in the next milestone. The only API change will add an additional parent: DebugSession argument to the startDebugging API.

Now I have a question regarding the UI that we will have to implement for this feature.

Above you said:

"Not show child debug sessions in the debug toolbar dropdown, only the parent".

I do not understand how that would work:
If I'm stopped in a python application that has one parent and two child processes and all of them are stopped, how would I single step in one of the child processes, if I'm not able to select the child in the dropdown (because it only shows the parent)?