Skip to content

lattice-analytics — Event ingestion & metrics

Ingests game telemetry events (game-API-key authed) and serves RBAC-scoped metric time-series for dashboards. Source: control-plane/lattice-analytics/src/LatticeAnalytics/Program.cs.

  • Port: http://localhost:3006 (hard-coded).
  • Auth: ingestion uses game API-key headers X-Lattice-Api-Key + X-Lattice-Api-Secret (validated via console). Query uses a developer bearer token resolved to a principal; RBAC: super-admin any game, developer only their OwnedGameIds.
  • DTOs use PascalCase.

Ingestion

Method · Path Auth Body → Response
POST /v1/events game API key {Events:EventInput[]} → IngestResponse{Accepted}; 403 on invalid key

EventInput{Type, Name?, UserId?, SessionId?, Timestamp?, Values?:Dictionary<string,double>, Tags?:Dictionary<string,string>}. gameId is resolved server-side from the key — never trusted from the body. Event Type values: Custom, GameLaunch, SessionStart, SessionEnd, Heartbeat, MatchmakingRequest, MatchmakingSuccess, MatchmakingFailure, FriendRequest, PartyCreated, PresenceChange, CheatViolation.

Query

Method · Path Auth Response
GET /v1/metrics none (catalog) MetricInfo[]{Key, Description, Aggregation}
GET /v1/games/{gameId}/metrics/{metric}?from=&to=&bucket= developer bearer, RBAC-scoped MetricSeriesResponse{GameId, Metric, Bucket, From, To, Total, Points:[{BucketStart, Value}]}
GET /v1/games/{gameId}/overview?from=&to=&bucket= developer bearer, RBAC-scoped GameOverviewResponse{GameId, From, To, Bucket, Metrics:MetricSeriesResponse[]}
GET /healthz — liveness

Built-in metric keys: ccu, session_count, avg_session_duration, matchmaking_requests, match_success_rate, friend_requests, parties_created, presence_changes, game_launches, cheat_violations, cheat_severity_total, flagged_players, active_users, plus dynamic custom.<name> and cheat_violations.<type> counters.

The cheat_violations / cheat_severity_total / flagged_players series are driven by the anti-cheat on_violation scores your game servers report — they power the cheat panel in the developer portal.

Send an event, then query CCU
curl -s -X POST http://localhost:3006/v1/events \
  -H "X-Lattice-Api-Key: $KEY" -H "X-Lattice-Api-Secret: $SECRET" \
  -H 'content-type: application/json' \
  -d '{"Events":[{"Type":"SessionStart","UserId":"u1","SessionId":"s1"}]}'

curl -s "http://localhost:3006/v1/games/$GAME/metrics/ccu?from=2026-06-01&to=2026-06-23&bucket=1d" \
  -H "authorization: Bearer $DEV_TOKEN" | jq