Local Debugging Guide for Extend Override — Go
This guide covers everything specific to debugging an Extend Override 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
- Extend Override debugging guide — Override-specific concepts for all languages
The examples in this guide use the matchmaking use case
(matchmaking-function-grpc-plugin-server-go). The project structure and debugging steps are
the same for every other Override use case — only the service file and proto differ. See the
service file reference table at the end of this guide.
Project structure
matchmaking-function-grpc-plugin-server-go/
├── main.go # Entry point — gRPC server, auth, metrics, tracing
├── proto.sh # Regenerate protobuf bindings
├── .env.template # Environment variable template
├── .vscode/
│ ├── launch.json # VS Code debug configuration
│ └── tasks.json # VS Code tasks (Run, Proto: Generate, etc.)
├── pkg/
│ ├── server/
│ │ ├── matchFunctionService.go # MatchFunctionServer — your override logic
│ │ ├── matchmaker.go # MatchMaker — core match logic
│ │ ├── gameRules.go # Rules parsing and validation
│ │ └── interfaces.go # MatchLogic interface
│ ├── common/
│ │ ├── authServerInterceptor.go # IAM token validation interceptor
│ │ ├── logging.go # gRPC middleware → slog bridge
│ │ └── tracerProvider.go # OpenTelemetry tracing setup
│ ├── pb/
│ │ ├── matchFunction.pb.go # Generated protobuf types (do not edit)
│ │ └── matchFunction_grpc.pb.go # Generated gRPC service code (do not edit)
│ └── proto/
│ └── matchFunction.proto # Protobuf definition
└── demo/
└── *.postman_collection.json # Postman collection for manual testing
Port numbers (constants in main.go):
| Port | Purpose |
|---|---|
6565 | gRPC server — receives calls from AGS |
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.
Confirming the service is up
You should see logs similar to:
{"time":"...","level":"INFO","msg":"starting app server"}
{"time":"...","level":"INFO","msg":"gRPC reflection enabled"}
{"time":"...","level":"INFO","msg":"gRPC server listening","address":"[::]:6565"}
{"time":"...","level":"INFO","msg":"prometheus metrics served at :8080/metrics"}
Verify gRPC reflection is reachable:
grpcurl -plaintext localhost:6565 list
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 common debugging 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 gRPC method being called | pkg/server/matchFunctionService.go — top of the relevant method |
| Match logic results | pkg/server/matchmaker.go — MakeMatches channel loop |
| Rules parsing | pkg/server/gameRules.go — RulesFromJSON |
| Auth / token validation failure | pkg/common/authServerInterceptor.go — interceptor entry |
| Service not starting at all | main.go — just before os.Exit(1) calls |
For conditional breakpoint syntax, see the Go language guide.
Reading logs
The service emits structured JSON logs via Go's slog. For jq log filtering, see the
Go language guide.
To stream only errors while the service runs:
go run main.go 2>&1 | jq 'select(.level == "ERROR")'
Testing the override manually
For grpcurl usage, see
Testing the override manually in the Override main
guide.
The demo/ directory contains a Postman collection (*.postman_collection.json) with
pre-built requests. Import it into Postman and update baseUrl and token for your local
setup.
Go-specific troubleshooting
Proto changes have no effect
Symptom: You edited pkg/proto/matchFunction.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 breakpoints to fire, always
use the VS Code launch config (or dlv debug) rather than go run.
PLUGIN_GRPC_SERVER_AUTH_ENABLED — auth rejects all calls
Symptom: Every gRPC call returns unauthenticated when testing locally.
Fix: Add PLUGIN_GRPC_SERVER_AUTH_ENABLED=false to your .env file. This disables the
IAM interceptor so you can test without a valid token. Remember to re-enable it before
deploying.
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.
This skill is available in each Override use case's template repository (see
Repositories).
For AI prompting tips and MCP server details, see Debugging with AI assistance in the Override main guide.
Service file reference by use case
The debugging workflow above applies to all Override use cases. Only the service file and proto vary. Use this table to find your implementation file:
| Use case | Go service file | Proto file |
|---|---|---|
| Matchmaking | pkg/server/matchFunctionService.go | pkg/proto/matchFunction.proto |
| Cloud Save Validator | See repo README | See repo README |
| Lootbox Roll | See repo README | See repo README |
| Profanity Filter | See repo README | See repo README |
| Revocation | See repo README | See repo README |
| Rotating Shop Items | See repo README | See repo README |
| Session DSM | See repo README | See repo README |
| Session Manager | See repo README | See repo README |
| Challenge Assignment | See repo README | See repo README |
For the repository link for each use case and language, see Extend Override repositories.