docs: add debugging guide for game server integration by hloeffler · Pull Request #275 · GameFabric/docs

Hauke Löffler (hloeffler) · 2026-04-20T15:36:17Z

Summary

Adds a new "Debugging game server integration" page under Monitoring (src/multiplayer-servers/monitoring/debugging.md)
Updates the Monitoring sidebar to include the new page

What's in the guide

Recommends using Vessels for integration and debugging (single game server, UI restart, logs in UI)
How to view container logs: Vessel UI for Vessels, Grafana (Current Gameservers → Gameserver Single Instance dashboard) for Formations/Armadas
How to inspect the Agones SDK game server object from within the pod
How to check environment variables for common misconfigurations
How to build and deploy a lightweight debugger sidecar that prints env vars and polls the game server object every 10 seconds (full Dockerfile and script included)
How to debug the allocation flow by setting LOG_LEVEL=debug on the Allocation Sidecar

Copilot

Pull request overview

Adds a new Monitoring documentation page to help users debug game server integrations, and wires it into the Monitoring sidebar so it’s discoverable within the VitePress site structure.

Changes:

Added a new guide: Debugging game server integration (logs, Agones SDK inspection, env var checks, debugger sidecar, allocation debugging).
Updated the Monitoring sidebar to include the new Debugging page.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

File	Description
`src/multiplayer-servers/monitoring/sidebar.json`	Adds a new sidebar entry pointing to the new debugging guide.
`src/multiplayer-servers/monitoring/debugging.md`	Introduces a new end-to-end debugging guide for integration issues, including operational steps and example sidecar tooling.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

Copilot · 2026-04-21T07:43:17Z

+echo "hello from the debugger"
+echo
+echo "ENV"
+env


The example debugger sidecar script prints the full environment (env), which is very likely to include secrets (for example allocation tokens) and can accidentally leak them into shared/retained logs. Consider changing the example to print only the specific non-secret variables you need for debugging, or demonstrate redaction/masking of known sensitive keys by default so the "safe" path is the one people copy/paste.

that's a valid point to make, even when trying to debug. Instructing users to do so goes against general security best practices. It also opens up a whole can of worms w.r.t. the blast radius of such a logging behaviour. Instead of "instructing" users to print their ENVs, give them pointers as to what they can do in such scenarios in a textual way: if they want to print their envs, its entirely on them to make that decision

Christian R (antiphp) · 2026-04-21T07:53:20Z

+FROM ubuntu:22.04
+
+# 2. Pre-install requirements.
+RUN apt-get update \
+        && apt-get install -y gnupg ca-certificates curl jq \
+        && apt-get clean -y
+
+# 3. Prepare a working directory and permissions.
+RUN mkdir /app
+RUN useradd -m -u 1000 debugger
+RUN chown debugger:debugger /app


Are the permissions required for what your debugger does?

Why ubuntu:22.04. That's like 4 years old, use latest?

I personally would have chosen a more compact image/approach. Like, "you just need bash, here you go with alpine/busybox. You need full-scale development tools, better choose "ubuntu:latest" and install custom packages like this...".

ubuntu:22.04 is still supported
and switching to 24.04 will break the build
permissions are needed for stuff,
also we have: https://docs.gamefabric.com/multiplayer-servers/getting-started/building-a-container-image#create-a-dockerfile

Ubuntu 24:04 only breaks the build because the image now includes a default non-root user at UID 1000 by default. You can still use ubuntu 24.04, just don't do useradd -u 1000.

Brendan Le Glaunec (Ullaakut) · 2026-04-21T07:19:47Z

