Local Debugging Guide for Extend Override

Last updated on July 14, 2026

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

概要​

このガイドでは、ローカルマシンで Extend Override アプリをデバッグする手順を説明します。

共通のデバッグ概念

すべての Extend アプリタイプに共通するデバッグ概念（環境変数の設定、VS Code デバッグワークフロー、ログの読み方、よくある起動エラー）については、 Extend ローカルデバッグガイドを参照してください。

Extend Override には 9 つのユースケース（matchmaking、cloud-save-validator、lootbox-roll、 profanity-filter、revocation、rotating-shop-items、session-dsm、session-manager、 challenge-assignment）があります。デバッグワークフロー（ポート、認証、実行/アタッチ/テストのパターン、proto の再生成）は、すべてのユースケースで共通です。本ガイドではそれらすべてを扱います。使用している ユースケースに固有のサービスファイルや proto については、各言語のガイドにある参照テーブルを 確認してください。

このガイドでは Visual Studio Code（VS Code） を中心に説明しますが、内容はどのエディタや IDE にも 適用できます。

言語ごとの設定（前提条件、プロジェクト構成、実行コマンド、デバッガー設定）については、 以下から使用する言語のガイドに直接進んでください。

サービスを通じた呼び出しの流れ​

すべての Extend Override アプリは、言語やユースケースにかかわらず同じレイヤー構成で構築されています。 この構成を理解することで、問題の発生箇所を特定しやすくなります。

AGS service (intercepts operation)
       │  gRPC  (with IAM bearer token)
       ▼
 gRPC Server  (port 6565)   ← your override logic lives here
       │
       ▼
 Returns override result to AGS

ポートの概要:

ポート用途
6565gRPC サーバー — AGS からの呼び出しを受信
8080Prometheus メトリクスエンドポイント（/metrics）

問題が発生した場合は、レイヤーごとに順を追って調査してください。

症状最も可能性の高いレイヤー最初に確認すべき箇所
サービスが起動しない環境変数 / 認証情報.env ファイル、IAM クライアント認証情報
Override がトリガーされないAdmin Portal での登録Extend の設定、override のバインディング
すべての呼び出しで認証エラーが発生するPLUGIN_GRPC_SERVER_AUTH_ENABLEDローカル開発時は .env で false に設定
Override はトリガーされるが結果が誤っているビジネスロジックoverride メソッドの実装
デバッガーが一度も一時停止しないポートの競合またはビルドモードポート 6565 で動作中のプロセスを確認
proto の変更が反映されない生成コードが古いprotobuf バインディングを再生成

環境設定​

共通の変数（AB_BASE_URL、AB_CLIENT_ID、AB_CLIENT_SECRET、LOG_LEVEL）と、 .env ファイルの作成・確認方法については、Extend アプリの共通デバッグガイドにある 環境設定を参照してください。

Extend Override 固有の変数: PLUGIN_GRPC_SERVER_AUTH_ENABLED​

Extend Event Handler とは異なり、Extend Override はすべての受信 gRPC 呼び出しに対して IAM ベアラートークンを検証します。デフォルトでは、これは有効になっています。

PLUGIN_GRPC_SERVER_AUTH_ENABLED=true
変数用途ローカルデバッグでの推奨値
PLUGIN_GRPC_SERVER_AUTH_ENABLEDgRPC 呼び出しに対する IAM トークン検証を有効化するローカル開発中は認証をスキップするために false

PLUGIN_GRPC_SERVER_AUTH_ENABLED=true の場合、grpcurl やテストクライアントからのすべての呼び出しに 有効な IAM ベアラートークンを含める必要があります。認証の動作を特にデバッグしている場合を除き、 ローカルテストを簡略化するために false に設定してください。

BASE_PATH は不要

Extend Override では BASE_PATH 変数を使用しません。gRPC-Gateway や HTTP/REST レイヤーは存在せず、AGS は gRPC サーバーを直接呼び出します。

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

VS Code のタスクとターミナルでの実行方法については、Extend アプリの共通デバッグガイドにある サービスをローカルで実行するを 参照してください。

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

サービスが起動すると、以下のようなログが表示されます（正確な形式は言語によって異なります）。

{"level":"INFO","msg":"gRPC server listening","address":"[::]:6565"}
{"level":"INFO","msg":"prometheus metrics served at :8080/metrics"}

gRPC リフレクションが機能していることも確認できます。

grpcurl -plaintext localhost:6565 list

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

デバッガーのアタッチ​

