Local debugging guide for Extend apps

Last updated on July 14, 2026

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

Overview​

このガイドでは、すべての AccelByte Extend アプリタイプ（Extend Override、Extend Event Handler、Extend Service Extension）に共通するデバッグの概念とツールについて説明します。

このガイドはベースラインのリファレンスとして使用してください。使用するアプリタイプや言語に固有の詳細については、以下のナビゲーションテーブルを利用してください。

アプリタイプ別​

アプリタイプ個別のデバッグガイド
Extend OverrideExtend Override のローカルデバッグガイド
Extend Event HandlerExtend Event Handler のローカルデバッグガイド
Extend Service ExtensionExtend Service Extension のローカルデバッグガイド

言語別​

言語言語セットアップガイド
GoGo
C#C#
JavaJava
PythonPython

環境設定​

すべての Extend アプリは、その設定を環境変数から読み込みます。テンプレートファイルはリポジトリのルートに用意されています。

ステップ 1 — .env ファイルを作成する​

cp .env.template .env

次に、エディタで .env を開き、値を入力します。

VS Code のショートカット

このリポジトリには "Create .env File" という VS Code タスクが同梱されています（.vscode/tasks.json を参照）。 fillenv がインストールされている場合、このタスクを実行することでファイルを自動的に生成できます。

ステップ 2 — 必須の変数を入力する​

以下の変数は、すべての Extend アプリタイプで必須です。

# AccelByte environment
AB_BASE_URL=https://<your-ags-environment>.accelbyte.io
AB_CLIENT_ID=<your-client-id>
AB_CLIENT_SECRET=<your-client-secret>

# Disable token validation during local development.
# Deployed Extend apps always have this value set to `true` and can't be changed.
PLUGIN_GRPC_SERVER_AUTH_ENABLED=false

# Log verbosity: debug | info | warn | error
LOG_LEVEL=debug
変数目的例
AB_BASE_URL使用する AGS 環境の URLhttps://dev.accelbyte.io
AB_CLIENT_IDOAuth クライアント IDabc123
AB_CLIENT_SECRETOAuth クライアントシークレットs3cr3t
PLUGIN_GRPC_SERVER_AUTH_ENABLEDローカルでトークンチェックをスキップする場合は falsefalse
LOG_LEVELログの詳細度debug
アプリタイプ固有の変数

一部のアプリタイプでは追加の変数が必要です。たとえば、Extend Service Extension では BASE_PATH が必要です。変数の完全なリストについては、アプリタイプ固有のデバッグガイドを参照してください。

ステップ 3 — サービスが AGS に到達できることを確認する​

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

JSON レスポンスが返れば、URL に到達可能であることが確認できます。ここでエラーが発生する場合は、URL が間違っているか、到達不能であることを意味します。

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

VS Code から実行する​

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

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

サービスが起動すると、次のようなログ出力が表示されます。

{"time":"...","level":"INFO","msg":"app server started"}

使用する言語の正確なターミナル実行コマンドについては、 言語別ガイドを参照してください。

VS Code でデバッガをアタッチする​

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

  1. .env ファイルに値が入力されていることを確認してください。
  2. Run and Debug パネルを開きます。Ctrl+Shift+D（Windows/Linux）または Cmd+Shift+D （macOS）を押すか、アクティビティバーのバグアイコンをクリックします。
  3. パネル上部のドロップダウンから "Debug: Service" を選択します。
  4. F5 を押します（または緑色の ▶ ボタンをクリックします）。

VS Code はデバッガ内でサービスを起動します。これにより、実行を一時停止し、 変数を検査し、コードを 1 行ずつステップ実行できるようになります。

言語固有の起動設定の詳細や、VS Code を使用しないセットアップについては、 言語別ガイドを参照してください。

ブレークポイントの設定と状態の検査​

ブレークポイントの設定方法​

ガター（行番号の左側にある細い帯）の中で、一時停止したい行の横をクリックします。赤い丸が表示されます。実行がその行に到達すると、VS Code は一時停止し、次の情報を表示します。

  • Variables — すべてのローカル変数とその現在の値。
  • Watch — 継続的に監視するために手動で追加した式。
  • Call Stack — 現在の行に到達するまでのすべての関数呼び出し。
  • Debug Console — 式をライブで評価できるプロンプト。

