ローカルデバッグガイド — Python

Last updated on July 14, 2026

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

このガイドでは、Python で作成された Extend Service Extension アプリのデバッグに固有の内容を説明します。環境セットアップ、VS Code のデバッグワークフロー、ログの読み方、よくある問題といった共通のデバッグ概念については、以下を参照してください。

プロジェクト構造​

src/
└── app/
    ├── __main__.py                            # Entry point
    ├── services/
    │   └── my_service.py                      # Your business logic
    └── ...
proto/
└── app/
    └── service.proto                          # gRPC API definition
ファイル内容
src/app/__main__.pyエントリポイント — gRPC サーバーと gRPC-Gateway を起動します。
src/app/services/my_service.pyビジネスロジック — gRPC サービスメソッドを実装します。
src/accelbyte_grpc_plugin/interceptors/authorization.pyすべての受信リクエストの IAM トークンと権限を検証します。
proto/app/service.protogRPC API を定義します — エンドポイント、リクエスト/レスポンスの形式、必要な権限。

ポート番号:

ポート用途
6565gRPC サーバー（内部用 — gRPC-Gateway によって使用されます）
8000gRPC-Gateway HTTP/REST — ブラウザ、Postman、curl から呼び出します
8080Prometheus メトリクスエンドポイント（/metrics）

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

ターミナルから​

# Export all variables from your .env file
export $(grep -v '^#' .env | xargs)

python -m app

VS Code から​

Terminal → Run Task → "Run: Service" を使用します。 このタスクは .vscode/tasks.json で定義されており、.env ファイルを自動的に読み込みます。

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

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

{"time":"...","level":"INFO","msg":"app server started","service":"extend-app-service-extension"}
{"time":"...","level":"INFO","msg":"starting gRPC-Gateway HTTP server","port":8000}
{"time":"...","level":"INFO","msg":"serving prometheus metrics","port":8080,"endpoint":"/metrics"}

ブラウザで http://localhost:8000<BASE_PATH>/apidocs/ を開き、Swagger UI が動作していることを確認します。

デバッガーの接続​

VS Code（推奨）​

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

{
  "name": "Debug: Service",
  "type": "python",
  "request": "launch",
  "module": "app",
  "cwd": "${workspaceFolder}/src",
  "envFile": "${workspaceFolder}/.env"
}

一般的なガイドのデバッガーの接続の手順に従い、ドロップダウンから "Debug: Service" を選択します。

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

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

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

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

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

ブレークポイントを置く場所​

調査したい内容ファイルと場所
呼び出されている特定の REST エンドポイントservices/my_service.py — 該当メソッドの先頭
認証/トークン検証の失敗accelbyte_grpc_plugin/interceptors/authorization.py — リクエストのインターセプトポイント
データが正しく保存または読み込まれないサービスで使用しているストレージまたはリポジトリモジュール
サービスがまったく起動しないapp/__main__.py — サーバー設定ブロック

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

ログの読み方​

jq によるログフィルタリングについては、 Python 言語ガイドを参照してください。

エンドポイントを手動でテストする​

curl と grpcurl の使用方法については、一般的なガイドの grpcurl を使ったテストを参照してください。

Swagger UI によるテスト（SE 固有）については、SE メインガイドの エンドポイントを手動でテストするを参照してください。

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

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

症状: proto/app/service.proto を編集したが、生成されたスタブが更新されていない。

対処法: proto 生成スクリプトを再実行します。

./proto.sh

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

app に対する ModuleNotFoundError​

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

原因: 作業ディレクトリが正しくありません。モジュールは src/ 配下にあります。

対処法:

cd src
python -m app

または PYTHONPATH を設定します。

PYTHONPATH=src python -m app

debugpy が見つからない​

症状: VS Code が debugpy がインストールされていないと表示する。

対処法:

pip install debugpy
# 仮想環境を使用している場合は、まず有効化してください:
source .venv/bin/activate && pip install debugpy

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

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

AI 支援​

アプリテンプレートには、 .claude/skills/debugging-guide/SKILL.md に Claude エージェントスキルが同梱されています。

AI プロンプトのヒントと MCP サーバーの詳細については、一般的なガイドの AI 支援によるデバッグを参照してください。

参考資料​

に最終更新
On this page