VS Code でのデバッガーのアタッチ手順については、Extend アプリの共通デバッグガイドにある VS Code でデバッガーをアタッチするを 参照してください。

Override 固有の .vscode/launch.json 設定や、VS Code 以外の環境での設定については、 言語別ガイドを参照してください。

ブレークポイントの設定と状態の確認​

ブレークポイントの設定方法、VS Code のデバッグパネルの使用方法、コードのステップ実行、条件付き ブレークポイントの記述方法については、Extend アプリの共通デバッグガイドにある ブレークポイントの設定と状態の確認を 参照してください。

Override サービスファイルで推奨されるブレークポイントの配置場所や、言語ごとの条件付き構文の例については、 言語別ガイドを参照してください。

ログの読み方​

構造化された JSON ログ形式、ログレベル、gRPC 呼び出しのペア、jq の使用方法については、 Extend アプリの共通デバッグガイドにある ログの読み方と理解を参照してください。

言語ごとの jq パイプコマンドについては、言語別ガイドを参照してください。

よくある問題​

すべての Extend アプリに共通するよくある問題（認証情報エラー、401 Unauthenticated、ブレークポイントが 一度もヒットしない、など）については、Extend アプリの共通デバッグガイドにある よくある問題を参照してください。

以下の問題は Extend Override に固有のものです。

Override がトリガーされない​

症状: gRPC サーバーは正常に動作していますが、ブレークポイントが一度もヒットせず、ログにも受信呼び出しが 表示されません。

原因: override アプリが Admin Portal 上で対象の AGS 機能にバインドされていません。

修正方法:

  1. Admin Portal に移動します。
  2. Extend > 該当するユースケース（例: Matchmaking）に移動します。
  3. アプリがデプロイされ、有効になっており、正しい namespace にバインドされていることを確認します。
  4. ローカルでテストする場合は、AGS 環境がローカルサービスへの呼び出しをルーティングするように設定されて いることを確認します（トンネルやローカルネットワークルートなど）。

すべての呼び出しで認証エラーが発生する — PLUGIN_GRPC_SERVER_AUTH_ENABLED​

症状: 有効な IAM トークンを使用していても、すべての gRPC 呼び出しが unauthenticated または permission denied を返します。

原因: 認証インターセプターが有効になっていてトークンを拒否している、または .env の IAM 認証情報が間違っています。

修正方法: ローカルデバッグの場合は、.env で PLUGIN_GRPC_SERVER_AUTH_ENABLED=false を設定し、 トークン検証を完全にバイパスします。認証を有効にしたままにする必要がある場合は、.env ファイル内の AB_CLIENT_ID、AB_CLIENT_SECRET、AB_BASE_URL を確認してください。

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

症状: .proto ファイルを編集しましたが、サービスの動作が変わりません。

原因: 生成されたコードスタブが再生成されていません。

修正方法: 「Proto: Generate」 VS Code タスクを実行します（利用可能な場合）。または、./proto.sh を直接実行（Go と Python の場合）するか、./gradlew generateProto（Java の場合）を実行するか、 プロジェクトを再ビルド（C# の場合）します。その後、サービスを再起動します。

Override を手動でテストする​

Swagger UI や HTTP エンドポイントは存在しません。AGS は gRPC サーバーを直接呼び出します。

override された AGS 機能をトリガーする​

最も現実的なテスト方法は、override が登録されている AGS 機能をトリガーすることです。具体的な手順は ユースケースによって異なります。各ユースケースのカスタマイズガイドには、ユースケース固有の呼び出し手順が 記載されています。

grpcurl で gRPC サーバーを直接テストする​

grpcurl を使ったテストについては、Extend アプリの共通デバッグガイドにある grpcurl でのテストを参照してください。

gRPC リフレクションを使用して利用可能なサービスを確認します。

grpcurl -plaintext localhost:6565 list

特定のメソッドを呼び出します（matchmaking の例 — 使用しているユースケースに応じてサービス名と メソッド名を調整してください）。

grpcurl -plaintext \
  -d '{"rules": {"json": "{}"}}' \
  localhost:6565 \
  accelbyte.matchmakingv2.matchfunction.MatchFunction/GetStatCodes

PLUGIN_GRPC_SERVER_AUTH_ENABLED=true の場合は、すべての grpcurl 呼び出しに -H "Authorization: Bearer <your-token>" を追加してください。

AI を活用したデバッグ​

任意のセクション

チームで AI ツールを使用していない場合、または職場で AI の使用が推奨されていない場合は、このセクションを スキップしてください。このガイドの他のすべてのセクションは完全に自己完結しており、AI アシスタントを 必要としません。

