From ff1ab3132798dcdf7557dc5c20fbed5d7349ef3d Mon Sep 17 00:00:00 2001 From: pike Date: Thu, 3 Sep 2026 05:16:14 +0000 Subject: [PATCH 1/2] 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). From 8b1b22953964f80e5a53519930e389cec367d8a7 Mon Sep 17 00:00:00 2001 From: pike Date: Thu, 3 Sep 2026 05:18:19 +0000 Subject: [PATCH 2/2] 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).