ローカルデバッグガイド — Python
This guide covers everything specific to debugging an Extend Service Extension app written in Python. For general debugging concepts — environment setup, VS Code debug workflow, log reading, and common issues — see:
- Extend local debugging guide — common concepts for all Extend app types
- Python language setup guide — Python prerequisites, debugpy, jq, and Python-specific troubleshooting
Project structure
src/
└── app/
├── __main__.py # Entry point
├── services/
│ └── my_service.py # Your business logic
└── ...
proto/
└── app/
└── service.proto # gRPC API definition
| File | What it does |
|---|---|
src/app/__main__.py | Entry point — starts the gRPC server and gRPC-Gateway. |
src/app/services/my_service.py | Your business logic — implements the gRPC service methods. |
src/accelbyte_grpc_plugin/interceptors/authorization.py | Validates every incoming request's IAM token and permission. |
proto/app/service.proto | Defines the gRPC API — endpoints, request/response shapes, and required permissions. |
Port numbers:
| Port | Purpose |
|---|---|
6565 | gRPC server (internal — used by gRPC-Gateway) |
8000 | gRPC-Gateway HTTP/REST — call this from a browser, Postman, or curl |
8080 | Prometheus metrics endpoint (/metrics) |
Running the service locally
From the terminal
# Export all variables from your .env file
export $(grep -v '^#' .env | xargs)
python -m app
From VS Code
Use Terminal → Run Task → "Run: Service".
This task is defined in .vscode/tasks.json and loads the .env file for you automatically.
Confirming the service is up
You should see logs like:
{"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"}
Open http://localhost:8000<BASE_PATH>/apidocs/ in your browser to verify Swagger UI is live.
Attaching the debugger
VS Code (recommended)
The repository ships with a ready-to-use launch configuration in .vscode/launch.json that
uses debugpy:
{
"name": "Debug: Service",
"type": "python",
"request": "launch",
"module": "app",
"cwd": "${workspaceFolder}/src",
"envFile": "${workspaceFolder}/.env"
}
Follow the attaching the debugger steps in the generic guide, then select "Debug: Service" from the dropdown.
Other IDEs — remote debugpy attach
Start the app with debugpy listening on port 5678:
export $(grep -v '^#' .env | xargs)
python -m debugpy --listen 5678 --wait-for-client -m app
The process pauses until a debugger connects. Attach from PyCharm, a remote debugger, or a second VS Code window using:
{
"name": "Attach: Remote",
"type": "python",
"request": "attach",
"connect": { "host": "localhost", "port": 5678 }
}
Where to put breakpoints
| What you want to investigate | File and location |
|---|---|
| A specific REST endpoint being called | services/my_service.py — top of the relevant method |
| Auth/token validation failure | accelbyte_grpc_plugin/interceptors/authorization.py — the request interception point |
| Data not saving or loading correctly | The storage or repository module used in your service |
| Service not starting at all | app/__main__.py — the server setup block |
For conditional breakpoint syntax, see the Python language guide.
Reading logs
For jq log filtering, see the
Python language guide.
Testing endpoints manually
For curl and grpcurl usage, see
Testing with grpcurl in the generic guide.
For Swagger UI testing (SE-specific), see Testing endpoints manually in the SE main guide.
Python-specific troubleshooting
Proto changes have no effect
Symptom: You edited proto/app/service.proto but the generated stubs haven't updated.
Fix: Re-run the proto generation script:
./proto.sh
Restart the service after re-generation.
ModuleNotFoundError for app
Symptom: Running python -m app gives ModuleNotFoundError: No module named 'app'.
Cause: The working directory is wrong. The module lives under src/.
Fix:
cd src
python -m app
Or set PYTHONPATH:
PYTHONPATH=src python -m app
debugpy not found
Symptom: VS Code says debugpy is not installed.
Fix:
pip install debugpy
# If using a virtual environment, activate it first:
source .venv/bin/activate && pip install debugpy
Checking for port conflicts
See Checking for port conflicts in the Python language guide.
AI assistance
The app template ships with a Claude agent skill at
.claude/skills/debugging-guide/SKILL.md.
For AI prompting tips and MCP server details, see Debugging with AI assistance in the generic guide.