octavia/doc/source/contributor/guides/remote-debugger.rst

Debugging Octavia code

This document describes how to setup and debug Octavia code using your favorite IDE (e.g. PyCharm, Visual Studio Code).

Prerequisites

• Octavia installed.
• IDE installed and Octavia added as project.

Setup

Both PyCharm Professional edition and Visual Studio Code offer remote debugging features that can be used for debugging Octavia components.

Note

Before running a new Octavia process you should make sure that processes of that component are no longer running. You can use ps aux in order to verify that.

PyCharm

Note

Remote debugging is a PyCharm Professional feature.

PyCharm offers two ways of debugging remotely¹. In general, the "through a remote interpreter" approach is more convenient and should be preferred. On the other hand, the "Python debug server" approach is the only one that works for debugging the API component (because of uWSGI). Therefore, this guide will explain both approaches.

Using a remote interpreter

First, configure a remote interpreter for the VM as documented in². Adding a deployment configuration with correct path mappings allows PyCharm to upload local changes to the remote host automatically.

Then, create a new Run/Debug Configuration by selecting Run -> Edit Configurations... in the menu bar. Add a new configuration and make sure Module name is selected instead of Script path. Enter the module name of the Octavia component you want to debug, for instance octavia.cmd.octavia_worker. Additionally, add --config-file /etc/octavia/octavia.conf to Parameters. Then check whether the right remote Python interpreter is selected. After you confirm the settings by clicking OK you should be able to run/debug the Octavia component with that new run configuration.

Using a Python debug server

As mentioned above the "remote interpreter" approach does not work with Octavia-API because that process is managed by uWSGI. Here the Python debug server approach³ needs to be used. You will need to install the pydevd-pycharm via pip as shown when creating the run/debug configuration. However, it is not necessary to modify the Python code in any way because Octavia code is already set up for it to work.

Export DEBUGGER_TYPE, DEBUGGER_HOST and DEBUGGER_PORT (host and port of the system running the IDE, respectively), and start the Octavia service you want to debug. For example, to debug the Octavia API service:

$ export DEBUGGER_TYPE=pydev
$ export DEBUGGER_HOST=192.168.121.1
$ export DEBUGGER_PORT=5678
$ uwsgi --ini /etc/octavia/octavia-uwsgi.ini

Note

You must run the Octavia/uWSGI command directly. Starting it via systemctl will not work with the debug server.

Visual Studio Code

While PyCharm synchronizes local changes with the remote host, Code will work on the remote environment directly through a SSH tunnel. That means that you don't even need to have source code on your local machine in order to debug code on the remote.

Detail information about remote debugging over SSH can be found in the official Visual Studio Code documentation⁴. This guide will focus on the essential steps only.

Using the remote development extension pack

Note

This approach will not work with the Octavia API component because that component is managed by uWSGI.

After installing the Visual Studio Code Remote Development Extension Pack ⁵ you need to open the Remote Explorer view and connect to the SSH target. This will open a new window and on the bottom left of that window you should see SSH: followed by the SSH host name. In the Explorer view you can then choose to either clone a repository or open an existing folder on the remote. For instance when working with devstack you might want to open /opt/stack or /opt/stack/octavia.

Next, you should configure the launch.json, which contains the run configurations. Use the following template and adjust it to your needs:

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Octavia Worker",
            "type": "python",
            "request": "launch",
            "module": "octavia.cmd.octavia_worker",
            "args": ["--config-file", "/etc/octavia/octavia.conf"],
            "justMyCode": true
        }
    ]
}

Make sure that the correct Python interpreter is selected in the status bar. In a devstack environment the global Python interpreter /usr/bin/python3 should be the correct one. Now you can start debugging by pressing F5.

Note

When running this the first time Visual Studio Code might ask you to install the Python debugger extension on the remote, which you must do. Simply follow the steps shown in the IDE.

Using ptvsd

Warning

ptvsd has been deprecated and replaced by debugpy. However, debugpy doesn't seem work with uWSGI processes. The information in this section might be outdated.

Another example is debugging the Octavia API service with the ptvsd debugger:

$ export DEBUGGER_TYPE=ptvsd
$ export DEBUGGER_HOST=192.168.121.1
$ export DEBUGGER_PORT=5678
$ /usr/bin/uwsgi --ini /etc/octavia/octavia-uwsgi.ini -p 1

The service will connect to your IDE, at which point remote debugging is active. Resume the program on the debugger to continue with the initialization of the service. At this point, the service should be operational and you can start debugging.

Troubleshooting

Remote process does not connect with local PyCharm debug server

1. Check if the debug server is still running

2. Check if the values of the exported DEBUGGER_ variables above are correct.

3. Check if the remote machine can reach the port of the debug server:

   $ nc -zvw10 $DEBUGGER_HOST $DEBUGGER_PORT

   If it cannot connect, the connection may be blocked by a firewall.

---

1. https://www.jetbrains.com/help/pycharm/remote-debugging-with-product.html↩︎

2. https://www.jetbrains.com/help/pycharm/remote-debugging-with-product.html#remote-interpreter↩︎

3. https://www.jetbrains.com/help/pycharm/remote-debugging-with-product.html#remote-debug-config↩︎

4. https://code.visualstudio.com/docs/remote/ssh↩︎

5. https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack↩︎