Skip to content
This repository has been archived by the owner on Jan 26, 2022. It is now read-only.

Debug Protocol Overview #64

Closed
2 tasks done
jtpio opened this issue Oct 17, 2019 · 4 comments · Fixed by #502
Closed
2 tasks done

Debug Protocol Overview #64

jtpio opened this issue Oct 17, 2019 · 4 comments · Fixed by #502
Labels
documentation Improvements or additions to documentation
Milestone

Comments

@jtpio
Copy link
Member

jtpio commented Oct 17, 2019

Adding a quick overview of the debug protocol, so it's easier to visualize the types of messages sent between the JupyterLab extension and the kernel.

It only shows a subset of the messages for now, but can be extended to also include the calls to continue, stepIn and disconnect.

This also show new messages that are not part of the Debug Adapter Protocol (DAP), such as dumpCell.

Diagram

debug-protocol

TODO

  • Add the call to debug_info_request
  • Add the flow to show the files being debugged (stepIn / breakpoints)

References

Source

Generated using: https://bramp.github.io/js-sequence-diagrams/

Diagram source
user->JupyterLab: open notebook

JupyterLab->kernel: kernel_info_request

kernel->JupyterLab: kernel_info_reply

JupyterLab->JupyterLab: check 'debugger' key

JupyterLab->user: show toggle button\nif 'debugger'

user->JupyterLab: enable debugging

JupyterLab->kernel: debugInfo request

kernel->JupyterLab: debugInfo response

user->JupyterLab: start debugger

JupyterLab->kernel: initialize request

kernel->JupyterLab: initialize response

JupyterLab->kernel: attach request

kernel->JupyterLab: attach response

Note right of kernel: debugger started

user->JupyterLab: add breakpoints\n(click on gutters)

JupyterLab->kernel: dumpCell request

kernel->JupyterLab: dumpCell response

JupyterLab->kernel: setBreakpoints request

kernel->JupyterLab: breakpoints response

JupyterLab->kernel: configurationDone request

kernel->JupyterLab: configurationDone response

user->JupyterLab: execute cell\n(Ctrl-Enter)

JupyterLab->kernel: requestExecute

kernel->kernel: execute code

kernel->kernel: hit breakpoint

kernel-->JupyterLab: stopped event

JupyterLab->kernel: stackTrace request

kernel->JupyterLab: stackTrace response

JupyterLab->user: show current line

JupyterLab->kernel: scopes request

kernel->JupyterLab: scopes response

JupyterLab->kernel: variables request

kernel->JupyterLab: variables response

JupyterLab->user: show variables

user->JupyterLab: step in deleted cell code

JupyterLab->kernel: stepIn request

kernel-->JupyterLab: stopped event

JupyterLab->JupyterLab: search for code matching\nsource path

JupyterLab->kernel: source request

kernel->JupyterLab: source response

JupyterLab->user: show source for current path

Note right of kernel: debug session

user->JupyterLab: disable debugging

JupyterLab->kernel: disconnect request

Note right of kernel: debugger stopped

kernel->JupyterLab: disconnect response

JupyterLab->JupyterLab: clear debugging UI for\nthe notebook

@jtpio
Copy link
Member Author

jtpio commented Oct 17, 2019

cc @KsavinN

Let me know if something isn't clear, and we can update the diagram.

@JohanMabille
Copy link
Member

Awesome! That will be super useful for kernel authors who want to support debugging! I think it would be nice to add it to the kernel protocol documentation once the "extended" debug protocol has been adopted.

@jtpio
Copy link
Member Author

jtpio commented Oct 17, 2019

Definitely 👍

@KsavinN KsavinN added the documentation Improvements or additions to documentation label Oct 17, 2019
@KsavinN KsavinN closed this as completed Oct 24, 2019
@KsavinN KsavinN reopened this Oct 24, 2019
@jtpio
Copy link
Member Author

jtpio commented Oct 25, 2019

Adding some documentation on how to inspect the debug messages sent in VS Code. This can be useful to understand when debug requests are made (for example triggered by a UI action).

Create launch.json

First step is to create a test file and a debug configuration:

image

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Current File",
            "type": "python",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal",
            "env": {"PTVSD_LOG_DIR": "/path/to/logs/folder"}
        }
    ]
}

EDIT: recent versions of VS Code are now using debugpy. The launch configuration must then be changed to using the DEBUGPY_LOG_DIR environment variable:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Current File",
            "type": "python",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal",
            "env": {"DEBUGPY_LOG_DIR": "/path/to/logs/folder"}
        }
    ]
}

Start the debugger

image

Open the logs

The content of the log file look like this:

...

D00000.032: IDE --> {
                "command": "initialize",
                "arguments": {
                    "clientID": "vscode",
                    "clientName": "Visual Studio Code",
                    "adapterID": "python",
                    "pathFormat": "path",
                    "linesStartAt1": true,
                    "columnsStartAt1": true,
                    "supportsVariableType": true,
                    "supportsVariablePaging": true,
                    "supportsRunInTerminalRequest": true,
                    "locale": "en-us"
                },
                "type": "request",
                "seq": 1
            }

...

With:

Overview

vscode-debug-logs

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants