refactor: improve local development resilience and add SKIP_TUNE

- Make CPU pinning (cpuset-cpus) dynamic based on host core count
- Add SKIP_TUNE environment variable to bypass sudo-required system tuning
- Update documentation to reflect new dynamic defaults and configuration options

Author: kevmoo

scripts/benchmark.sh

@@ -90,7 +90,11 @@ cleanup_all() {
     docker volume prune -f >/dev/null 2>&1 || true
     docker image prune  -f >/dev/null 2>&1 || true
 }
-trap 'cleanup_all; system_restore' EXIT
+if [ "${SKIP_TUNE:-}" != "true" ]; then
+    trap 'cleanup_all; system_restore' EXIT
+else
+    trap 'cleanup_all' EXIT
+fi
 
 # Clean slate: stop any leftover benchmark containers from a previous
 # crashed run, AND prune any leftover dangling volumes/images from the
@@ -171,7 +175,11 @@ $_has_isolated_test && framework_build
 
 # ── System tuning — NOW, after all image builds are complete ───────────────
 
-system_tune
+if [ "${SKIP_TUNE:-}" != "true" ]; then
+    system_tune
+else
+    info "skipping system tuning as requested (SKIP_TUNE=true)"
+fi
 
 # Start the postgres sidecar if any subscribed test needs it.
 need_pg=false

scripts/lib/common.sh

@@ -29,7 +29,23 @@ H3THREADS="${H3THREADS:-64}"
 GCANNON="${GCANNON:-gcannon}"
 GCANNON_IMAGE="${GCANNON_IMAGE:-gcannon:latest}"
 GCANNON_MODE="${GCANNON_MODE:-native}"
-GCANNON_CPUS="${GCANNON_CPUS:-32-63,96-127}"
+
+_AVAIL_CORES=$(nproc 2>/dev/null || echo 1)
+if [ -z "${GCANNON_CPUS:-}" ]; then
+    if [ "$_AVAIL_CORES" -ge 128 ]; then
+        GCANNON_CPUS="32-63,96-127"
+    else
+        # For smaller machines, just use the second half of cores for load gen, 
+        # or all cores if we only have 1 or 2.
+        if [ "$_AVAIL_CORES" -le 2 ]; then
+            GCANNON_CPUS="0-$((_AVAIL_CORES - 1))"
+        else
+            _HALF=$((_AVAIL_CORES / 2))
+            GCANNON_CPUS="$_HALF-$((_AVAIL_CORES - 1))"
+        fi
+    fi
+fi
+export GCANNON_CPUS
 
 H2LOAD="${H2LOAD:-h2load}"
 H2LOAD_IMAGE="${H2LOAD_IMAGE:-h2load:latest}"

scripts/lib/framework.sh

@@ -95,7 +95,18 @@ framework_start() {
     # Profile-declared CPU limit.
     if [ -n "$cpu_limit" ]; then
         if [[ "$cpu_limit" == *-* ]]; then
-            args+=(--cpuset-cpus="$cpu_limit")
+            local max_cpu
+            max_cpu=$(($(nproc)-1))
+            # Extract the largest CPU index from the cpuset string (e.g. "95" from "0-31,64-95")
+            local requested_max
+            requested_max=$(echo "$cpu_limit" | grep -oP '\d+$')
+            
+            if [ "$requested_max" -gt "$max_cpu" ]; then
+                warn "profile cpuset $cpu_limit exceeds available CPUs (max $max_cpu) — using all cores"
+                args+=(--cpus="$(nproc)")
+            else
+                args+=(--cpuset-cpus="$cpu_limit")
+            fi
         else
             local avail
             avail=$(nproc 2>/dev/null || echo 64)

site/content/docs/running-locally/configuration.md

@@ -16,6 +16,7 @@ Defined in `scripts/lib/common.sh`. Override by exporting before you run the scr
 | `THREADS` | `64` | gcannon / wrk worker threads. |
 | `H2THREADS` | `64` | h2load worker threads (HTTP/2, h2c gRPC). |
 | `H3THREADS` | `64` | h2load-h3 worker threads (HTTP/3 over QUIC). |
+| `SKIP_TUNE` | `false` | When `true`, skips kernel/hardware tuning (CPU governor, socket limits) that requires `sudo`. Useful for local development. |
 
 In `benchmark-lite.sh`, `THREADS` defaults to `max(nproc / 2, 1)` and `H2THREADS` / `H3THREADS` mirror `$THREADS`. Pass `--load-threads N` to override all three in one shot.
 
@@ -36,7 +37,7 @@ Every framework `Dockerfile` reads the same defaults from its env, so you rarely
 |---|---|---|
 | `LOADGEN_DOCKER` | `false` | When `true`, every load generator runs from its Docker image instead of the host binary. Builds missing images automatically from `docker/*.Dockerfile`. Forced `true` by `benchmark-lite.sh`. |
 | `GCANNON_MODE` | `native` | `native` or `docker`. Implied by `LOADGEN_DOCKER`. |
-| `GCANNON_CPUS` | `32-63,96-127` | CPU list the load generators run on. Native mode wraps calls in `taskset -c $GCANNON_CPUS`; docker mode passes it via `--cpuset-cpus`. `benchmark-lite.sh` sets this to `0-$((nproc-1))`. |
+| `GCANNON_CPUS` | dynamic | CPU list the load generators run on. Native mode wraps calls in `taskset -c $GCANNON_CPUS`; docker mode passes it via `--cpuset-cpus`. Defaults to the upper half of available cores on smaller machines to avoid resource contention with the server. |
 
 ## Tool binaries and images