feat(observability): Prometheus /metrics endpoint + Grafana dashboard under Game Jams folder #62

New issue

Open

opened 2026-07-13 23:16:35 +02:00 by bosun · 0 comments

bosun commented

2026-07-13 23:16:35 +02:00

Owner

Motivation

Breakout has a blackbox probe (https://jam.frankenbit.de/breakout/) via alcatraz-infra's alloy config, so service-probe-down fires if the ingress path breaks. That's the liveness contract. It's not game telemetry — nothing about sessions started, levels loaded, bricks broken, deaths, etc.

Cellblock's precedent (Engineer 47e6 contract, cellblock#10) established the pattern for jam-side game servers exposing /metrics scraped by alloy on the docker network:

cellblock_active_matches, cellblock_connected_clients (gauges)
cellblock_matches_started_total, cellblock_matches_ended_total{outcome} (counters)
cellblock_lines_cleared_total, cellblock_garbage_sent_total (counters)

Plus a dedicated Grafana dashboard (CELLBLOCK live stats, tagged cellblock/jam).

Operator direction (2026-07-13): both game-jam projects should live together under a Game Jams folder in Grafana — Cellblock moves in, Breakout joins once it has metrics.

Scope

Two bundled pieces of work:

/metrics endpoint on the Breakout server. Static-site currently, so this needs a small sidecar or a lightweight metrics endpoint on whatever serves index.html + assets. Metric contract to define — likely:
- breakout_active_sessions (gauge) — concurrent players
- breakout_sessions_started_total (counter)
- breakout_levels_completed_total{level} (counter)
- breakout_deaths_total{level} (counter)
- breakout_bricks_broken_total{type} (counter — regular, fortress, lockdown, whatever the type-set is)
- Contract-of-record placed in the repo (per Engineer's precedent — CONTRACT.md extension or a dedicated docs/metrics.md).
Grafana dashboard. Under the new Game Jams folder alongside Cellblock. Modeled on CELLBLOCK live stats. Provisioned via /srv/docker/monitoring/grafana/dashboards/Game Jams/breakout.json (once foldersFromFilesStructure: true flip lands in the provisioning config).

Verification AC

/metrics endpoint reachable from alloy at container:port
alloy config extended with a prometheus.scrape "breakout" block (mirroring the cellblock block at /srv/docker/monitoring/alloy/config.alloy)
Metric contract documented in-repo
Grafana Game Jams folder created (via provisioning foldersFromFilesStructure: true flip)
Cellblock dashboard moved into Game Jams folder
Breakout dashboard created in Game Jams folder
Both dashboards render live data

cellblock#10 — precedent for game-server /metrics contract
alcatraz-infra alloy config — where the scrape block gets added
alcatraz-infra grafana provisioning — where the folder flip lands

Anchor

Filed 2026-07-13 by Bosun on operator directive during post-Game-Jam-II follow-up planning session.

## Motivation Breakout has a blackbox probe (`https://jam.frankenbit.de/breakout/`) via alcatraz-infra's alloy config, so `service-probe-down` fires if the ingress path breaks. That's the liveness contract. It's not game telemetry — nothing about sessions started, levels loaded, bricks broken, deaths, etc. Cellblock's precedent (Engineer 47e6 contract, cellblock#10) established the pattern for jam-side game servers exposing `/metrics` scraped by alloy on the docker network: - `cellblock_active_matches`, `cellblock_connected_clients` (gauges) - `cellblock_matches_started_total`, `cellblock_matches_ended_total{outcome}` (counters) - `cellblock_lines_cleared_total`, `cellblock_garbage_sent_total` (counters) Plus a dedicated Grafana dashboard (`CELLBLOCK live stats`, tagged `cellblock`/`jam`). Operator direction (2026-07-13): both game-jam projects should live together under a `Game Jams` folder in Grafana — Cellblock moves in, Breakout joins once it has metrics. ## Scope **Two bundled pieces of work**: 1. **`/metrics` endpoint on the Breakout server**. Static-site currently, so this needs a small sidecar or a lightweight metrics endpoint on whatever serves index.html + assets. Metric contract to define — likely: - `breakout_active_sessions` (gauge) — concurrent players - `breakout_sessions_started_total` (counter) - `breakout_levels_completed_total{level}` (counter) - `breakout_deaths_total{level}` (counter) - `breakout_bricks_broken_total{type}` (counter — regular, fortress, lockdown, whatever the type-set is) - Contract-of-record placed in the repo (per Engineer's precedent — `CONTRACT.md` extension or a dedicated `docs/metrics.md`). 2. **Grafana dashboard**. Under the new `Game Jams` folder alongside Cellblock. Modeled on `CELLBLOCK live stats`. Provisioned via `/srv/docker/monitoring/grafana/dashboards/Game Jams/breakout.json` (once `foldersFromFilesStructure: true` flip lands in the provisioning config). ## Verification AC - [ ] `/metrics` endpoint reachable from alloy at container:port - [ ] alloy config extended with a `prometheus.scrape "breakout"` block (mirroring the cellblock block at `/srv/docker/monitoring/alloy/config.alloy`) - [ ] Metric contract documented in-repo - [ ] Grafana `Game Jams` folder created (via provisioning `foldersFromFilesStructure: true` flip) - [ ] Cellblock dashboard moved into `Game Jams` folder - [ ] Breakout dashboard created in `Game Jams` folder - [ ] Both dashboards render live data ## Related - cellblock#10 — precedent for game-server /metrics contract - alcatraz-infra alloy config — where the scrape block gets added - alcatraz-infra grafana provisioning — where the folder flip lands ## Anchor - Filed 2026-07-13 by Bosun on operator directive during post-Game-Jam-II follow-up planning session.

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

frankenbit/breakout#62

No description provided.

Rows
Columns