Local Debugging Guide for Extend Override — Python

Last updated on July 14, 2026

注釈：本資料はAI技術を用いて翻訳されています。

このガイドでは、Python で書かれた Extend Override アプリのデバッグに関する具体的な内容を扱います。環境構築、VS Code のデバッグワークフロー、ログの読み方、よくある問題など、共通のデバッグ概念については以下を参照してください。

このガイドの例では、matchmaking のユースケース(matchmaking-function-grpc-plugin-server-python)を使用しています。プロジェクト構成とデバッグ手順は他のすべての Override ユースケースでも同じで、サービスファイルと proto のみが異なります。ガイドの最後にあるサービスファイル参照表を参照してください。

プロジェクト構成​

matchmaking-function-grpc-plugin-server-python/
├── proto.sh                             # protobuf バインディングを再生成
├── .env.template                        # 環境変数テンプレート
├── .vscode/
│   ├── launch.json                      # VS Code デバッグ設定
│   └── tasks.json                       # VS Code タスク(Run: App、Proto: Generate など)
├── proto/
│   └── matchFunction.proto              # protobuf 定義
└── src/
    ├── matchFunction_pb2.py             # 生成された protobuf 型(編集しないこと)
    ├── matchFunction_pb2_grpc.py        # 生成された gRPC servicer(編集しないこと)
    └── app/
        ├── __main__.py                  # エントリポイント — サービスの登録、認証の設定
        ├── ctypes.py                    # GameRules データクラスと ValidationError
        ├── utils.py                     # 環境変数のヘルパー
        └── services/
            └── matchFunction.py         # AsyncMatchFunctionService — Override のロジック
ファイル内容
src/app/__main__.pyエントリポイント — gRPC サーバーを起動し、AsyncMatchFunctionService を登録し、認証インターセプターを接続します。
src/app/services/matchFunction.pyOverride のロジック — GetStatCodes、ValidateTicket、EnrichTicket、MakeMatches、BackfillMatches を実装する非同期 gRPC ハンドラー。
src/app/ctypes.pyGameRules データクラスと ValidationError。
src/matchFunction_pb2.py生成された protobuf メッセージ型。直接編集しないこと。
src/matchFunction_pb2_grpc.py生成された gRPC servicer の基底クラス。直接編集しないこと。
proto/matchFunction.protoprotobuf 定義 — サービスメソッドの信頼できる情報源。

ポート番号(__main__.py で設定):

ポート用途
6565gRPC サーバー — AGS からの呼び出しを受け取ります
8080Prometheus メトリクスエンドポイント(/metrics)

サービスをローカルで実行する​

ターミナルから実行する​

# .env ファイルからすべての変数をエクスポート
export $(grep -v '^#' .env | xargs)

PYTHONPATH=src python -m app

VS Code から実行する​

Terminal → Run Task → "Run: App" を使用します。このタスクは .vscode/tasks.json で定義されており、PYTHONPATH=src を自動的に設定します。プロジェクトルート内の venv/ に仮想環境があることを前提としています。

仮想環境のセットアップ

まだ venv/ ディレクトリがない場合は、次のコマンドを実行します。

python -m venv venv
source venv/bin/activate   # Windows の場合: venv\Scripts\activate
pip install -r requirements.txt

サービスが起動していることを確認する​

次のようなログ出力が表示されるはずです。

INFO:app:using AccelByte Python SDK x.x.x
INFO:asyncio:gRPC server started on port 6565

gRPC サーバーに到達できることを確認します。

grpcurl -plaintext localhost:6565 list

デバッガーを接続する​

VS Code(推奨)​

このリポジトリには、すぐに使える起動設定が .vscode/launch.json に用意されています。

{
  "name": "Debug: App",
  "type": "debugpy",
  "request": "launch",
  "module": "app",
  "cwd": "${workspaceFolder}",
  "envFile": "${workspaceFolder}/.env",
  "env": {
    "PYTHONPATH": "src"
  },
  "console": "integratedTerminal",
  "justMyCode": true
}

共通デバッグガイドのデバッガーの接続の手順に従い、ドロップダウンから "Debug: App" を選択します。

ライブラリコードにステップインする

"justMyCode": true は debugpy やサードパーティのフレームへのステップインをスキップします。accelbyte_grpc_plugin インターセプターや生成された gRPC コードにステップインする必要がある場合は、false に設定してください。

その他の IDE — リモート debugpy アタッチ​

debugpy をポート 5678 でリスニングさせてアプリを起動します。

export $(grep -v '^#' .env | xargs)
PYTHONPATH=src python -m debugpy --listen 5678 --wait-for-client -m app

デバッガーが接続するまでプロセスは一時停止します。PyCharm、リモートデバッガー、または2つ目の VS Code ウィンドウから、以下の設定で接続します。

