feat(ops): structured JSON logging + trace/player scopes + client-intent audit #156

Merged

marco merged 1 commit from feat/structured-logging into main

2026-07-22 22:02:33 +02:00

marco commented

2026-07-22 21:55:06 +02:00

Owner

Summary

Structured logging for the two servers, aimed at Loki/Grafana and at auditing what a client does (reconstruct a session, spot a modified client).

One log format everywhere (dev + prod, identical): structured JSON to stdout via the built-in AddJsonConsole — no env-dependent shape; the environment is only ever a label/field (Promtail adds env/job/container; the framework logs it at startup). No new dependency. (Local just dev now also emits JSON, so it's testable locally.)
Correlation on every line (scopes, IncludeScopes): ActivityTrackingOptions puts the request Activity's TraceId/SpanId on each log (correlate a whole /ws session); GameSessionHandler wraps the session in a PlayerId/Char scope (filter by player). Plus the framework's ConnectionId/RequestPath.
Client-intent audit: one Client intent {Intent} line per client message (Debug), under that scope → set Logging__LogLevel__IsoMmo=Debug for a full action trail to reconstruct a session or spot odd/rapid actions. Malformed frames now log at Warning (a modified-client tell).
docs/deploy.md documents the format, Promtail→Loki, the trace/player correlation, and the audit level.

How it was tested

Ran the stack locally with Logging__LogLevel__IsoMmo=Debug, logged in via the debug harness and moved around. Verified in the captured stdout:

Every app log line is valid JSON (Timestamp, LogLevel, Category, Message, State bag of template fields, Scopes).
The connect line and each Client intent MoveRequest carry, in scopes, the same TraceId for the connection plus PlayerId + Char.
Also confirmed ASPNETCORE_ENVIRONMENT=Production (the Docker default) emits the identical JSON.
just lint (zero warnings) + just test (all projects green) + whole solution builds.

Checklist

just lint passes (zero warnings)
just test is green
The whole solution builds
Multi-platform preserved (built-in logging; no OS-specific code, no new dependency)
Docs updated (docs/deploy.md)
Part of #11 (pre-internet ops) — structured logging item

## Summary Structured logging for the two servers, aimed at Loki/Grafana and at **auditing what a client does** (reconstruct a session, spot a modified client). - **One log format everywhere** (dev + prod, identical): **structured JSON to stdout** via the built-in `AddJsonConsole` — no env-dependent shape; the environment is only ever a label/field (Promtail adds `env`/`job`/`container`; the framework logs it at startup). No new dependency. (Local `just dev` now also emits JSON, so it's testable locally.) - **Correlation on every line** (scopes, `IncludeScopes`): `ActivityTrackingOptions` puts the request Activity's **`TraceId`/`SpanId`** on each log (correlate a whole `/ws` session); GameSessionHandler wraps the session in a **`PlayerId`/`Char`** scope (filter by player). Plus the framework's `ConnectionId`/`RequestPath`. - **Client-intent audit**: one `Client intent {Intent}` line per client message (Debug), under that scope → set `Logging__LogLevel__IsoMmo=Debug` for a full **action trail** to reconstruct a session or spot odd/rapid actions. Malformed frames now log at **Warning** (a modified-client tell). - `docs/deploy.md` documents the format, Promtail→Loki, the trace/player correlation, and the audit level. ## How it was tested Ran the stack locally with `Logging__LogLevel__IsoMmo=Debug`, logged in via the debug harness and moved around. Verified in the captured stdout: - Every app log line is valid JSON (`Timestamp`, `LogLevel`, `Category`, `Message`, `State` bag of template fields, `Scopes`). - The connect line and each `Client intent MoveRequest` carry, in scopes, the same **`TraceId`** for the connection plus **`PlayerId`** + **`Char`**. - Also confirmed `ASPNETCORE_ENVIRONMENT=Production` (the Docker default) emits the identical JSON. - `just lint` (zero warnings) + `just test` (all projects green) + whole solution builds. ## Checklist - [x] `just lint` passes (zero warnings) - [x] `just test` is green - [x] The whole solution builds - [x] Multi-platform preserved (built-in logging; no OS-specific code, no new dependency) - [x] Docs updated (`docs/deploy.md`) - [x] Part of #11 (pre-internet ops) — structured logging item

marco added 1 commit

2026-07-22 21:55:06 +02:00

feat(ops): structured JSON logging (same format everywhere) + TraceId/PlayerId scopes + client-intent audit

ci / Lint & Test (pull_request) Successful in 1m44s

Details

cdb010a621

marco merged commit d7e38a88c2 into main

2026-07-22 22:02:33 +02:00

marco deleted branch feat/structured-logging

2026-07-22 22:02:33 +02:00

marco referenced this pull request from a commit

2026-07-22 22:02:34 +02:00