Add autoscaling outcomes to Metrics (Refs #140)

docs/guides/autoscaling.md

@@ -10,7 +10,7 @@ T5 game-wide policies cover the ten standard Zombies maps; T6 policies cover nin
 
 Choose **Add policy**, select the game and scope, and enter an explicit maximum. The initial editor selects Off, with a minimum of one running lobby, one empty spare, and a 15-minute empty interval. Counts must be between 1 and 20; the minimum and spare target cannot exceed the maximum.
 
-Choose **Save policy** to apply changes directly. Saving checks the current fleet, policy revision, ownership conflicts, and host readiness. If saving is blocked, the form keeps your settings and shows the reason. Saved policies show lobby counts, key availability, and the current status. An active job appears once with its latest stage and a **View job** link. Use **Lobbies** for per-map spare coverage and occupancy evidence, **Activity** for decision changes grouped by job, and **Metrics** for observed capacity and provisioning measurements.
+Choose **Save policy** to apply changes directly. Saving checks the current fleet, policy revision, ownership conflicts, and host readiness. If saving is blocked, the form keeps your settings and shows the reason. Saved policies show lobby counts, key availability, and the current status. An active job appears once with its latest stage and a **View job** link. Use **Lobbies** for per-map spare coverage and occupancy evidence and **Activity** for decision changes grouped by job. [**Metrics**](metrics.md) shows observed lobby counts and empty spare hours, plus autoscaling additions, removals, failed or cancelled operations, and average/maximum request-to-ready time for the selected period, game, and map. The policy card retains its separate 31-day measurement totals, including spare deficits.
 
 | Autoscaling | Behavior                                                                                              |
 | ----------- | ----------------------------------------------------------------------------------------------------- |
@@ -68,7 +68,7 @@ The production observation period and live pilot have not been run as part of im
 
 1. Select one or two representative maps and record the baseline lineup, keys, versions, host CPU and memory, and player-hours.
 2. Select On after resolving blockers and checking agent capability. Set the minimum, maximum, and spare target, then choose Save policy.
-3. Monitor request-to-ready time from Provisioning, browser visibility, successful external joins, empty lobby-hours, spare deficits, and removals. Increase the spare target if creation latency leaves new groups without a suitable lobby.
+3. Use Metrics to monitor request-to-ready time, empty lobby-hours, and autoscaling removals for the selected period and scope. Check the policy card's 31-day spare deficits and individual Provisioning operations for delays; verify browser visibility and successful external joins separately. Increase the spare target if creation latency leaves new groups without a suitable lobby.
 4. Expand one map at a time when spare availability and gameplay meet your requirements. Pause if they regress.
 
 The page retains up to 31 days of decision evidence and observations, with the 30 most recent decision changes shown. Repeated unchanged evaluations update the decision's last-seen time instead of adding a row. Unresolved intent survives retention. Provisioning history retains the operation and policy backlink separately.

docs/guides/metrics.md

@@ -26,10 +26,35 @@ 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 and include retained occupancy and match
-history. Range and scope are shareable through the URL; refreshes preserve table
+preserve the exact recorded game/map pair and include retained occupancy, match,
+and autoscaling Provisioning history. Range and scope are shareable through the URL; refreshes preserve table
 controls and chart selection.
 
+## Autoscaling operations
+
+The **Autoscaling** section follows the selected period, game, and map and links
+to the policies. **Lobbies added** and **Lobbies removed** count successful create
+and remove operations, including completions with warnings. Failed and cancelled
+operations appear separately. Counts come from retained Provisioning records
+linked to autoscaling, independently of occupancy samples; manual operations and
+changes in sampled lobby counts do not contribute.
+
+An operation belongs to the period containing its finish time, including both
+endpoints. A request made before the period still counts if it finishes within it;
+pending operations and finishes outside the period do not count. **Request to
+ready** shows the average and maximum request-to-finish duration of successful
+creates with valid timestamps, including queue time. Each create has equal weight.
+Without valid completed creates, these timings are unavailable, not zero. Verified
+readiness does not establish browser visibility or successful external joins.
+
+Scope uses the operation's recorded server name, which encodes its game and map
+variant. Game-wide policies do not combine different variants when filtering by
+map. Friendly map names, slugs, and unambiguous canonical map names are supported;
+an ambiguous engine label such as `zm_transit` is not assigned to a variant.
+History survives server removal and policy deletion, subject to Provisioning
+retention. Missing or purged operations are not estimated. The policy card's
+31-day spare-deficit measurements remain separate from this section.
+
 ## Matches and groups
 
 **Matches started** counts retained matches whose recorded start falls within the
@@ -199,3 +224,10 @@ 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, as do changes to the match and player participation data
 used by the report.
+
+`autoscaling` contains `added`, `removed`, `failed`, `cancelled`, `readinessSamples`,
+`readinessMeanSeconds`, and `readinessMaxSeconds`. Counts use `finished_at` in the
+selected window; readiness uses `finished_at - started_at` for successful creates
+with nonnegative, valid durations. Both timing values are `null` when there are
+no readiness samples. Changes to Provisioning outcomes or autoscaling source
+links invalidate cached reports, including when no new occupancy is collected.