From 8b1b22953964f80e5a53519930e389cec367d8a7 Mon Sep 17 00:00:00 2001 From: pike Date: Thu, 3 Sep 2026 05:18:19 +0000 Subject: [PATCH] docs: Deduplicate validate-check helper Keep a single Makefile validate-check target that prints the full /metrics dump, highlights hit/miss fields, and curls /lancache-heartbeat. Drop the duplicate README troubleshooting item and align the validation chapter plus validate-config.yaml comments with that behavior. Link: https://git.s1d3sw1ped.com/s1d3sw1ped/steamcache2/issues/29 --- Makefile | 24 +++++++++++------------- README.md | 24 +++++++++++------------- docs/examples/validate-config.yaml | 7 ++++--- 3 files changed, 26 insertions(+), 29 deletions(-) diff --git a/Makefile b/Makefile index 745926e..9230f4a 100644 --- a/Makefile +++ b/Makefile @@ -62,15 +62,7 @@ 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) +validate-check: ## Curl local /metrics (full dump + hit/miss fields) 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"; \ @@ -82,9 +74,15 @@ validate-check: ## Curl local /metrics (hit/miss) and /lancache-heartbeat (defau 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 "=== http://localhost/lancache-heartbeat (GET; expect 204 + X-LanCache-Processed-By: SteamCache2) ==="; \ + hb=$$(curl -sD - -o /dev/null --max-time 5 http://localhost/lancache-heartbeat) || { \ echo "ERROR: could not fetch http://localhost/lancache-heartbeat"; \ + echo "Is steamcache2 running on the default listen address :80?"; \ + exit 1; \ + }; \ + printf '%s\n' "$$hb"; \ + echo "$$hb" | grep -q '204' && echo "$$hb" | grep -qi 'X-LanCache-Processed-By' || { \ + echo "ERROR: expected HTTP 204 and X-LanCache-Processed-By on /lancache-heartbeat"; \ exit 1; \ } @@ -135,7 +133,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 " validate-check Curl local /metrics (full dump + hit/miss fields) and /lancache-heartbeat (default :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 + @echo " prefill Download latest SteamPrefill into bin/steam-prefill/SteamPrefill (gitignored)" diff --git a/README.md b/README.md index 52da1e6..486ef9b 100644 --- a/README.md +++ b/README.md @@ -59,11 +59,12 @@ After steamcache2 is running (default `listen_address: :80`) and has seen a litt ```bash make validate-check -# or: +# or, manually: curl -s http://localhost/metrics +curl -s -i http://localhost/lancache-heartbeat ``` -Read these fields: +`make validate-check` prints the full `/metrics` dump, highlights hit/miss fields, and curls `/lancache-heartbeat`. Read these fields: | Field | Meaning | | --- | --- | @@ -128,12 +129,13 @@ When the server is running, point your external SteamPrefill (or other load gene ./SteamPrefill benchmark run ... ``` -When finished, you can get a quick metrics summary with: +When finished, you can get a quick metrics + heartbeat report with: ```bash make validate-check -# or: +# or, manually: curl -s http://localhost/metrics +curl -s -i http://localhost/lancache-heartbeat ``` 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. @@ -144,16 +146,17 @@ After a benchmark run you can ask for a quick report: ```bash make validate-check -# or manually: +# or, manually: curl -s http://localhost/metrics +curl -s -i http://localhost/lancache-heartbeat ``` -Look for: +`make validate-check` prints the full `/metrics` dump, highlights hit/miss fields, and curls `/lancache-heartbeat`. Look for: - 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` -Heartbeat is the same as the operator check: `curl -s -i http://localhost/lancache-heartbeat` (HTTP 204, `X-LanCache-Processed-By: SteamCache2`). +Heartbeat should be HTTP 204 with `X-LanCache-Processed-By: SteamCache2`. Use GET (`curl -i`), not HEAD (`curl -I`). #### The Validation Config @@ -409,12 +412,7 @@ make - 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` + - Do not start with the full SteamPrefill chapter. Use [Quick check: is it caching?](#quick-check-is-it-caching): `make validate-check` (full `/metrics`, hit/miss fields, and `/lancache-heartbeat`) - 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) diff --git a/docs/examples/validate-config.yaml b/docs/examples/validate-config.yaml index 52ef182..1b43278 100644 --- a/docs/examples/validate-config.yaml +++ b/docs/examples/validate-config.yaml @@ -27,9 +27,10 @@ # SteamPrefill benchmark run -c 20 ... # # After the benchmark run, inspect with: -# make validate-check -# # or: curl -s http://localhost/metrics -# Heartbeat (process up): curl -s -i http://localhost/lancache-heartbeat +# make validate-check # full /metrics + hit/miss fields + /lancache-heartbeat +# # or, manually: +# curl -s http://localhost/metrics +# curl -s -i http://localhost/lancache-heartbeat # GET, not HEAD # # 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).