{
  "name": "Attach: Remote",
  "type": "debugpy",
  "request": "attach",
  "connect": { "host": "localhost", "port": 5678 }
}

ブレークポイントを配置する場所​

調査したい内容ファイルと場所
呼び出されている特定の gRPC メソッドsrc/app/services/matchFunction.py — 対象の非同期メソッドの先頭
ストリーミングのマッチロジックsrc/app/services/matchFunction.py — MakeMatches 内の async for request in request_iterator ループの内部
ルールの解析src/app/services/matchFunction.py — json.loads(rules_json) の行
認証 / トークン検証の失敗src/accelbyte_grpc_plugin/interceptors/authorization.py — インターセプターのエントリ
サービスがまったく起動しないsrc/app/__main__.py — sdk.initialize(...) と auth_service.login_client_async(...) の呼び出し

条件付きブレークポイントの構文については、Python 言語ガイドを参照してください。

ログを読む​

このサービスは Python 標準の logging モジュールを使用します。サービスが JSON ログを出力する場合の jq によるログのフィルタリングについては、Python 言語ガイドを参照してください。

サービスの実行中にエラーレベルの出力だけを確認するには、次のようにします。

PYTHONPATH=src python -m app 2>&1 | grep ERROR

Override を手動でテストする​

grpcurl の使い方と、Override された AGS 機能をトリガーする方法については、Override メインガイドのOverride を手動でテストするを参照してください。

demo/ ディレクトリには、事前構築済みのリクエストを含む Postman コレクション(*.postman_collection.json)が含まれています。Postman にインポートし、ローカル環境用に baseUrl と token を更新してください。

Python 特有のトラブルシューティング​

Proto の変更が反映されない​

症状: proto/matchFunction.proto を編集したが、生成されたスタブが更新されていません。

原因: 生成されたファイル src/matchFunction_pb2.py と src/matchFunction_pb2_grpc.py が再生成されていません。

対処法: "Proto: Generate" の VS Code タスクを実行するか、次のコマンドを実行します。

./proto.sh

再生成後にサービスを再起動してください。

ModuleNotFoundError: No module named 'app'​

症状: python -m app を実行すると ModuleNotFoundError: No module named 'app' が発生します。

原因: PYTHONPATH が設定されていないため、Python が src/ 内の app モジュールを見つけられません。

対処法: 常にコマンドの前に PYTHONPATH=src を付けます。

PYTHONPATH=src python -m app

VS Code の起動設定と "Run: App" タスクはこれを自動的に処理します。

PLUGIN_GRPC_SERVER_AUTH_ENABLED — 認証がすべての呼び出しを拒否する​

症状: ローカルでテストすると、すべての gRPC 呼び出しが unauthenticated を返します。

対処法: .env ファイルに PLUGIN_GRPC_SERVER_AUTH_ENABLED=false を追加します。これにより IAM インターセプターが無効になり、有効なトークンなしでテストできます。デプロイ前に再度有効にすることを忘れないでください。

debugpy が見つからない​

症状: VS Code が debugpy がインストールされていないと表示するか、起動設定が失敗します。

対処法:

# まず仮想環境を有効化し、その後インストール
source venv/bin/activate
pip install debugpy

ポートの競合を確認する​

Python 言語ガイドのポートの競合を確認するを参照してください。

AI アシスタンス​

各 Override ユースケースのアプリテンプレートには、.claude/skills/debugging-guide/SKILL.md に Claude エージェントスキルが同梱されています。AI プロンプトのヒントと MCP サーバーの詳細については、Override メインガイドのAI アシスタンスによるデバッグを参照してください。

ユースケース別サービスファイル参照​

上記のデバッグワークフローは、すべての Override ユースケースに適用されます。サービスファイルと proto のみが異なります。実装ファイルを見つけるには、この表を使用してください。

ユースケースPython サービスファイルProto ファイル
Matchmakingsrc/app/services/matchFunction.pyproto/matchFunction.proto
Cloud Save Validatorリポジトリの README を参照リポジトリの README を参照
Lootbox Rollリポジトリの README を参照リポジトリの README を参照
Profanity Filterリポジトリの README を参照リポジトリの README を参照
Revocationリポジトリの README を参照リポジトリの README を参照
Rotating Shop Itemsリポジトリの README を参照リポジトリの README を参照
Session DSMリポジトリの README を参照リポジトリの README を参照
Session Managerリポジトリの README を参照リポジトリの README を参照
Challenge Assignmentリポジトリの README を参照リポジトリの README を参照

各ユースケースおよび言語のリポジトリリンクについては、Extend Override リポジトリを参照してください。

参考資料​

に最終更新
On this page