Local debugging guide — Go
This guide covers everything specific to debugging an Extend Service Extension app written in Go. 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
- Go language setup guide — Go prerequisites, Delve, jq, and Go-specific troubleshooting
Project structure
| File / Package | What it does |
|---|---|
main.go | Entry point — wires together gRPC server, gRPC-Gateway, metrics, tracing, and auth. |
pkg/service/myService.go | Your business logic — implements the gRPC service methods. |
pkg/storage/storage.go | Talks to AccelByte CloudSave to persist and retrieve data. |
pkg/common/authServerInterceptor.go | Validates every incoming request's IAM token and permission. |
pkg/common/logging.go | Bridges the gRPC middleware logger to Go's slog. |
pkg/common/tracerProvider.go | Sets up OpenTelemetry distributed tracing (Zipkin exporter). |
pkg/proto/service.proto | Defines the gRPC API — endpoints, request/response shapes, and required permissions. |
pkg/pb/ | Auto-generated Go code from .proto. Do not edit directly. |
Port numbers (constants in main.go):
| 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)
go run main.go
From VS Code
Use Terminal → Run Task → "Run: Service".
This task is defined in .vscode/tasks.json and prompts you for BASE_PATH if it is not
already set.
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:
{
"name": "Debug: Service",
"type": "go",
"request": "launch",
"mode": "auto",
"program": "${workspaceFolder}",
"envFile": "${workspaceFolder}/.env",
"cwd": "${workspaceFolder}",
"console": "integratedTerminal"
}
Follow the attaching the debugger steps in the generic guide, then select "Debug: Service" from the dropdown.
Other IDEs — Delve headless mode
Start Delve in headless mode so your IDE can connect to it:
dlv debug --headless --listen=:2345 --api-version=2 .
Then configure your IDE to attach to localhost:2345 via DAP (Debug Adapter Protocol).
Where to put breakpoints
| What you want to investigate | File and location |
|---|---|
| A specific REST endpoint being called | pkg/service/myService.go — top of the relevant method |
| Auth/token validation failure | pkg/common/authServerInterceptor.go — NewUnaryAuthServerIntercept |
| Data not saving or loading correctly | pkg/storage/storage.go — SaveGuildProgress / GetGuildProgress |
| Service not starting at all | main.go — just before os.Exit(1) calls |
For conditional breakpoint syntax, see the Go language guide.
Reading logs
For jq log filtering, see the
Go 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.
Go-specific troubleshooting
Proto changes have no effect
Symptom: You edited pkg/proto/service.proto but nothing changed at runtime.
Cause: The generated stubs in pkg/pb/ have not been regenerated.
Fix: Run the "Proto: Generate" VS Code task, or:
./proto.sh
Then restart the service.
go run vs the debugger launch config
go run main.go compiles without debug information. When you need to attach a debugger, always
use the VS Code launch config (or dlv debug) rather than go run.
Checking for port conflicts
See Checking for port conflicts in the Go 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.