+
+## Use Vessels for integration and debugging
+
+Even if your game ultimately requires [Armadas](/multiplayer-servers/getting-started/glossary#armada), use a [Vessel](/multiplayer-servers/getting-started/glossary#vessel) during integration and debugging. Vessels give you a single game server that you can restart directly from the UI, and container logs are visible in the UI without any additional setup. This makes the feedback loop much faster than working with Armadas.


I would say start with a Vessel, but still run tests with Armadas as well before deploying the real stuff since there are some fundamental differences in configuration etc that they'd still likely need to experiment with a bit. WDYT?

yes,
but for allocation, vessel will also work and is way easierer

Brendan Le Glaunec (Ullaakut) · 2026-04-21T07:23:15Z

+
+## Inspecting the game server object
+
+The Agones SDK exposes a local REST endpoint inside every game server pod. You can query it from within the pod to see the current game server state, addresses, ports, labels, and annotations:


How can users get access to inside of the pod? Is that described somewhere?

they can't no feature at the moment

Then I'd say we need to change this phrasing because thats what it implies to me 😄

Brendan Le Glaunec (Ullaakut) · 2026-04-21T09:49:42Z

+## Using a debugger sidecar
+
+If you cannot easily add diagnostic commands to your game server, you can run a lightweight sidecar container that automatically prints environment variables on start and polls the Agones SDK game server object every 10 seconds. Because this output can include secrets, use it only in non-production environments or redact sensitive values before sending logs to shared systems.
+
+### Building the debugger sidecar image
+
+Create the following two files and build the container image.


I would emphasize that this is only an example and that they can write a debugger sidecar however they wish, including safer solutions than this

Co-authored-by: Christian R <antiphp@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

Copilot · 2026-04-21T10:33:26Z

+curl "http://localhost:${AGONES_SDK_HTTP_PORT}/gameserver" | jq '.'
+```
+
+This endpoint is only accessible from within the pod. The `AGONES_SDK_HTTP_PORT` environment variable is always set in every container in the pod and defaults to `9358`.


This sentence claims AGONES_SDK_HTTP_PORT is always set in every container in the pod. Elsewhere the docs state it's set in “your container” by Agones, which is less absolute; if sidecars don't reliably get this env var, the current wording is inaccurate. Consider softening the guarantee and/or suggesting a fallback to the default port when the variable isn't present.

Suggested change

This endpoint is only accessible from within the pod. The `AGONES_SDK_HTTP_PORT` environment variable is always set in every container in the pod and defaults to `9358`.

This endpoint is only accessible from within the pod. Agones sets `AGONES_SDK_HTTP_PORT` for the game server container. If that variable is not present in the container you are using, use the default port `9358`.

Reword Vessels section to recommend also testing with Armadas before production. Add Vessel UI caveats for log volume and previous container runs. Broaden Grafana log scope beyond Formations/Armadas. Clarify that in-pod commands run from entrypoint scripts or sidecars, not via exec. Show curl without jq as primary example. Replace inline warning with admonition blocks, note env unavailability in distroless images, and remove redundant "pay special attention" line. Rename "debugger sidecar" to "debug sidecar" throughout. Emphasize the sidecar is only an example. Add --platform linux/amd64 to docker build and link to existing Dockerfile guide.

Alex Bartolomey (zoomoid) · 2026-04-21T15:00:06Z

+echo "hello from the debugger"
+echo
+echo "ENV"
+env


that's a valid point to make, even when trying to debug. Instructing users to do so goes against general security best practices. It also opens up a whole can of worms w.r.t. the blast radius of such a logging behaviour. Instead of "instructing" users to print their ENVs, give them pointers as to what they can do in such scenarios in a textual way: if they want to print their envs, its entirely on them to make that decision

Alex Bartolomey (zoomoid) · 2026-04-21T15:01:25Z

+FROM ubuntu:22.04
+
+# 2. Pre-install requirements.
+RUN apt-get update \
+        && apt-get install -y gnupg ca-certificates curl jq \
+        && apt-get clean -y
+
+# 3. Prepare a working directory and permissions.
+RUN mkdir /app
+RUN useradd -m -u 1000 debugger
+RUN chown debugger:debugger /app


Ubuntu 24:04 only breaks the build because the image now includes a default non-root user at UID 1000 by default. You can still use ubuntu 24.04, just don't do useradd -u 1000.

Alex Bartolomey (zoomoid) · 2026-04-21T15:02:40Z

+1. Navigate to your [Formation](/multiplayer-servers/getting-started/glossary#formation), [Vessel](/multiplayer-servers/getting-started/glossary#vessel), [ArmadaSet](/multiplayer-servers/getting-started/glossary#armadaset), or [Armada](/multiplayer-servers/getting-started/glossary#armada) configuration.
+1. In the **Sidecars** section, select **Create from scratch**.
+1. Set the container image to your debug sidecar image.
+1. Save your changes.


all the same numbers?

This is on purpose, doing this renders the markdown correctly and makes it easier to add/remove/reorder items in the future

It's called lazy numbering

However, if the list is small, and you don’t anticipate changing it, prefer fully numbered lists, because it is nicer to read in source.

I suppose 4 qualifies as "long"?

Considering how often our docs are shifting in this repo I'd personally recommend always doing lazy numbering here :p Some less volatile docs I'd be fine with regular numbered lists. But this whole place is chaos incarnate 😄

docs: add debugging guide for game server integration

5db323b

Copilot AI review requested due to automatic review settings April 20, 2026 15:36

Hauke Löffler (hloeffler) requested a review from a team as a code owner April 20, 2026 15:36

Copilot started reviewing on behalf of Hauke Löffler (hloeffler) April 20, 2026 15:36 View session

Copilot AI reviewed Apr 20, 2026

View reviewed changes

Update src/multiplayer-servers/monitoring/debugging.md

376d959

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings April 20, 2026 15:52

Copilot started reviewing on behalf of Hauke Löffler (hloeffler) April 20, 2026 15:53 View session

Hauke Löffler (hloeffler) and others added 2 commits April 20, 2026 17:53

Update src/multiplayer-servers/monitoring/debugging.md

81ebe12

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update src/multiplayer-servers/monitoring/debugging.md

d0f8124

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot AI reviewed Apr 20, 2026

View reviewed changes

Comment thread src/multiplayer-servers/monitoring/debugging.md Outdated

Comment thread src/multiplayer-servers/monitoring/debugging.md

Comment thread src/multiplayer-servers/monitoring/debugging.md Outdated

Update src/multiplayer-servers/monitoring/debugging.md

a1970f5

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings April 21, 2026 07:39

Copilot started reviewing on behalf of Hauke Löffler (hloeffler) April 21, 2026 07:39 View session

Copilot AI reviewed Apr 21, 2026

View reviewed changes

Christian R (antiphp) reviewed Apr 21, 2026

View reviewed changes

Brendan Le Glaunec (Ullaakut) reviewed Apr 21, 2026

View reviewed changes

Update src/multiplayer-servers/monitoring/debugging.md

d2b51e3

Co-authored-by: Christian R <antiphp@users.noreply.github.com>

Copilot AI review requested due to automatic review settings April 21, 2026 10:29

Copilot AI reviewed Apr 21, 2026

View reviewed changes

Alex Bartolomey (zoomoid) requested changes Apr 21, 2026

View reviewed changes


		## Use Vessels for integration and debugging

		Even if your game ultimately requires [Armadas](/multiplayer-servers/getting-started/glossary#armada), use a [Vessel](/multiplayer-servers/getting-started/glossary#vessel) during integration and debugging. Vessels give you a single game server that you can restart directly from the UI, and container logs are visible in the UI without any additional setup. This makes the feedback loop much faster than working with Armadas.


		## Inspecting the game server object

		The Agones SDK exposes a local REST endpoint inside every game server pod. You can query it from within the pod to see the current game server state, addresses, ports, labels, and annotations:

	This endpoint is only accessible from within the pod. The `AGONES_SDK_HTTP_PORT` environment variable is always set in every container in the pod and defaults to `9358`.
	This endpoint is only accessible from within the pod. Agones sets `AGONES_SDK_HTTP_PORT` for the game server container. If that variable is not present in the container you are using, use the default port `9358`.

Conversation

Hauke Löffler (hloeffler) commented Apr 20, 2026

Summary

What's in the guide

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!