Show match demand in metrics (Refs #138)

docs/guides/metrics.md

@@ -26,8 +26,37 @@ history or the original installation date.
 Background refresh keeps the last successful report visible on failure and offers
 Retry. Returning to a visible tab refreshes immediately. Game and map filters apply
 to the whole report, including comparisons, signals, and the heatmap. Map choices
-preserve the exact recorded game/map pair. Range and scope are shareable through
-the URL; refreshes preserve table controls and chart selection.
+preserve the exact recorded game/map pair and include retained occupancy and match
+history. Range and scope are shareable through the URL; refreshes preserve table
+controls and chart selection.
+
+## Matches and groups
+
+**Matches started** counts retained matches whose recorded start falls within the
+selected period, including both endpoints. A missing start event uses the first
+recorded match observation, which may be later than the actual start. Active,
+completed, and interrupted matches all count, including matches that never reach
+round 2 and matches on removed servers. These counts do not use the leaderboard's
+completed-match or round qualification rules.
+
+**Average group size** is the average number of distinct recorded player GUIDs per
+match. A player counts once across all reports for that match, including late
+joins and players who left before its end. Each match has equal weight in the
+fleet average; the average is not an average of map averages. This measures
+recorded participation over the match's lifetime, not its starting squad or peak
+simultaneous occupancy. Active matches can change as more players are recorded.
+
+**Solo games** counts matches with exactly one distinct recorded player. Its share
+uses only matches with at least one recorded player. Matches with no recorded
+players still count as started, but their group size is unknown and they are
+excluded from both the average and solo-share denominator. If no matches have
+recorded players, those two values are unavailable rather than zero.
+
+The map table includes these same match statistics. A map with match history in
+the selected period remains visible even without occupancy samples; its match
+statistics do not establish lobby-hours, availability, or an autoscaling shortage.
+Match statistics cover the selected period only and have no previous-period
+comparison.
 
 ## Timeline and tables
 
@@ -125,11 +154,18 @@ Map variants use the configured variant when it matches the reported map. Player
 capacity may be retained in raw samples, but no metric or signal requires
 `sv_maxclients` or an assumed four-player limit.
 
-Collection begins after this feature is installed; earlier occupancy cannot be
+Occupancy collection begins after this feature is installed; earlier occupancy cannot be
 reconstructed. Samples default to 31 days of retention; **Admin → Settings** can
 change this period. Cleanup runs during collection and in the background. Samples
 survive removal of a server and contain no player identities.
 
+Match statistics use existing saved match history, independently of occupancy
+samples and raw telemetry diagnostics. **Match history retention** under
+**Admin → Settings → Matches & players** defaults to indefinite. Expiring a
+completed or interrupted match also removes its player participation and changes
+these statistics; active matches are protected. Increasing retention cannot
+restore expired matches. Saved match history survives removal of a server.
+
 ## API
 
 `GET /api/metrics` supplies the same report as the page and disables HTTP response
@@ -140,9 +176,19 @@ from selected-scope evidence timestamps. Collection boundaries are determined
 before scope filtering, so samples from other groups still end a batch interval.
 
 `running` contains `average`, `peak`, and `capturedHours`; timeline points include
-their own `capturedHours`. Map rows expose `noEmpty`, `availabilityObserved`, and
+their own `capturedHours`. Report-level `matches` and each map row's `matches`
+contain `started`, `withRecordedPlayers`, `averageGroupSize`, `solo`, and
+`soloShare`. `withRecordedPlayers` is the denominator for the group average and
+solo share; `soloShare` is a percentage from 0 to 100. When that denominator is
+zero, `averageGroupSize` and `soloShare` are `null`, `solo` is zero, and `started`
+retains the recorded number of starts. Match scope uses the exact saved `game` and `map_name`
+labels, and its time window uses the saved `started_at` timestamp. Occupancy
+collection and evidence timestamps remain independent of match history.
+
+Map rows expose `noEmpty`, `availabilityObserved`, and
 `availabilityUnknown` durations, plus current `policy` context and
 `noEmptyAtMaximum` / `noEmptyBelowMaximum` durations. `pooledAvailability` combines
 map durations and coverage. `autoscalingPaused` reports the current global pause
 separately from each policy's own `pausedReason`. Policy edits and global pause changes invalidate
-cached metrics reports.
+cached metrics reports, as do changes to the match and player participation data
+used by the report.