234 lines
15 KiB
Markdown
234 lines
15 KiB
Markdown
# Metrics
|
||
|
||
Metrics is under **Analytics** at `/metrics` (keyboard shortcut: `g m`).
|
||
Choose the past 24 hours, 7 days, or 30 days. The page refreshes every minute.
|
||
|
||
## Overview and filters
|
||
|
||
**Lobbies running** shows the average and peak number of recorded lobbies in the
|
||
selected scope. The average divides captured lobby-hours, including unknown
|
||
status, by captured wall time. Empty spares are deliberate supply for new groups:
|
||
the card shows their hours and share of all captured lobby-hours, rather than
|
||
treating them as failed utilization. Unknown status can include lobbies starting
|
||
or unavailable, so this count does not guarantee every lobby was ready to join.
|
||
|
||
**Player-hours** integrates reported player counts over time. **No empty lobby**
|
||
shows the share of known map time when no tracked lobby reported zero players.
|
||
Each game/map is measured separately, then its durations are pooled. This is not
|
||
elapsed fleet time or a count of rejected joins. A partly occupied Zombies lobby
|
||
does not count as an empty spare, even if player slots remain.
|
||
|
||
**Last collected** is the newest recorded batch, including unknown checks;
|
||
**Report refreshed** is when this report was calculated. Collection stops when no
|
||
servers are registered. Earliest retained observations do not prove continuous
|
||
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, 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
|
||
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
|
||
|
||
The timeline defaults to **Average lobbies running**, split into **With players**,
|
||
**Empty spare**, and **Unknown**. Each bucket divides those lobby-hours by its
|
||
captured wall time, so changing lobby counts remain visible. Collection gaps are
|
||
excluded from that denominator. The average-lobby axis uses whole-number ticks;
|
||
period details preserve fractional averages. Switch to the share view to compare proportions,
|
||
or hours to compare absolute lobby time. Periods without captured time remain gaps.
|
||
|
||
The timeline has labelled axes and marks partial edge periods. Select a bar or use
|
||
Previous/Next to inspect its exact interval and values. The time table supplies
|
||
the same figures for comparison and assistive technology. Zero captured time is
|
||
distinct from an observed empty lobby. Short durations use seconds or minutes so
|
||
a real observation is not rounded to zero.
|
||
|
||
The map table supports numeric sorting and local search. **Lobbies (avg · peak)**
|
||
shows the time-weighted average and peak concurrent lobby count for each recorded
|
||
game/map pair, with empty lobby-hours beneath. Sort this column by average count.
|
||
The average divides all captured lobby-hours, including unknown occupancy, by
|
||
that map's captured wall time; collection gaps and periods without recorded lobbies
|
||
for that map are excluded. Peak is the largest captured concurrent count, not the
|
||
number of distinct lobby names. Empty lobby-hours sum time with zero reported
|
||
players across the map's lobbies. Unknown occupancy is not counted as empty;
|
||
empty time is unavailable when no occupancy is known. Lobby counts are unavailable
|
||
without captured time. Per-lobby match and activity history is available on server pages.
|
||
|
||
The map table's
|
||
**No empty lobby** column uses occupancy alone and retains the known map-time
|
||
denominator in its details. Unknown map availability stays distinct from zero
|
||
time without a spare. Evidence can be limited by short observations or unknown
|
||
occupancy, never by missing player limits.
|
||
|
||
## Comparisons and activity
|
||
|
||
Previous-period comparisons use the preceding equally long window with identical
|
||
filters. Average lobby counts compare recorded supply, while player-hours changes
|
||
are relative percentages. A previous observed zero can show **New**. Missing
|
||
evidence remains unavailable. Partial retained history is labelled; a 30-day
|
||
comparison usually has little previous history because default retention is
|
||
31 days. Collection gaps are excluded, and comparisons do not prove uninterrupted
|
||
collection or adjust player-hours for fleet size.
|
||
|
||
The activity heatmap groups captured time by weekday and hour in its displayed
|
||
timezone. Color represents occupied / known lobby time. Exact cell values include
|
||
unknown time and contributing dates. No-data cells differ from observed zero;
|
||
repeated DST hours contribute their actual elapsed time. Occupancy share describes
|
||
how the fleet was used, but can change simply because a policy adds or removes
|
||
spares. Read it alongside player-hours, lobby counts, and empty-lobby availability.
|
||
|
||
## Autoscaling signals
|
||
|
||
Signals compare each map's observations with its **current** applicable policy.
|
||
Game-wide policies apply independently to each supported map variant. Each signal
|
||
links to the policy on **Fleet → Autoscaling**; a map without a policy gets a link
|
||
to add one. Signals are advisory and never change a policy or a lobby.
|
||
|
||
A global pause appears once above the signals. Historical shortage signals remain
|
||
visible while the fleet is paused, including suggestions to review the maximum
|
||
or spare target. Review these findings and current settings before resuming.
|
||
An individual policy's own pause or disabled state still prompts a policy review.
|
||
|
||
| Recorded condition | Suggested action |
|
||
| ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
|
||
| No empty lobby for at least 2% of known map time, mostly at or above the current maximum | Review raising the policy maximum. |
|
||
| No empty lobby for at least 2% of known map time, mostly below the current maximum | Review the spare target and check creation time or blockers. |
|
||
| An applicable policy is off or paused | Review the policy and its pause or activation conditions. |
|
||
| No applicable policy and known occupancy is available | Consider adding an autoscaling policy to keep spares available. |
|
||
| Occupancy unavailable | Check telemetry/RCON reporting and wait for known player counts. |
|
||
| No shortage signal | Keep watching empty-lobby availability. |
|
||
|
||
Evidence includes no-empty map time and how it splits above/below the current
|
||
maximum. Less than one hour of known map availability, less than 80% known map
|
||
availability, or less than 80% known lobby time makes advice tentative. Player limits are not needed. These
|
||
thresholds are advisory rules, not demand forecasts.
|
||
|
||
Policy settings may have changed during the selected period. Comparing historical
|
||
counts against today's maximum does not establish which settings applied then or
|
||
whether autoscaling was enabled. No reported empty lobby also does not prove
|
||
failed joins or unmet demand. Review provisioning delays, blockers, host resources,
|
||
and game-key availability before changing targets.
|
||
|
||
## Definitions and collection
|
||
|
||
- **With players:** a successful observation reported at least one player.
|
||
- **Empty spare:** an observation reported zero players.
|
||
- **Unknown:** failed checks, provisioning, or otherwise unavailable occupancy.
|
||
- **Player-hours:** reported players × observed time. Bots count if the server includes them.
|
||
- **Empty lobby available:** at least one lobby on the game/map reported zero players.
|
||
- **No empty lobby:** at least one lobby reported occupancy, and none reported zero. Mixed positive and unknown counts mean no empty lobby was reported; an unknown lobby might actually have been empty.
|
||
- **Unknown map availability:** every lobby on the game/map had unknown occupancy. This interval is excluded from the known-map denominator and is never counted as a spare shortage.
|
||
|
||
Observations come from the existing status worker. Each complete collection stays
|
||
valid until the next collection, up to the 90-second freshness limit. Longer gaps
|
||
are excluded, not counted as unknown or zero lobbies. Captured wall time includes
|
||
intervals with at least one recorded lobby in the selected scope. Unknown lobby
|
||
time and unknown map time use different units: several unknown lobbies on one map
|
||
contribute several lobby-hours but only one interval of unknown map availability.
|
||
|
||
Charts split time at UTC hour/day boundaries; partial periods remain partial.
|
||
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.
|
||
|
||
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
|
||
caching. Query parameters are `days` (1, 7, or 30), `game`, `map` (requires game),
|
||
and `timeZone` (an IANA zone). Invalid ranges and zones fall back to the defaults;
|
||
invalid scope syntax is normalized. Fleet collection timestamps remain separate
|
||
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`. 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, 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.
|