Operator clarity: one README-facing "is it caching?" check #29

New Issue

2026-09-03T00:04:05-05:00

linus commented

2026-09-03 00:04:05 -05:00

Problem

steamcache2 ships and already has hit/miss metrics (/metrics, /lancache-heartbeat). The README buries that under long SteamPrefill validation. Justin shouldn’t have to dig logs or run a full benchmark to answer "is it caching?".

Goal

One obvious, README-facing operator check for the existing cache product — not a new monitoring product.

Scope (do) — prefer net-simpler

Front-and-center Quick check (or equivalent) in README: after a short run with traffic, how to confirm hit vs miss (existing /metrics fields are fine).
If the existing endpoints are enough, document them — do not invent a second metrics system.
Only add a tiny helper (Makefile target or one-liner script) if curl + README is still too opaque; keep it dumb.

Out of scope

Prometheus stack, dashboards, new auth on metrics, redesigning storage tiers, SteamPrefill rewrite.

Acceptance

README has a short operator section: start cache → generate a little traffic → run the check → read hit/miss (or heartbeat) without reading the whole validation chapter.
Documented commands work against a local default listen address from current config defaults.
No new daemon/sidecar.

Docs bar

README update is the product change here. Sibling docs that claim how to verify caching must match. Same PR.

Owner

@pike — wait for this issue; one PR.

## Problem steamcache2 ships and already has hit/miss metrics (`/metrics`, `/lancache-heartbeat`). The README buries that under long SteamPrefill validation. Justin shouldn’t have to dig logs or run a full benchmark to answer "is it caching?". ## Goal One obvious, README-facing operator check for the existing cache product — not a new monitoring product. ## Scope (do) — prefer net-simpler - Front-and-center Quick check (or equivalent) in README: after a short run with traffic, how to confirm hit vs miss (existing `/metrics` fields are fine). - If the existing endpoints are enough, **document them** — do not invent a second metrics system. - Only add a tiny helper (Makefile target or one-liner script) if curl + README is still too opaque; keep it dumb. ## Out of scope - Prometheus stack, dashboards, new auth on metrics, redesigning storage tiers, SteamPrefill rewrite. ## Acceptance 1. README has a short operator section: start cache → generate a little traffic → run the check → read hit/miss (or heartbeat) without reading the whole validation chapter. 2. Documented commands work against a local default listen address from current config defaults. 3. No new daemon/sidecar. ## Docs bar README update **is** the product change here. Sibling docs that claim how to verify caching must match. Same PR. ## Owner @pike — wait for this issue; one PR.

pike referenced this issue from a commit

2026-09-03 00:16:20 -05:00

docs: Add README operator cache check

pike referenced a pull request that will close this issue

2026-09-03 00:16:39 -05:00

docs: Add README operator cache check #30

pike referenced this issue from a commit

2026-09-03 00:18:24 -05:00

docs: Deduplicate validate-check helper

linus closed this issue

2026-09-03 00:19:53 -05:00

linus referenced this issue from a commit