Console Usage page #634

Part of #623.

Scope

After this PR, the console has a Usage page at /usage, last in the sidebar. It shows the full figures for the chosen range (1 hour, 6 hours, 24 hours, 7 days): requests, grants and how each was served, wait, held time and turnaround, provisioning and boot time, rejections by reason, device incidents, slots, RAM and queue use over the range, and use per platform, per worker and per requester. The Overview's Granted tile now opens it. They are the same figures simlock stats --json and GET /v1/stats give for that range.

In short

The page reads GET /v1/stats?since=<range> (#632) and draws it as stat tiles and tables. It uses #633's range picker, its ?range= rule and its partial note, and fetches the route like every other (feature #623 Shared values, "Console ranges"). It works at 360 px wide and in both themes.

flowchart LR
  N["Sidebar: Usage (new)"] --> P["/usage?range=1h|6h|24h|7d"]
  P --> S["GET /v1/stats?since=range"]
  S --> V["Tiles + tables (new)"]
  S -->|partial| Q["Figures cover from today 09:12."]
  O["Overview: Granted tile (changed)"] -->|link| P

What the operator sees, for /usage?range=24h after a scripted run:

Usage                                   [1 hour] [6 hours] (24 hours) [7 days]
Figures cover from today 09:12.
Requests 214   Granted 209   Rejected 5   Wait p95 38 s   Held p50 4 min 2 s     (each: last 24 hours)

Grants by source     warm 160 · booted 41 · provisioned 8
Durations            Count  p50      p95       Max
  Wait               209    0 s      38 s      2 min 10 s
  Held               ...
  Turnaround / Provisioning / Boot ...
Rejections by reason   no-wait 3 · timeout 2
Use over the range     Slots: peak 8, mean 5.2, of 8 · RAM: peak 12.0 GiB, mean 900 MiB, of 16.0 GiB · Queue: peak 3, mean 0.4
Device incidents       Quarantined 1 · Recovered from quarantine 1 · Recovered after a crash 0 · Lost 0
Per platform           Platform, Requests, Granted, Rejected, Wait p95 (iOS, then Android)
Per worker             Worker, Requests, Granted, Rejected, Wait p95; one row per worker; on a single host one row, the host
Per requester          Requester (label, then id), Requests, Granted, Rejected, Held in total

If this goes wrong, the operator sees figures that differ from simlock stats for the same range, or a page that scrolls sideways on a phone.

Technical spec

Facts

The output shape, the route and the ranges are feature #623 Shared values ("usage.get", "GET /v1/stats", "Console ranges"). The range picker, the Wait p95 tile and the partial note are #633's. Means are time-weighted by the daemon (Shared values, "usage.get"); the page prints them as given.

Modules touched

Searches: ROUTES, NAV, IconName, DataTable, usePaging, and #633's range and figures modules.

• ui/src/model/usage.ts (new): one stats answer to the page's view model: tiles, grants by source, durations, rejections, incidents, use over the range, the platform, worker and requester rows.
• ui/src/state/usage.ts (new): reads Overview and Waiting: a range picker, wait p95, leases granted and three charts #633's range and its stats path with useLiveResource. The worker and requester tables page in the URL (workers-page/workers-size, requesters-page/requesters-size, F16); the other tables (grants by source, durations, rejections, incidents, platforms) take one constant Paging that holds every row on one page, so no pager shows. A range change drops workers-page and requesters-page and keeps the sizes.
• ui/src/model/overview.ts: the Granted tile links to /usage with the Overview's ?range= (none for 1h).
• ui/src/screens/usage/index.tsx, usage.css (new): the page.
• ui/src/app/routes.ts: a Usage entry at /usage, after Events.
• ui/src/ds/icon.tsx: a usage icon.
• e2e/console/fixtures.ts: Usage in NAV.
• e2e/console/usage.spec.ts (new).
• docs/CONSOLE.md, ui/AGENTS.md (Pages table).

flowchart LR
  RT[app/routes*] --> SU[screens/usage*]
  SU --> STU[state/usage*]
  SU --> DS[ds: StatRow, Panel, DataTable, ChoiceChips]
  STU --> R[state/range, #633]
  STU --> L[state/live]
  STU --> PG[state/paging]
  STU --> MU[model/usage*]
  MU --> F[model/figures, #633]

Contract and event changes

None. The page reads #632's route, typed from #631's output schema. The only input it takes is ?range= (#633's rule) and the four page keys (F4's rule).

Other code on the same state

Searches: setSearch writers (3: state/paging.ts, state/events.ts, #633's range), watch( (1).

• The range and the two page keys share the query; each writer keeps the others' keys (F4, Overview and Waiting: a range picker, wait p95, leases granted and three charts #633).
• The Overview (Overview and Waiting: a range picker, wait p95, leases granted and three charts #633) watches the same /v1/stats?since=<range> path; with both on screen there is one resource and at most one request in flight (connection.ts:173-177).

Failure modes

State written: the URL's range and page keys only. A restart in the middle leaves nothing.

Rules in play

• ADR 0013 §1, "keeps no state the daemon does not report": every figure is the answer's, and the page sums, averages or re-buckets nothing.
• ADR 0013 §3: the route is fetched on events and every second, coalesced, like every route.
• ADR 0016 §5, "every surface shows that beside the figures": the partial note sits under the picker.
• Architecture rule 10: the Wait p95 tile and the partial note are Overview and Waiting: a range picker, wait p95, leases granted and three charts #633's functions, not copies.
• ui/AGENTS.md layers: the builder in model/, the read in state/, the screen draws only.
• DESIGN.md: numbers mono and right-aligned; tables through DataTable; codes as spelled (F6); 360 px, both themes, AA contrast.
• Testing rule 7: phone width, keyboard, CSP, axe and sidebar order come from adding Usage to NAV (F3), not from new tests.

Tests

Seam: ui/src/model/usage.ts unit tests and a screen test with renderToStaticMarkup, modelled on ui/src/screens/overview/overview.test.tsx; the browser lane modelled on e2e/console/views.spec.ts.

• the tiles show Requests, Granted, Rejected, Wait p95 and Held p50 from totals, each with the range's unit, with a fixture where every figure differs
• grants by source list warm, booted and provisioned, and unknown only when the answer has it
• the durations table has rows Wait, Held, Turnaround, Provisioning and Boot, each with its own count, p50, p95 and max as durations, and — for a null figure
• rejections list one row per reason as the daemon spells it, largest count first and ties by reason, and say No requests were rejected. when there are none
• incidents list Quarantined, Recovered from quarantine, Recovered after a crash and Lost from their four fields
• use over the range shows totals.utilisation.slots peak, mean (one decimal) and max, totals.queue peakDepth and meanDepth, and totals.utilisation.ram peakBytes, meanBytes and limitBytes through formatBytes (900 MiB below 1 GiB, 12.0 GiB above) only when it is present, — for a null figure, with a fixture where every figure differs
• the page shows no declined, probes or failures.byEvent count, with a fixture that has them set
• the platform table has the columns Platform, Requests, Granted, Rejected and Wait p95, with iOS then Android
• the worker table has the columns Worker, Requests, Granted, Rejected and Wait p95; a row is named by its label, or its id where it has none, in the daemon's order; a single host's one entry is one row; an empty workers says No workers in this range.
• a requester row shows its label with its id beside it, its id alone where it has no label, the agent alone for a gw:<instance>:<agent> id (agentIdOf), and its held time in total as a duration, in the daemon's order
• an answer with no requests shows tiles of 0, — for every percentile and mean, and No requests in this range. in the requester table
• the Usage screen draws the picker with the chosen range checked, the tiles, and each table as a region named by its panel title
• the Usage screen shows the partial note under the picker when the figures carry one, and none otherwise
• a refused stats read shows its message in place of the figures; while loading the page shows Loading…
• extend "lists the sections in the sidebar's order" in ui/src/app/routes.test.ts with /usage last, and routeFor("/usage") is Usage
• the Overview's Granted tile links to /usage from 1h and to /usage?range=6h, 24h, 7d from the others (extend Overview and Waiting: a range picker, wait p95, leases granted and three charts #633's Granted case in ui/src/model/overview.test.ts)
• choosing another range drops workers-page and requesters-page from the URL and keeps the new range and both size keys (a model test of the URL writer)
• (console) after a scripted run on the fake driver, /usage?range=24h shows the same requests, grants by source, rejections by reason, wait p95, slots peak and mean, and requester rows as GET /v1/stats?since=24h and simlock stats --since 24h --json, and its per-worker table has one row, the host
• (console) /usage opens on 1 hour; choosing 7 days writes ?range=7d, and a reload keeps 7 days checked and the same figures
• (console) a lease granted while the page is open raises Requests and Granted within 2 seconds with no reload
• (console) clicking the Overview's Granted tile on /?range=7d opens /usage?range=7d
• (console) on a gateway with two workers, the per-worker table has two rows, each named by its worker's label
• (console) Usage in NAV puts /usage under the existing every-view tests: 360 px with no sideways scroll, keyboard alone, no CSP violation, sidebar order, and the axe check in light and dark (F3)

Done when

• On the fake driver after a scripted run, the Usage page for 24 hours shows the same figures as simlock stats --since 24h --json and GET /v1/stats?since=24h.
• The picker switches between 1 hour, 6 hours, 24 hours and 7 days, and the URL keeps the choice.
• The page has no sideways scroll at 360 px and passes the axe check in both themes.
• On a gateway the per-worker table has one row per worker; on a single host, one row.
• docs/CONSOLE.md lists Usage in the sidebar and describes its figures and the partial note; ui/AGENTS.md has its row in Pages.

Out of scope

• Charts on the Usage page; the three charts are the Overview's (Overview and Waiting: a range picker, wait p95, leases granted and three charts #633).
• The CSV ledger (&ledger=1, GET /v1/stats and the simlock stats --csv ledger #632).
• Explicit start and end dates.

Depends on

• Overview and Waiting: a range picker, wait p95, leases granted and three charts #633

Written by an agent.