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

Last updated on July 14, 2026

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

このガイドでは、Python で記述された Extend Event Handler アプリのデバッグに特有の内容を扱います。環境構築、VS Code のデバッグワークフロー、ログの読み方、よくある問題といった一般的なデバッグの概念については、以下を参照してください。

Extend App テンプレートに基づく

このガイド内のファイルパス、タスク名、モジュール名は AccelByte Extend Event Handler Python テンプレートを参照しています。 プロジェクトで異なる名前を使用している場合でも、考え方自体は同じです。パスをご自身のレイアウトに合わせて調整してください。

前提条件​

インストール要件については、Python 言語セットアップガイドを参照してください。 加えて、ローカル開発中に受信イベントをシミュレートするには grpcurl が必要です。インストールと使用方法については、メインガイドの テスト用のイベントトリガーを参照してください。

プロジェクト構成​

ファイル / パッケージ内容
src/app/__main__.pyエントリポイント — AccelByte SDK を初期化し、クライアント認証情報でログインし、gRPC サービスを登録してサーバーを起動します。
src/app/services/login_handler.pyuserLoggedIn イベント用のビジネスロジック — イベントを受け取り grant_entitlement を呼び出します。
src/app/services/third_party_login_handler.pyuserThirdPartyLoggedIn イベント用のビジネスロジック — login_handler.py と同様のパターンです。
src/app/services/entitlement.pyAGS Fulfillment API を呼び出してユーザーにアイテムを付与する共通ヘルパー。
src/app/utils.pyenvirons を使って .env から環境変数を読み込みます。
src/accelbyte_grpc_plugin/__init__.pyApp クラス — gRPC サーバー、インターセプター、Prometheus、Zipkin、ヘルスチェックを連携させます。
src/accelbyte_grpc_plugin/interceptors/DebugLoggingServerInterceptor と MetricsServerInterceptor。
src/account_pb2.py / src/account_pb2_grpc.pyproto/account.proto から自動生成された gRPC スタブ。直接編集しないでください。
proto/account.protoAGS IAM アカウントイベントの proto 定義。

ポート番号（src/app/__main__.py のデフォルト値）:

ポート用途
6565gRPC サーバー — Kafka Connect からのイベントとシミュレートされた grpcurl の呼び出しを受け取ります
8080Prometheus メトリクスエンドポイント（/metrics）

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

ターミナルから​

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

PYTHONPATH=src venv/bin/python -m app

VS Code から​

Terminal → Run Task → "Run: App" を使用します。 このタスクは .vscode/tasks.json で定義されており、自動的に PYTHONPATH=src が設定されます。

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

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

INFO:app:login client...
INFO:app:login client successful
INFO:app:starting app server..
INFO:app:gRPC health checking enabled
INFO:app:gRPC reflection enabled
INFO:app:prometheus enabled
INFO:app:zipkin enabled
INFO:app:app server started

gRPC のリフレクション（つまりサーバー）が動作していることを確認します。

grpcurl -plaintext localhost:6565 list

期待される出力 — 登録済みサービスの一覧:

accelbyte.iam.account.v1.UserAuthenticationUserLoggedInService
accelbyte.iam.account.v1.UserAuthenticationUserThirdPartyLoggedInService
grpc.health.v1.Health
grpc.reflection.v1alpha.ServerReflection

デバッガーをアタッチする​

VS Code（推奨）​

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

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

手順:

汎用ガイドのデバッガーのアタッチの手順に従い、ドロップダウンから "Debug: App" を選択します。

VS Code は内部で debugpy を使用します。別途設定する必要はありません。

ヒント — justMyCode: デフォルトでは justMyCode: true により、サードパーティのライブラリコードへのステップインがスキップされます。 AccelByte SDK や gRPC の内部処理にステップインする必要がある場合は、.vscode/launch.json でこれを false に変更してください。

その他の IDE — debugpy ヘッドレスモード​

IDE から接続できるように、debugpy をヘッドレスモードで起動します。

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

デバッガーが接続されるまで、このプロセスはブロックされます。その後、IDE を DAP（Debug Adapter Protocol）経由で localhost:5678 にアタッチするように設定します。

ブレークポイントを設定する場所​

注目すべきロジックの大部分はサービスハンドラーファイル内にあります。まずはそこから確認してください。

調査したい内容ファイルと場所
到着したログインイベント全般src/app/services/login_handler.py — OnMessage の先頭
到着したサードパーティログインイベントsrc/app/services/third_party_login_handler.py — OnMessage の先頭
エンタイトルメント付与ロジックsrc/app/services/entitlement.py — grant_entitlement の内部
サービスがまったく起動しないsrc/app/__main__.py — auth_service.login_client(sdk=sdk) の直後
起動時の認証情報チェックsrc/app/__main__.py — login_client の後の if error: ブロック

受信イベントのペイロードを調べる​

デバッガーが OnMessage の内部で一時停止したとき、request パラメーターにはイベントの全体が含まれています。 Variables パネルで展開すると、イベントが持つすべてのフィールド（user_id、namespace、サードパーティイベントの場合は platform_id など、proto/account.proto で定義されているもの）を確認できます。

条件付きブレークポイントの構文​

ブレークポイントを右クリック → Edit Breakpoint → 次のような Python 式を入力します。

request.user_id == "test-user-001"

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

テスト用のイベントトリガー​

イベントシミュレーションのオプションと grpcurl コマンドについては、メインガイドの テスト用のイベントトリガーを参照してください。

サービスメソッドの記述を確認する​

proto メソッドの正確なフィールド名を知る必要がある場合は、grpcurl describe を使用します。

