[JacobStephens2]

Closes #2068

Summary

Fleet metrics are an explicit client of each owning machine's local /api/v1/metrics, merged here; the API itself stays local (ADR 0026).

metrics --fleet | metrics --machine <name> | /metrics (Fleet by default once a machine is paired or saved)
  fleet::load
    this machine: trends()                      (skipped for --machine <peer>)
    each Fleet entry, in parallel, 3 s bound:
      link-only        -> no request
      ok               -> save snapshot (logs/fleet-metrics/<digest>.json, one rename)
      unavailable      -> saved snapshot for this view, else newest with the same filters
                          -> status cached, last_seen
      refused/incompatible -> no snapshot
    retired (saved, no longer in console.fleet) -> cached
    merge: outcome rows per machine · comparison rows per machine + Fleet totals per kind
           · Where runs failed by stage/category with per-machine counts
/api/v1/metrics?fleet=… or ?machine=…  -> 400 "explicit client view"

• --machine <this machine's name> gives plain metrics; the page's This machine keeps the signal groups.
• A reachable peer's failed Command opens at /peek?…&machine=<peer>; a cached one is plain text marked (cached).
• metrics --fleet is in the parity exclusions with ADR 0026's reason; the ADR now names --machine too.
• Manual (docs/guide.md → site/docs), hand-written site pages and docs/code-navigation.md updated.

Evidence

Execution evidence

• Before: cargo test --test console fleet_metrics_merge_paired_consoles_and_keep_an_offline_peer_cached on the base branch: metrics --fleet is not a metrics argument (usage: thirdshift metrics [<command>] [--json] [--window …]), so the test cannot run there.
  After: test metrics::fleet_metrics_merge_paired_consoles_and_keep_an_offline_peer_cached ... ok. It pairs two real loopback Consoles and checks:

  • Fleet totals equal the sum of each machine's own metrics.
  • The page defaults to the Fleet.
  • A peer's drilldown link opens.
  • The API refuses fleet and machine.
  • --machine scoping works.
  • After the peer is stopped, it shows as cached with last_seen.
  • It is retired after console fleet remove.

• Review findings, each run first as written:

  Test	Before the fix	After the fix
  cargo test --test console api_metrics_stays_local_once_a_peer_is_paired	API answered with Fleet metrics: {"comparison":…,"machines":[…	ok
  cargo test --test console fleet_metrics_keep_an_offline_peer_for_another_window	offline peer's last-fetched history missing	ok
  cargo test --test console a_fleet_machine_named_fleet_can_be_chosen_alone	assertion left != right failed: one machine reads as the whole Fleet	ok
  cargo test --bin thirdshift logs::metrics::fleet::tests	a_cached_snapshot_counts_only_failures_in_todays_window failed with left: 1, right: 0	test result: ok. 6 passed

• Security review: a peer refuses a signed-in Console person missing from its sign-in list, but once it went offline or was removed, the summary saved from another person's read showed to that person. Snapshots are now kept per machine and reader (src/logs/metrics/fleet.rs path, saved), and the guide says so.

  Test	Before the fix	After the fix
  cargo test --test console a_cached_peer_snapshot_stays_with_the_person_who_read_it	panicked at tests/console/fleet_control.rs:230: the refused person's page listed widgets#73 (cached) on owner	ok

• scripts/affected-tests main after the security fix: PASS npm test --prefix site, PASS cargo build --locked, PASS npm test --prefix console, PASS cargo test.

• scripts/affected-tests origin/issue-2036:

  • PASS npm test --prefix site
  • PASS cargo build --locked
  • PASS npm test --prefix console
  • cargo test had 2 failures, both outside this change:
    • process::findings::closing_rechecks_each_merged_base_and_leaves_a_failing_finding_for_the_day_shift fails the same way on the base issue-2036 (panicked at tests/process/findings.rs:331:5), checked in a detached worktree.
    • process::findings::merged_fix_is_rechecked_after_a_later_fix_fails passed when rerun.

Visual evidence

The Gist upload of the captures was blocked by this session's permission rules, so the images are not embedded. They are kept locally at the session's capture paths (same viewport and state, /metrics?window=30d):

• 1440×900 desktop:
  • Before, this machine only: /tmp/before-desktop.IRXiR1.png
  • After, Fleet view with peer east: /tmp/after-desktop.yZE05G.png
  • After, peer stopped and shown as cached, offline · last seen …: /tmp/after-desktop-cached.F9UolN.png
• 390×844 mobile:
  • Before: /tmp/before-mobile.1QViFY.png
  • After: /tmp/after-mobile.UUY5s6.png

The After captures were taken before the review fixes. Those fixes changed only the Fleet option's value (now empty) and the badge colour token (--look → --look-text).

Merge Danger

Door: two-way

This adds new flags, a new page view, and a cache directory, ~/.thirdshift/logs/fleet-metrics/, that is safe to delete. No record formats change.

Blast Radius: Metrics

• Once a Fleet machine is paired, /metrics opens on the Fleet view instead of this machine. This machine is one choice away.
• /api/v1/metrics now answers 400 to fleet and machine query keys, which it rejected before as unknown arguments.

Unaddressed findings

Standards

All judgement calls; no hard violations were reported.

• 2. Duplicated Code: remote() and its fan-out mirror src/cronjobs/fleet.rs. Only the error classification is shared (Failure::of, in src/console/fleet/read.rs). The readers decode different documents, and only metrics falls back to a cache (src/logs/metrics/fleet.rs remote). A generic reader would mean refactoring cronjobs --fleet, which is beyond Fleet Metrics aggregation (metrics --fleet), default Fleet scope, and local peer-snapshot cache #2068.
• 3. Repeated Switches: Failure→Status in two files. The Status enums differ on purpose: metrics adds Cached (src/logs/metrics/fleet.rs enum Status). The repeated part is three match arms.
• 4. Mirror Summary* types restate Trends.
  • These types are the wire contract with other machines, which may run older versions.
  • Trends holds &'static str fields and cannot be deserialized (src/logs/metrics/outcomes.rs Bucket.kind).
  • A silent drop is caught by the e2e test, which compares the Fleet totals against each machine's own metrics.
• 5. Bar macro and legend copied into metrics_fleet.html. This is presentational and a few lines long. The shared form was extracted to metrics_form.html.
• 6. Data Clumps: FleetPage and MetricsPage fields. Both pages are built in one function, src/console/metrics.rs show.
• 7. "This machine's name means local" decided twice. The CLI (logs::metrics::reads_fleet) and the page resolve different inputs. The page also has a no-machine default that the CLI lacks.
• 8 (part). "snapshot" and "summary" wording drift. The user-visible notes say "snapshot"; the guide says "saved summary". The other renames in this finding were made.
• 9. metrics --machine other adds no parity coverage. It is kept to document that --machine shares the --fleet exclusion (comment in identity, src/console/parity.rs). ADR 0026 names both flags.
• 10 (part). fleet-metrics/ is listed up to three times per request. Each listing is a small directory read with no user-visible cost. The duplicated cli construction in this finding was fixed.

Security

None. The one finding introduced by this change was fixed and its test is kept.

Spec

None. All three Spec findings were fixed and their tests are kept.

Review coverage

Every changed file was read by both reviewers, except site/docs/index.html. That file is generated from docs/guide.md and was excluded from reading; npm run docs:check --prefix site passes.

Built with claude 2.1.314 · opus · default effort

Security review outcome

No unaddressed introduced findings.