Claude Code、GitHub Copilot などの AI コーディングアシスタントは、デバッグの相棒として、 不慣れなコードの説明、ログの解析、的確な修正の提案などに活用できます。

デバッグスキルの使用​

各 Extend Override アプリのテンプレートリポジトリには、.claude/skills/debugging-guide/SKILL.md にすぐに使えるエージェントスキルが用意されています。スキルとは、AI に対して特定の分野（この場合は Extend Override アプリのデバッグ）を支援する方法を正確に指示する一連の指示です。

このスキルファイルは、各ユースケースのテンプレートリポジトリで利用できます（全リストは リポジトリを参照してください）。スキルが有効になったら、AI チャットで 以下のいずれかを入力して呼び出します。

目的入力内容
発生している問題をデバッグする/debugging-guide Go — getting unauthenticated on every call
デバッグガイドを作成または更新する/debugging-guide write Go
AI に判断させる問題を自然な言葉で説明する — AI が適切なモードを選択します
互換性

エージェントスキルは Claude Code で標準的に動作します。他の AI ツールや IDE 拡張機能を使用する場合は、 Agent Skills オープンスタンダードに対応しているかどうかを確認してください。 使用しているツールがスキルに対応していない場合は、.claude/skills/debugging-guide/SKILL.md の内容を コピーして、チャットセッションの最初のメッセージ（またはシステムプロンプト）として貼り付けてください。

以下は、独自の Extend Override リポジトリで .claude/skills/debugging-guide/SKILL.md として 調整・保存できる参考用のスキルファイルです。

