s1d3sw1ped/steamcache2
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases 32 Wiki Activity

docs: Deduplicate validate-check helper
CI / vulncheck (pull_request) Successful in 14s
Details
CI / check-and-test (pull_request) Successful in 41s
Details

Browse Source 
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: #29
This commit is contained in:
pike
2026-09-03 05:18:19 +00:00
parent ff1ab31327
commit 8b1b229539
3 changed files with 26 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Makefile
+11 -13
View File
@@ -62,15 +62,7 @@ validate run-validation: build clean-disk ## Start steamcache2 on :80 with small
fi; \ fi; \
exec "$$BINARY" --config docs/examples/validate-config.yaml --log-level info 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) validate-check: ## Curl local /metrics (full dump + hit/miss fields) and /lancache-heartbeat (default :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 ===" @echo "=== http://localhost/metrics ==="
@metrics=$$(curl -sf --max-time 5 http://localhost/metrics) || { \ @metrics=$$(curl -sf --max-time 5 http://localhost/metrics) || { \
echo "ERROR: could not fetch 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 ==="; \ 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; \ printf '%s\n' "$$metrics" | grep -E '^(total_requests|cache_hits|cache_misses|hit_rate|memory_cache_hits|disk_cache_hits|errors) ' || true; \
echo ""; \ echo ""; \
echo "=== http://localhost/lancache-heartbeat (expect 204 + X-LanCache-Processed-By: SteamCache2) ==="; \ echo "=== http://localhost/lancache-heartbeat (GET; expect 204 + X-LanCache-Processed-By: SteamCache2) ==="; \
curl -sD - -o /dev/null --max-time 5 http://localhost/lancache-heartbeat || { \ hb=$$(curl -sD - -o /dev/null --max-time 5 http://localhost/lancache-heartbeat) || { \
echo "ERROR: could not fetch 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; \ exit 1; \
} }
@@ -135,7 +133,7 @@ help: ## Show this help message
@echo " clean-disk Remove disk cache" @echo " clean-disk Remove disk cache"
@echo " bench Run low-level VFS microbenchmarks" @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 / 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 " setcap Explicitly set cap on current build (for port 80 use outside validate)"
@echo " validate-kill Kill leftover steamcache2 processes (safer)" @echo " validate-kill Kill leftover steamcache2 processes (safer)"
@echo " prefill Download latest SteamPrefill into bin/steam-prefill/SteamPrefill (gitignored)" @echo " prefill Download latest SteamPrefill into bin/steam-prefill/SteamPrefill (gitignored)"
README.md
+11 -13
View File
@@ -59,11 +59,12 @@ After steamcache2 is running (default `listen_address: :80`) and has seen a litt
```bash ```bash
make validate-check make validate-check
# or: # or, manually:
curl -s http://localhost/metrics 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 | | Field | Meaning |
| --- | --- | | --- | --- |
@@ -128,12 +129,13 @@ When the server is running, point your external SteamPrefill (or other load gene
./SteamPrefill benchmark run ... ./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 ```bash
make validate-check make validate-check
# or: # or, manually:
curl -s http://localhost/metrics 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. 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 ```bash
make validate-check make validate-check
# or manually: # or, manually:
curl -s http://localhost/metrics 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`) - 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 - 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`). Heartbeat should be HTTP 204 with `X-LanCache-Processed-By: SteamCache2`. Use GET (`curl -i`), not HEAD (`curl -I`).
#### The Validation Config #### The Validation Config
@@ -409,12 +412,7 @@ make
- Adjust the disk cache size to match available storage - Adjust the disk cache size to match available storage
6. **Not sure if it is caching** 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` - 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`)
- `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` - 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) - Confirm the process is up with `curl -s -i http://localhost/lancache-heartbeat` (GET, not HEAD)
docs/examples/validate-config.yaml
+4 -3
View File
@@ -27,9 +27,10 @@
# SteamPrefill benchmark run -c 20 ... # SteamPrefill benchmark run -c 20 ...
# #
# After the benchmark run, inspect with: # After the benchmark run, inspect with:
# make validate-check # make validate-check # full /metrics + hit/miss fields + /lancache-heartbeat
# # or: curl -s http://localhost/metrics # # or, manually:
# Heartbeat (process up): curl -s -i http://localhost/lancache-heartbeat # 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 # 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). # exercising the disk tier (workload >> RAM is ideal for real disk testing).