From ff1ab3132798dcdf7557dc5c20fbed5d7349ef3d Mon Sep 17 00:00:00 2001 From: pike Date: Thu, 3 Sep 2026 05:16:14 +0000 Subject: [PATCH] docs: Add README operator cache check MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The README buried hit/miss verification under the SteamPrefill validation chapter, and advertised make validate-check without a Makefile target. Operators need a short start → traffic → metrics path against the existing /metrics and /lancache-heartbeat endpoints. Link: https://git.s1d3sw1ped.com/s1d3sw1ped/steamcache2/issues/29 --- Makefile | 27 ++++++++++++++++ README.md | 52 ++++++++++++++++++++++++++++-- docs/examples/validate-config.yaml | 4 ++- 3 files changed, 79 insertions(+), 4 deletions(-) diff --git a/Makefile b/Makefile index c1db98c..745926e 100644 --- a/Makefile +++ b/Makefile @@ -62,6 +62,32 @@ validate run-validation: build clean-disk ## Start steamcache2 on :80 with small fi; \ exec "$$BINARY" --config docs/examples/validate-config.yaml --log-level info +validate-check: ## Print hit/miss fields from http://localhost/metrics (default listen_address :80) + @echo "=== steamcache2 cache check (http://localhost/metrics) ===" + @curl -sS --fail --max-time 5 http://localhost/metrics | grep -E '^(total_requests|cache_hits|cache_misses|hit_rate|memory_cache_hits|disk_cache_hits|errors) ' || { \ + echo "ERROR: could not read hit/miss metrics from http://localhost/metrics"; \ + echo "Is steamcache2 running on the default listen address (:80)?"; \ + exit 1; \ + } + +validate-check: ## Curl local /metrics (hit/miss) and /lancache-heartbeat (default :80) + @echo "=== http://localhost/metrics ===" + @metrics=$$(curl -sf --max-time 5 http://localhost/metrics) || { \ + echo "ERROR: could not fetch http://localhost/metrics"; \ + echo "Is steamcache2 running on the default listen address :80?"; \ + exit 1; \ + }; \ + printf '%s\n' "$$metrics"; \ + echo ""; \ + echo "=== hit/miss fields ==="; \ + printf '%s\n' "$$metrics" | grep -E '^(total_requests|cache_hits|cache_misses|hit_rate|memory_cache_hits|disk_cache_hits|errors) ' || true; \ + echo ""; \ + echo "=== http://localhost/lancache-heartbeat (expect 204 + X-LanCache-Processed-By: SteamCache2) ==="; \ + curl -sD - -o /dev/null --max-time 5 http://localhost/lancache-heartbeat || { \ + echo "ERROR: could not fetch http://localhost/lancache-heartbeat"; \ + exit 1; \ + } + validate-kill: ## Kill leftover steamcache2 processes (safer, checks process name) @echo "Looking for steamcache2 processes on common validation ports (80 is primary)..." @for port in 80 8040 8080; do \ @@ -109,6 +135,7 @@ help: ## Show this help message @echo " clean-disk Remove disk cache" @echo " bench Run low-level VFS microbenchmarks" @echo " validate / run-validation Start server on :80 (builds, auto-setcaps fresh binary, then runs as normal user, cleans disk cache first)" + @echo " validate-check Print hit/miss fields from http://localhost/metrics (default listen :80)" @echo " setcap Explicitly set cap on current build (for port 80 use outside validate)" @echo " validate-kill Kill leftover steamcache2 processes (safer)" @echo " prefill Download latest SteamPrefill into bin/steam-prefill/SteamPrefill (gitignored)" \ No newline at end of file diff --git a/README.md b/README.md index 5a88e2a..52da1e6 100644 --- a/README.md +++ b/README.md @@ -53,6 +53,38 @@ SteamCache2 is a blazing fast download cache for Steam, designed to reduce bandw make run # or ./steamcache2 ``` +### Quick check: is it caching? + +After steamcache2 is running (default `listen_address: :80`) and has seen a little Steam traffic — a game download, a short SteamPrefill pass, or any cacheable request — confirm hits vs misses from the existing endpoints. You do not need a full benchmark or log diving. + +```bash +make validate-check +# or: +curl -s http://localhost/metrics +``` + +Read these fields: + +| Field | Meaning | +| --- | --- | +| `cache_hits` / `cache_misses` / `hit_rate` | Whether later requests were served from cache | +| `memory_cache_hits` / `disk_cache_hits` | Which tier served the hits | +| `total_requests` / `errors` | Volume and failures | + +A first pass through new content is mostly misses (`hit_rate` near 0). Repeat the same content and `cache_hits` / `hit_rate` should rise. + +To confirm the process is up (HTTP 204 and `X-LanCache-Processed-By: SteamCache2`): + +```bash +curl -s -i http://localhost/lancache-heartbeat +``` + +Use GET (`curl -i`), not HEAD (`curl -I`): the server only accepts GET. + +These are the cache process's own `/metrics` and `/lancache-heartbeat` endpoints. There is no separate metrics daemon. + +If you changed `listen_address`, point curl at that host:port instead. For a full SteamPrefill validation workflow (small caches, coalescing, GC), see [Validating Full Functionality](#validating-full-functionality-with-external-tools). + ### Development Workflow Use `make` for the majority of common development tasks. The Makefile handles running tests, linting, hygiene checks, building, running the application, and other routine boilerplate work. @@ -100,9 +132,11 @@ When finished, you can get a quick metrics summary with: ```bash make validate-check +# or: +curl -s http://localhost/metrics ``` -This is the recommended simple workflow. No automatic downloading or running of external tools. +See [Quick check: is it caching?](#quick-check-is-it-caching) for which fields to read. This is the recommended simple workflow. No automatic downloading or running of external tools. #### Inspecting the Result @@ -115,9 +149,11 @@ curl -s http://localhost/metrics ``` Look for: -- High cache hit rate after the warmup pass +- High cache hit rate after the warmup pass (`cache_hits`, `hit_rate`, plus `memory_cache_hits` / `disk_cache_hits`) - Non-zero `coalesced` and `disk` activity -- Zero unexpected errors +- Zero unexpected `errors` + +Heartbeat is the same as the operator check: `curl -s -i http://localhost/lancache-heartbeat` (HTTP 204, `X-LanCache-Processed-By: SteamCache2`). #### The Validation Config @@ -372,6 +408,16 @@ make - Consider using a different GC algorithm like `hybrid` - Adjust the disk cache size to match available storage +6. **Not sure if it is caching** + - Do not start with the full SteamPrefill chapter. Use [Quick check: is it caching?](#quick-check-is-it-caching): `make validate-check` or `curl -s http://localhost/metrics` + - `cache_misses` on the first request is expected; a repeat of the same object should increment `cache_hits` + - `curl -si http://localhost/lancache-heartbeat` should return 204 and `X-LanCache-Processed-By: SteamCache2` + +6. **Not sure if it is caching** + - See [Quick check: is it caching?](#quick-check-is-it-caching): `make validate-check` or `curl -s http://localhost/metrics` + - A first pass is mostly `cache_misses`; repeating the same content should raise `cache_hits` / `hit_rate` + - Confirm the process is up with `curl -s -i http://localhost/lancache-heartbeat` (GET, not HEAD) + ### Getting Help - Check the logs for detailed error messages diff --git a/docs/examples/validate-config.yaml b/docs/examples/validate-config.yaml index 9546661..52ef182 100644 --- a/docs/examples/validate-config.yaml +++ b/docs/examples/validate-config.yaml @@ -27,7 +27,9 @@ # SteamPrefill benchmark run -c 20 ... # # After the benchmark run, inspect with: -# curl -s http://localhost/metrics +# make validate-check +# # or: curl -s http://localhost/metrics +# Heartbeat (process up): curl -s -i http://localhost/lancache-heartbeat # # Tweak sizes upward if you want to run very large workloads while still # exercising the disk tier (workload >> RAM is ideal for real disk testing).