デバッグスキルの全文を表示（SKILL.md）
---
name: debugging-guide
description: >
  Expert guide writer and debugging assistant for AccelByte Extend Override apps.
  Use when a developer asks for help debugging their Override service, diagnosing startup or
  runtime errors, understanding logs, setting up a debugger, or when writing or updating a
  DEBUGGING_GUIDE.md for an Extend Override app. Covers Go but the workflow applies to other
  supported languages (Python, C#, Java).
argument-hint: "[language] [brief issue description or 'write guide']"
allowed-tools: Read, Grep, Glob, Bash(go *), Bash(dlv *), Bash(ss *), Bash(grpcurl *), Bash(jq *)
---

# Debugging Guide Skill — Extend Override

You are an expert backend developer and technical writer specializing in AccelByte Gaming
Services (AGS) Extend Override apps. Your two modes of operation are:

1. **Debug Mode** — Help a developer diagnose and fix a real issue in their running service.
2. **Write Mode** — Author or update a `DEBUGGING_GUIDE.md` for an Extend Override repository.

Detect which mode is needed from `$ARGUMENTS`. If the argument mentions a specific error,
log output, or symptom, use Debug Mode. If it mentions "write", "guide", or "document", use
Write Mode. If ambiguous, ask one clarifying question.

---

## Architecture Context

Every Extend Override app shares this architecture:

\`\`\`
AGS service (intercepts operation)
       │  gRPC  (with IAM bearer token)
       ▼
 gRPC Server  (port 6565)   ← your override logic lives here
       │
       ▼
 Returns override result to AGS
\`\`\`

Key environment variables:

| Variable | Purpose |
|---|---|
| `AB_BASE_URL` | AccelByte environment base URL |
| `AB_CLIENT_ID` / `AB_CLIENT_SECRET` | OAuth client credentials |
| `PLUGIN_GRPC_SERVER_AUTH_ENABLED` | `false` to skip IAM token validation locally |
| `LOG_LEVEL` | `debug` \| `info` \| `warn` \| `error` |

---

## Debug Mode

### Step 1 — Identify the layer where the failure occurs

- Service fails to **start** → environment variables and IAM login.
- All calls return **unauthenticated** → set `PLUGIN_GRPC_SERVER_AUTH_ENABLED=false` locally.
- Override is **never triggered** → check Admin Portal binding.
- Returns **wrong result** → business logic in the service implementation file.
- Debugger **won't pause** → port conflicts or build mode.
- **Proto changes ignored** → regenerate bindings.

### Step 2 — Collect evidence

1. Ask for full log output at `LOG_LEVEL=debug`. Look for `"level":"ERROR"` lines.
2. Read the source files referenced in the error before suggesting a fix.
3. Check environment: `printenv | grep -E 'AB_|PLUGIN_GRPC|LOG_LEVEL'`
4. Check ports: `ss -tlnp | grep -E '6565|8080'`

### Step 3 — Common-issue checklist

| Symptom | Likely cause | Where to look |
|---|---|---|
| `unable to login using clientId and clientSecret` | Wrong credentials or unreachable `AB_BASE_URL` | Entry point → OAuth login |
| All calls return `unauthenticated` | Auth interceptor active with missing token | Set `PLUGIN_GRPC_SERVER_AUTH_ENABLED=false` |
| Override never fires | App not bound in Admin Portal | Admin Portal Extend configuration |
| Override returns wrong result | Business logic error | Service implementation file |
| Breakpoints never hit | Port conflict or auth blocking before breakpoint | Disable auth, check port 6565 |
| Proto changes have no effect | Generated code not regenerated | Run `./proto.sh` or equivalent |

### Step 4 — Suggest a minimal fix

- Explain *why* the fix works.
- Read the file first, then show the exact change.
- Provide a verification step after every fix.

### Step 5 — Verify

\`\`\`bash
# Confirm service starts cleanly
go run main.go 2>&1 | jq 'select(.level == "ERROR")'

# Confirm gRPC layer is reachable
grpcurl -plaintext localhost:6565 list

# Call a specific method (adjust service and method for your use case)
grpcurl -plaintext \
  -d '{"rules": {"json": "{}"}}' \
  localhost:6565 \
  accelbyte.matchmakingv2.matchfunction.MatchFunction/GetStatCodes
\`\`\`

---

## Write Mode

### Audience

Junior developers and game developers with limited backend experience. Avoid assuming knowledge
of gRPC, protobuf, or IAM. Use plain language. VS Code-centric but include notes for other IDEs.

### Required sections

1. Overview + architecture diagram
2. Project structure reference (file-to-responsibility table, port table)
3. Prerequisites (language-specific)
4. Environment setup (.env, key variables, when to disable auth locally)
5. Running the service (terminal + VS Code task)
6. Attaching the debugger (VS Code launch config, other IDEs/headless)
7. Breakpoints and inspection (placement table, stepping shortcuts, conditional breakpoints)
8. Reading logs (format, levels, gRPC pairs, jq)
9. Common issues (symptom / cause / fix per issue)
10. Testing manually (grpcurl, trigger AGS feature, Postman collection)
11. AI-assisted debugging (this skill, MCP servers, prompting tips)
12. Tips and best practices

### Before writing, always read first

1. Existing `DEBUGGING_GUIDE.md` if present — update, do not replace accurate content.
2. `main.go` (or equivalent entry point) for ports, startup sequence, and env vars.
3. Service implementation file to understand the business logic layer.
4. `.vscode/launch.json` for the debug configuration name and settings.
5. The `.proto` file for service method names.

MCP サーバー​

アプリテンプレートには、.vscode/mcp.json（存在する場合）に MCP サーバーの設定が含まれています。 これらにより、AI アシスタントは AccelByte 固有の知識に直接アクセスできます。

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

Extend アプリのデバッグにおける一般的な AI プロンプトのヒントについては、Extend アプリの共通デバッグ ガイドにあるAI を活用したデバッグを 参照してください。

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

ログレベル、認証の無効化、条件付きブレークポイント、VS Code パネル、ポートの確認などの一般的な ヒントについては、Extend アプリの共通デバッグガイドにある ヒントとベストプラクティスを参照してください。

Extend Override 固有のヒント:

  • ローカル開発では認証を無効にする。 ビジネスロジックをデバッグしている間は、.env で PLUGIN_GRPC_SERVER_AUTH_ENABLED=false を設定してください。デプロイ前に認証を再度有効にして、 エンドツーエンドで動作を確認してください。

  • .proto を変更するたびに proto バインディングを再生成する。 再生成せずに .proto ファイルを 編集することは、わかりにくいコンパイルエラーや実行時エラーの最も一般的な原因の一つです。正確な 再生成コマンドについては、使用している言語のガイドを参照してください。

  • 簡単な手動テストには grpcurl を使用する。 HTTP/REST レイヤーが存在しないため、grpcurl は 完全な AGS フローをトリガーせずに単一の呼び出しを実行して結果を確認する最も速い方法です。

言語別ガイド​

上記のセクションでは、すべての言語およびすべての Override ユースケースに共通する概念とワークフローを 説明しています。設定手順、プロジェクト構成、実行コマンド、デバッガー設定、言語固有のトラブルシューティング については、使用している言語専用のガイドを参照してください。

参考資料​

に最終更新
On this page