Make Cyberbrain more intuitive to use

[laike9m]

Background

In #49 and cool-RR's email, an issue was mentioned:
It is not intuitive how to run a different program and open the trace graph with new data.

Quote:

I tried out the demo on Gitpod and followed the instructions. After viewing the first example I ran a different example but didn't know how to view the graph. Eventually I figured out that killing the first process with Ctrl+C made it possible to reinitialize Cyberbrain with a new example.

I changed the value passed to the function and reran, expecting to see the graph updated with the new values when I hovered with the mouse. It wasn't. I also tried the command "Initialize CyberBrain" again and yet the value wasn't updated.

Clearly we need to do better at this.

How It Works Now?

Currently, the Cyberbrain Python lib (abbr. cb-py) launches a server. When users run "Initialize Cyberbrain" in VS Code, the The Cyberbrain VS Code extension (abbr. cb-vsc) talks to the server and fetches data, then visualizes it. The server listens on a fixed port, thus there can't be multiple running servers.

Proposed Solution

Note: the below solution takes into consideration a feature which has not been implemented yet: multi-frame tracing. The original design of this feature is described here, which may differ from the below solution. But the core idea keeps unchanged: let users pick the frame to visualize.

Overview

cb-vsc automatically starts a long-running server, let's call it coordination server (abbr. cs). The workflow looks like this:

1. When cb-py finishes tracing a Python program
   • 2.1. If there's only one frame
     cb-py sends this frame to cs/cb-vsc, cb-vsc generates a new trace graph.
   • 2.2. If there are multiple frames
     3. cb-py sends the locations of these frames (aka FrameLocaterList) to cs/cb-vsc
     4. The user picks one frame (details TBD), cs/cb-vsc sends the location of this frame (FrameLocater) back to cb-py
     5. cb-py sends the selected frame to cs/cb-vsc, cb-vsc generates a new trace graph.

Note that in case 2.2, step 3-5 could repeat multiple times to allow visualizing different frames in the same execution. This requires server-side streaming RPC, so cs/cb-vsc can send multiple FrameLocaters to cb-py. Also cb-vsc should persist the locations of all available frames.

The proposed solution has a few benefits compared to the existing implementation:

• Users only need to run the Python program, no need to run "Initialize Cyberbrain".
• The experience keeps unchanged for running multiple programs and/or multiple times.

The Coordination Server

Requirements:

• cs should remain active as long as VS Code is open, presumably with a periodic status check.

• The listening port should be configurable. Potentially, we can use a config file ~/.cyberbrain_config and let cb-py and cb-vsc read it.

Open questions:

• Will vsc launch multiple coordination servers when there are multiple opened window? If yes, we need to handle it gracefully.

Things to Take into Consideration

Stateless

The infrastructure should be as stateless as possible, otherwise it would be very complicated to maintain and extend.

Future Proof

The design should work well with future features to add, including (but not limited to) multi-frame tracing, though this is hard since things may change or news features are planned.

Needs to work well with codelens #34

The report sent from cb-py could potentially carry information to tell cb-vsc where to show codelens, so that users are aware of the click-to-enable-trace-graph feature. This (and supporting for multi-frame tracing) also means that the Python program needs to stay alive before manually terminated.

Remote Debugging Friendly

The design should be able to support remote debugging.

AI: Learn how remote debugging works.

Third-party Friendly

We should not rely on VS Code specific things, and if users want to build their own cs and frontend, they should be able to do so.

[laike9m]

@alexmojaki @cool-RR @laixintao to take a look

[alexmojaki]

Sounds like a good plan.

[laike9m]

The re-implementation of current user workflow (single frame) is done and released in 0.0.10.

I will create separate issues for multi-frame support.