VSCode でリモートアタッチを利用して Embedded Python をデバッグする方法

開発者の皆さん、こんにちは！

この記事では、InterSystems IRIS サーバサイドで実行できるPython（Embedded Python）のデバッグ方法をご紹介します。

前提：VSCode の Python デバッガ用モジュールの debugpy を利用するため、Python スクリプトファイルに記載した Embedded Python のコードが対象です。クラス定義に[Language = python]を指定して記載しているコードは対象外となります。ご注意ください！

（1）なぜdebugpyを使うのか？

VSCode の Python デバッガは内部的に、debugpy を使用していますが、これは「VSCode が起動した Python プロセス」に自動適用される仕組みです。

そのため、irispython のような VSCode 管理外の Python プロセスや、すでに起動しているリモート／コンテナ上の Python に対しては、明示的に debugpy を起動する必要があります。

(2)debugpyのインストール

ということで、debugpy をインストールします。

pip install debugpy

必要であれば --break-system-packages を付けてインストールします。

pip3 install debugpy --break-system-packages

(3)VSCodeの準備

VSCode デバッグメニューを開き、create a launch.json file をクリックし、launch.json に Python リモートアタッチ用デバッガを設定します。

リモートアタッチで接続するサーバー名（IPアドレス）、リモートのデバッグサーバーがリッスンするポート番号を指定します。

上記指定で、launch.json がワークスペースに追加されるので、利用環境に合わせて設定を変更します。

※ ポート番号は空いている任意の番号を利用できます。

pathMappings は、「VSCode 上のファイル」と「デバッグ対象プロセスが実行しているファイル」を1対1で対応付けるための設定です。

この対応が取れていない場合、ブレークポイントを置いてもヒットしない、または別の行で止まることがあります。

pathMappings 以下の localRoot は、VSCodeのワークスペースフォルダのルートがデフォルト設定されていますので、デバッグ用のPythonスクリプトファイルがあるディレクトリを指定します。

例では、ワークスペース/src/DebugTest.py をデバッグ用コードに使用したいので、${workspaceFolder}/src としています。

pathMappings 以下の remoteRoot は、アタッチ先デバッグサーバーで実行する Python スクリプトファイルの存在するのディレクトリを指定します。

指定例は以下の通りです。

✅例1：Embedded Pythonの実行がローカルの場合

Windows での記述例です。

remoteRoot には、Embedded Python で実行する Python スクリプトファイルが存在するディレクトリ：C:\\WorkSpace\\EmbeddedPythonDebug\\src を指定しています。

{
    // 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": "Python Debugger: Remote Attach",
            "type": "debugpy",
            "request": "attach",
            "connect": {
                "host": "localhost",
                "port": 5678
            },
            "pathMappings": [
                {
                    "localRoot": "${workspaceFolder}/src",
                    "remoteRoot": "C:\\WorkSpace\\EmbeddedPythonDebug\\src"
                }
            ]
        }
    ]
}

✅例2：Embedded Python の実行がIRISコンテナの場合

※ VSCode Dev Containersを利用している場合は、ドキュメント：Running a Session through Docker Dev Containers をご参照ください。

コンテナの場合は、デバッグサーバーがリッスンするポート番号をコンテナ開始時にホストから利用できるように、ポートフォーワードを指定する必要があります。

このリポジトリでは、docker-compose.yml を利用しているため、以下の設定をしています。

ports: ["9872:1972","5678:5678","52773:52773"]

services:  iris:    build:      context:.      dockerfile:Dockerfile    ports:["9872:1972","5678:5678","52773:52773"]    container_name:trysql    volumes:["./src:/src"]    environment:      -TZ=JST-9

また、VSCode のデバッグで参照するホスト上のディレクトリをコンテナから参照できるようにバインドマウントしておく必要があります。

volumes: ["./src:/src"]

ホストの src をコンテナの /src にバインドマウントしています。

上記コンテナに対する launch.json は以下の通りです。

{
    // 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": "Python Debugger: Remote Attach",
            "type": "debugpy",
            "request": "attach",
            "connect": {
                "host": "localhost",
                "port": 5678
            },
            "pathMappings": [
                {
                    "localRoot": "${workspaceFolder}/src",
                    "remoteRoot": "/src"
                }
            ]
        }
    ]
}

(4)デバッグ

サンプル一式👉https://github.com/Intersystems-jp/debug-embedded-python

デバッグを開始するため、debugpy をインストールしたデバッグサーバーで Python スクリプトファイルを実行します。実行時 irispython を使用します。

実行時の記述は以下の通りです。

<IRISインストールディレクトリ>/bin/irispython -m debugpy --listen localhost:5678 --wait-for-client <Pythonスクリプトファイル>

--listen localhost:5678 は、デバッグサーバーに localhost からポート 5678 での接続待機を指示しています。

コンテナの場合は、ホストから接続する必要があるので --listen 0.0.0.0:5678 と指定します。

--wait-for-client の指定で、VSCodeのデバッガーからの接続があるまで Python スクリプトが実行されないようにします。

※ --wait-for-client を指定しない場合、VSCode から接続する前に Python スクリプトが実行されるため、設定したブレークポイントには到達しません。

具体的な実行例は以下の通りです。

ローカルでの実行

Windowsでの実行例で記載します。IRISのインストールディレクトリを c:\intersystems\irishealth1 として記載していますので、実行環境に合わせてディレクトリを変更してください。

デバッグ前に初期データなどの準備をします。irispythonを利用して以下実行します。

c:\intersystems\irishealth1\bin\irispython .\src\DebugTest.py --mode prepare

DebugTest.py の prepare()関数を実行しています。

初期実行が終了したら、irispython と debugpy を利用して Python スクリプトを実行します。

コンテナでの実行

/usr/irissys/bin/irispython -m debugpy --listen 0.0.0.0:5678 --wait-for-client /src/DebugTest.py

DebugTest.py の run()関数を実行します。

コンテナ開始からデバッグ実行までの一連の流れ

コンテナ開始

docker compose up -d

コンテナへログイン

docker exec -it debugtest bash

デバッグ実行

/usr/irissys/bin/irispython -m debugpy --listen 0.0.0.0:5678 --wait-for-client /src/DebugTest.py

ここで、VSCodeのデバッグメニューから launch.json で指定した設定を利用して、デバッグを開始します。

launch.json の name　に設定した名称：Python Debugger: Remote Attach が表示されているので、クリックするとデバッグが開始します。

 後は、VSCodeのメニューに従ってデバッグを進めます。

よくあるトラブル

実際に遭遇したトラブルをご紹介します。

✅ブレークポイントが止まらない　→　pathMappings の対応が合っていない

✅コンテナで localhost 指定して接続できない。　→　 0.0.0.0 を指定して解消

✅import iris でエラーになる　→　irispythonで起動していない