grpcurl -plaintext localhost:6565 \
  describe accelbyte.iam.account.v1.UserAuthenticationUserLoggedInService.OnMessage

これにより、そのメソッドの完全な proto 定義が表示されます。-d のペイロードにどのフィールドを含めるべきか正確に知りたいときに役立ちます。

ログを読む​

このサービスは Python の標準 logging モジュールを使用して stdout に書き込みます。ログの 1 行は次のようになります。

INFO:app:OnMessage request: {"user_id": "test-user-001", "namespace": "mygame"}

ローカル実行中は grep を使ってログ出力を絞り込めます。

# ERROR 行のみを表示
PYTHONPATH=src venv/bin/python -m app 2>&1 | grep "ERROR"

# 特定ユーザーに関連する行を表示
PYTHONPATH=src venv/bin/python -m app 2>&1 | grep "test-user-001"

# すべての OnMessage 呼び出しを表示
PYTHONPATH=src venv/bin/python -m app 2>&1 | grep "OnMessage"

デバッグレベルのログを有効にする​

デフォルトのログレベルは INFO です。デバッグレベルの出力（gRPC インターセプターのログを含む）を確認するには、 .env に PLUGIN_GRPC_SERVER_LOGGING_ENABLED=true を設定します。

PLUGIN_GRPC_SERVER_LOGGING_ENABLED=true

これにより DebugLoggingServerInterceptor が有効になり、受信するすべての呼び出しについて gRPC メソッド名がログに記録されます。

gRPC 呼び出しのパターン​

各イベントが正常に処理されると、ハンドラーからリクエストログとレスポンスログが 1 つずつ出力されます。

INFO:app:OnMessage request: {"user_id": "...", "namespace": "..."}
INFO:app:OnMessage response: {}

リクエスト行だけが表示され、対応するレスポンス行が続かない場合、ハンドラーは応答を返す前にエラーに遭遇しています。 上下の ERROR 行を確認してください。

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

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

症状: proto/ 内のファイルを編集したが、実行時に何も変わらない。

原因: src/account_pb2.py、src/account_pb2_grpc.py、src/account_pb2.pyi に生成されたスタブが再生成されていません。

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

./proto.sh

その後、サービスを再起動します。

ITEM_ID_TO_GRANT が未設定 — サービスが即座に終了する​

症状:

ERROR:app:ITEM_ID_TO_GRANT environment variable is required

原因: .env ファイルに ITEM_ID_TO_GRANT がありません。

対処法: .env に ITEM_ID_TO_GRANT=<your-item-id> を追加して再起動します。このアイテム ID は、AB_NAMESPACE で指定した名前空間内の公開済みストアに存在する必要があります。

サービスが終了する — クライアント認証情報によるログインが失敗する​

症状:

ERROR:app:login client failed

または auth_service.login_client からの例外トレースバック。

原因: AB_CLIENT_ID または AB_CLIENT_SECRET が間違っている、あるいは AB_BASE_URL が誤った環境を指しています。

対処法:

  1. .env 内の認証情報を再確認します。

  2. AB_BASE_URL に到達できることを確認します。

    curl "$AB_BASE_URL/iam/v3/public/config"

  3. Admin Portal で OAuth クライアントに CLIENT_CREDENTIALS グラントタイプが有効になっていることを確認します。

ポート競合を確認する​

「address already in use」と表示された場合:

ss -tlnp | grep -E '6565|8080'

古いプロセスを終了させてから、再度起動してください。

grpcurl が「Failed to dial」を返す​

症状:

Failed to dial target host "localhost:6565": ...

原因: gRPC サーバーがまだ起動していない、起動時にクラッシュした、または別のポートでリスニングしています。

対処法:

  1. サービスのログで起動エラー（ERROR 行）を確認します。
  2. ポート 6565 が開いていることを確認します: ss -tlnp | grep 6565。
  3. grpcurl -plaintext localhost:6565 list を再実行します。成功すればサーバーは起動しています。

ハンドラーが Internal を返すが ERROR ログが表示されない​

症状: grpcurl は Code: Internal を報告しますが、ログに対応する ERROR 行が見つかりません。

原因: 例外が構造化ロガーに到達する前に、AccelByte SDK または gRPC レイヤー内部で捕捉されています。

対処法:

  1. src/app/services/entitlement.py の grant_entitlement 内にブレークポイントを設定し、platform_service.fulfill_item から返される error の値を確認します。
  2. デバッグログを有効にします。.env に PLUGIN_GRPC_SERVER_LOGGING_ENABLED=true を設定して再起動します。

デバッガーがブレークポイントで一時停止しない​

考えられる原因と対処法:

原因対処法
デバッガーではなく Run: App タスクでサービスを起動したVS Code の "Debug: App" launch 設定（F5）を使用します
すでに別のインスタンスが起動していて、そちらがイベントを処理しているポート競合を確認します: ss -tlnp | grep 6565 し、古いプロセスを停止します
justMyCode: true によって対象ファイルがスキップされているファイルが src/ 配下にあり、ライブラリとして扱われていないか確認します。justMyCode: false に設定してみてください
grpcurl が間違ったポートを対象にしているgrpcurl -plaintext localhost:6565 list でポート 6565 を確認します

AI アシスタンス​

このアプリテンプレートには、.claude/skills/debugging-guide/SKILL.md に Claude エージェントスキルが同梱されています。 このスキルファイル全体を自身のリポジトリにコピーし、AI アシスタントで有効化してください。

スキルの全内容とプロンプトのコツについては、メインガイドの AI アシスタンスセクションを参照してください。

参考資料​

に最終更新
On this page