コードをステップ実行する​

操作ショートカット動作内容
ContinueF5次のブレークポイントまで実行する
Step OverF10現在の行を実行し、呼び出された関数には入らない
Step IntoF11現在の行で呼び出された関数の中に入る
Step OutShift+F11現在の関数を完了し、呼び出し元に戻る
RestartCtrl+Shift+F5デバッグセッションを再起動する
StopShift+F5デバッガを停止する

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

ブレークポイントの丸を右クリック → Edit Breakpoint → 条件を入力します。 デバッガは、条件が true と評価された場合にのみ一時停止します。 これは、多数のリクエストの中から特定のものだけを検査したい場合に特に便利です。

各言語の条件式の構文例については、 言語別ガイドを参照してください。

ヒント​

  • Call Stack パネルを確認してください。 デバッガが一時停止すると、Call Stack には、現在のフレームからエントリーポイントまで、現在の行に到達するまでのすべての関数呼び出しが表示されます。 これにより、リクエストがどのようにコードに到達したかを正確に把握できます。

  • Watch パネルを使用してください。 req.Namespace や err のような式を追加しておくと、Variables パネルを毎行展開しなくても、ステップ実行中に監視できます。

  • 条件付きブレークポイントを使用してください。 すべてのリクエストで停止するのではなく、調査対象の正確な入力に条件を絞り込みます。

ログの読み取りと理解​

すべての Extend アプリは、構造化された JSON ログ行を標準出力に出力します。1 行のログは次のようになります。

{"time":"2026-03-10T12:00:00Z","level":"INFO","msg":"request received","method":"SomeMethod","duration":"1.234ms"}

ログレベル​

レベル表示されるタイミング注意すべきタイミング
DEBUGLOG_LEVEL=debug の場合のみロジックや変数値の詳細なトレース
INFOデフォルト通常のイベント（サーバー起動、リクエスト受信）
WARN予期しないが致命的ではない事象繰り返し発生する場合は調査する価値がある
ERROR何かが失敗した場合常に調査する

ローカル開発中は .env で常に LOG_LEVEL=debug を設定してください。追加の gRPC ペイロードログにより、ブレークポイントを設定せずに問題が判明することが多くあります。

gRPC リクエスト/レスポンスのペア​

サービスは、すべての gRPC 呼び出しの開始と終了を自動的にログに記録します。

{"msg":"started call","grpc.method":"SomeMethod", ...}
{"msg":"finished call","grpc.code":"OK","grpc.duration":"2ms", ...}

grpc.code が OK 以外（たとえば Unauthenticated、Internal、NotFound など）の場合は、 ログをスクロールして上に戻り、原因を説明する ERROR 行を探してください。

jq によるログの整形表示​

jq をインストールし、ローカル開発中にサービスの出力をパイプで渡します。

# Pretty-print all logs
<your-run-command> 2>&1 | jq '.'

# Show only ERROR-level logs
<your-run-command> 2>&1 | jq 'select(.level == "ERROR")'

<your-run-command> は、言語別ガイドにある言語固有のコマンドに置き換えてください。

grpcurl でのテスト​

grpcurl を使用すると、ポート 6565 の gRPC サーバーを直接呼び出すことができます。すべての Extend アプリは、このポートで gRPC サーバーを公開しています。

# List available services (server reflection is enabled)
grpcurl -plaintext localhost:6565 list

# Call a method directly
grpcurl -plaintext \
  -d '{"namespace":"mygame"}' \
  localhost:6565 <ServiceName>/<MethodName>

これは、問題がアプリのロジックにあるのか、それとも上位のゲートウェイレイヤーにあるのかを切り分けるのに役立ちます。

PLUGIN_GRPC_SERVER_AUTH_ENABLED=true の場合は、gRPC メタデータに有効なベアラートークンを追加してください。

grpcurl -plaintext \
  -H "authorization: Bearer <token>" \
  -d '{"namespace":"mygame"}' \
  localhost:6565 <ServiceName>/<MethodName>

よくある問題​

サービスが終了する — "unable to login using clientId and clientSecret"​

症状:

{"level":"ERROR","msg":"error unable to login using clientId and clientSecret","error":"..."}

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

解決策:

  1. .env の認証情報を再確認してください。
  2. AB_BASE_URL に到達可能であることを確認してください: curl "$AB_BASE_URL/iam/v3/public/config"。
  3. OAuth クライアントで CLIENT_CREDENTIALS グラントタイプが Admin Portal で有効になっていることを確認してください。

すべてのリクエストが 401 Unauthenticated を返す​

症状: すべての gRPC 呼び出しが Unauthenticated ステータスを返します。

原因: トークン検証が有効になっており、リクエスト内のベアラートークンが欠落している、期限切れである、または必要な権限を欠いています。

解決策（ローカルデバッグ）: .env で PLUGIN_GRPC_SERVER_AUTH_ENABLED=false を設定し、再起動してください。

ブレークポイントが一度もヒットしない​

考えられる原因と解決策:

原因解決策
リクエストがコードに到達する前に失敗している（例: 認証時）認証を無効化する: PLUGIN_GRPC_SERVER_AUTH_ENABLED=false
サービスの別のインスタンスが同じポートで実行中ポートの競合を確認する: ss -tlnp | grep 6565 を実行し、古いプロセスを停止する
コードパスに到達していない（メソッド名が間違っている）利用可能なメソッドを確認する: grpcurl -plaintext localhost:6565 list

ヒントとベストプラクティス​

  • ローカルでは常に LOG_LEVEL=debug を使用してください。 追加の gRPC ペイロードログにより、ブレークポイントを設定せずに問題が判明することが多くあります。

  • ローカルでは認証を無効化し、コミット前に再度有効化してください。 PLUGIN_GRPC_SERVER_AUTH_ENABLED=false は開発用の一時的な設定であり、永続的な設定ではありません。プッシュする前に true に戻し、 トークンの権限が正しく機能することを確認してください。

  • 起動前にポートを確認してください。 "address already in use" と表示された場合、 サービスの以前のインスタンスがまだ実行中です。

    ss -tlnp | grep 6565

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

  • .env ファイルは絶対にコミットしないでください。 このファイルには認証情報が含まれています。 .gitignore に記載されていることを確認してください。チームメンバーが必要な変数を把握できるように、.env.template への変更はコミットしてください。

AI 支援を利用したデバッグ​

オプションのセクション

チームで AI ツールを使用していない場合は、このセクションをスキップしてください。このガイドの他のすべてのセクションは、単独で完結しています。

Claude Code、GitHub Copilot などの AI コーディングアシスタントは、 不明なコードの説明、ログの解析、的を絞った修正の提案に役立ちます。

効果的なプロンプトのヒント​

症状だけでなく、エラー全体を貼り付けてください。

「このサービスがクラッシュするのはなぜですか?」ではなく、

「私の Extend アプリは起動時に次のログを出して終了します。最も可能性の高い原因は何で、 どのように修正すればよいですか?」と聞いてみてください。

{"level":"ERROR","msg":"error unable to login using clientId and clientSecret","error":"401 Unauthorized"}

関連するソースファイルを含めてください。

「これは私のサービスの実装ファイルです。特定の入力に対して、このメソッドは codes.Internal を返します。 このケースを個別に処理すべきでしょうか?」

修正の前に説明を求めてください。

「PLUGIN_GRPC_SERVER_AUTH_ENABLED が何をするのか、そしてなぜローカル開発中に無効化しても 安全なのかを説明してください。」

MCP サーバー​

アプリのテンプレートには、.vscode/mcp.json に Model Context Protocol (MCP) サーバーの設定が同梱されており、AI アシスタントが AccelByte 固有の知識に直接アクセスできるようになっています。

サーバー提供する内容
ags-extend-sdk-mcp-serverAccelByte Extend SDK のシンボル、型、使用パターンに関する知識
ags-api-mcp-serverAGS REST API へのライブアクセス（環境内に AB_BASE_URL が必要）

リファレンス​

に最終更新
On this page