valve_

CLI reference

Perf harness commands, profiles, workload selectors, timing options, environment variables, and exit codes.

Invoke the private workspace CLI from the repository root:

pnpm perf <command> [options]
pnpm perf --help

Options are validated per command. Unknown commands, unsupported flags, invalid numbers, and conflicting selectors are rejected. Use Run benchmarks for complete workflows.

Commands

CommandBehavior and defaults
doctorCapture host capabilities, environment information, and timer lateness.
calibrate [--reps 3]Measure cold-process overhead and write host-local planning calibration. Supports --isolate.
build [--ref REF] [--patch FILE]Build and freeze the current checkout or a git revision. A patch requires --ref. Prints the build identity.
micro [--quick] [--filter TEXT]Run Tinybench in-process suites; filter by name and optionally reduce measurement time.
modelRun portable admission-model, capacity, golden, and oracle checks. Real-server parity belongs to integration tests.
quick [--filter TEXT]Run model, then reduced micro suites. The filter applies to microbenchmarks.
footprint [--check] [--base REF]Bundle source and dist entries and consumers with the same esbuild settings, record gzip sizes and module attribution. --check enforces the candidate's current source-entry budgets.
startup [--base REF] [--reps 3]Alternate build order across three default pairs, with ten fresh Node processes per entry/build/pair. Record import/init time, CPU, heap, RSS, and peak RSS; filesystem caches remain shared.
scoped [--stores memory] [--iterations 100] [--base REF]Probe public Store.acquireScoped: batches 1/32/128, rules 2/8/16, cold/hot/mixed identities, and 1/4/8-client contention in one Node process. Denial evaluations are separate from grants.
drift [--base REF] [--jobs 200] [--response-ms 0] [--reps 3]Cold-process pacing at 100/s, burst 1, after 32 warmup jobs. Record public-store calls, queue wait, callback drift, CPU, memory, GC, and event-loop delay. No private wake/admission timestamps.
plan [--profile targeted]Print selected cells, skipped cells, arms, looks, and calibrated estimate. Builds and trials do not execute.
smokeShort real-time correctness trials; default smoke profile and one replication. Missing store coverage is listed explicitly.
matrix --base REF [--head REF|--current]Compare baseline/A/A/candidate arms; default targeted profile, current checkout as candidate.
libs [--category L1,L2,D1]Compare supported library/category cells with Valve A/A and separate distributed Valve audits.
soak [--suite lease] [--duration 4h]One continuous stateful trial per selected suite; default one-hour window and total offered load of two jobs/second.
chaos [--faults TYPE,...]Execute the selected fault-suite cells, with instrumented correctness arms.
c1 [--stores memory,redis74]Verify the deadline regression: the later callback must reject with MAX_WAIT_EXCEEDED without starting after the earlier job stalls past its deadline.
report RUN_ID [--html]Render saved summary/local diagnostic data as reports. Does not rerun trials or recompute measurements from raw payloads.
legacy catalog [--archive DIR]Inspect a configured read-only pre-harness evidence archive.
legacy golden [--archive DIR]Replay archived analyzers to regenerate legacy golden evidence. Requires the external archive.

The four diagnostic commands footprint, startup, scoped, and drift accept --base REF and --head REF; the candidate otherwise comes from the current checkout. Both artifacts are built before sampling, and the current harness measures both. Startup, scoped, and drift remain descriptive.

Infrastructure commands

pnpm perf infra up redis74,valkey8
pnpm perf infra status
pnpm perf infra down redis74,valkey8
pnpm perf infra adopt redis://127.0.0.1:6379 --empty-only --name local-perf
pnpm perf infra images redis74 --build
pnpm perf infra up redis74-netem

up accepts --cpuset CPUS and --recreate. Without names, up selects Redis 7.4 and Valkey 8; down selects all registered servers. Supplying names makes cleanup explicit. status reports reachability, sentinel validity, and container identity. images checks netem image availability; --build builds the local netem image. Netem containers use locally built images with network-control tools for delay/jitter cells.

NameDocker imagePublished host port
redis62redis:6.216462
redis74redis:7.416479
redis8redis:816481
valkey72valkey/valkey:7.216472
valkey8valkey/valkey:816480

-netem variants are also recognized, as are locally registered adopted names. Linux normally connects through direct container IPs rather than published ports. Adoption requires an empty database and makes it disposable; see store ownership.

Profiles

Profiles select cells, replications, audits, and the decision plan. Use plan --profile NAME or the intended execution command's --dry-run to see the concrete selection on your host.

ProfileSelectionDefault replication looksAuditDefault budget
smokeAvailable smoke cells, with additional core Valkey coverage1Main trials instrumentedNone
targetedRisk cells of selected suites; all suites if not filtered5SeparateNone
sylvieFocused two-worker GCRA and lease cells10SeparateNone
nightlyRisk cells selected by priority within budget5Separate40 minutes
decisionRisk cells plus deterministic pairwise covering cells5, 10, 20SeparateNone

pnpm perf:sylvie is shorthand for pnpm perf matrix --profile sylvie and defaults to HEAD versus current. Sylvie is supported by matrix and plan. It requires isolation and authoritative execution. Other matrix profiles need an explicit --base.

--reps N replaces the profile's staged looks with one fixed-N look. Choose it before execution. The decision profile evaluates only its preregistered looks and can stop resolved cells early.

Suites

--suite accepts comma-separated suite names:

SuiteCoverage
gcraGCRA rate/burst admission and saturated or offered demand.
fixed-windowEpoch-aligned fixed-window rules and boundaries.
multi-ruleAtomic admission across several rules.
scopedIdentity-specific and shared rule combinations.
weightedWeighted costs and prefix head-of-line effects.
leaseGlobal concurrency, lease expiry/renewal, subscriber variants.
combinedRate rules and global leases in the same admission.
deadlinesQueue deadlines and late-start exposure.
storesCorrectness and risk cells across Redis/Valkey versions.
lifecyclePause/resume/close and related lifecycle behavior.
faultsDeclared worker/server faults and recovery.
runtimeRuntime overhead and background-work cells.
networkStore RTT delay/jitter; requires netem infrastructure.
apiPublic API workload cells.

Not every suite has every store variant. --stores filters generated cells; it does not manufacture a Cartesian product of every suite and store. Inspect skipped cells, especially for version and network suites.

Fault selectors

The default chaos suite accepts these --faults types:

TypeMechanism
client-killDisconnect server clients to exercise reconnection.
redis-restartRestart the disposable server without persistence.
redis-pausePause the server beyond the workload's lease TTL.
redis-stallRun a calibrated blocking server operation.
redis-cpuApply background CPU duty to the server.
redis-loadApply competing command load.

Worker-kill and late-join fault specifications (kill-workers, spawn-workers) also exist in declared suite cells. A filter only selects fault types available in the chosen suite's cells; it does not add a new fault or configure its parameters. Use --dry-run to inspect selection.

Library comparison categories

CategoryContractOther libraries
L1Local concurrency with 1 ms async jobsp-limit, p-queue, Bottleneck
L1-noopLocal concurrency with synchronous no-op jobsp-limit, p-queue, Bottleneck; analyzed separately from L1
L2Local burst-1 pacingp-queue, Bottleneck
L3Local fixed-window quotap-queue, Bottleneck; window anchoring differs
L4Local burst bankBottleneck, approximate mapping only
L5Queued cancellationp-queue; only still-queued jobs are cancelled
D1Distributed global concurrencyBottleneck clustering
D2Distributed burst-1 pacingBottleneck clustering
D3Distributed window quotaBottleneck clustering

Valve-only features such as scoped admission, multiple atomic rules, and weighted atomic admission are N/A for competitors that lack the contract. An identity adapter invokes jobs directly as a harness-floor control. Floor measurements are raw absolutes; nothing is subtracted from results.

Real-time options

These options belong to the shared planning/execution commands: plan, smoke, matrix, libs, soak, and chaos. Their effect depends on the selected tier; use --dry-run to check the resulting cells. They are not universal flags for portable commands.

Selection and build identity

OptionMeaning
--profile NAMESelect a named profile. Smoke defaults to smoke; matrix defaults to targeted.
--suite NAME,...Select workload suites.
--stores NAME,...Select stores, including memory. --store is an alias; do not supply both.
--category ID,...Select library categories for libs.
--faults TYPE,...Filter fault cells in chaos; unknown types are rejected.
--cell TEXTKeep cell IDs containing the text.
--limit-cells NKeep the first N cells after priority/ID ordering; report exclusions.
--base REFBaseline git ref, or current for the working checkout. Required for ordinary matrix execution.
--head REFCandidate git ref; mutually exclusive with --current.
--currentExplicitly select the working checkout candidate.
--patch FILEBuild a patched candidate from --head, otherwise the baseline ref (or HEAD for a current baseline). Resolved relative to the invoking directory.
--rebuildRequest a current-checkout rebuild. Real-time current builds already rebuild by default.
--endpoint URLOverride selected Redis addresses with a redis:// or rediss:// URL; execution is non-authoritative.

Timing and workload

OptionRange/default and meaning
--reps N1-100 independent repetitions; otherwise use profile looks.
--seed NInteger 0-4294967295; real-time default 42. Derives workload and ordering seeds.
--workers N1-64 processes; overrides selected cells. Sylvie allows at most two.
--window DURATIONOverride measurement window; bare numbers are seconds, or use 2s, 40m, 4h. Positive, at most 12 hours.
--duration DURATIONAlias for --window; also used for continuous soak duration.
--window-ms NWindow in milliseconds, 1-43200000. Supply only one window spelling.
--warmup-ms N0-3600000 ms; otherwise the cell's warmup.
--drain-ms N0-3600000 ms after the window to observe outcomes; otherwise the cell's drain.
--rate NSoak's total offered jobs/second, 0.001-10000; default 2.
--budget DURATIONPositive, at most 12 hours. Select complete cells that fit the estimated budget.

Window overrides scale fault times to keep the requested fault within a short sample. They change the plan and its evidential strength.

Execution and output

OptionMeaning
--dry-runPrint the plan without builds or trial execution. plan always does this.
--yesAllow execution when the estimate exceeds 60 minutes.
--isolateRe-exec in a protected systemd user scope and apply worker affinity.
--worker-cpus CPUSCPU list such as 0-3,6; keep separate from pinned server CPUs.
--require-authoritativeFail before trials if required execution controls are missing.
--run-id IDChoose a safe run-directory name; reuse only with identical measurement inputs to resume.
--htmlWrite a self-contained HTML report in addition to standard report formats.
--keep-rawRetain raw NDJSON streams and worker configs after compressed payload creation.

Environment variables

VariablePurpose
VALVE_PERF_HOMEOverride the state root, normally <repo>/.perf. Use a consistent location for related invocations.
VALVE_PERF_HOST_PORTS=1Connect through published host ports instead of Linux direct container IPs; portable execution only.
PERF_INTEGRATION=1Opt into harness integration tests using the dedicated Redis 7.4/Valkey 8 endpoints.
PERF_REDIS_URLSComma-separated integration endpoints. Model parity restricts URLs to the harness loopback ports 16479/16480.
VALVE_EVIDENCE_ARCHIVEPath to the external legacy evidence archive; alternatively use legacy --archive.

VALVE_PERF_ISOLATED is internal re-exec state, not a way to enable authority. The harness checks live cgroup controls. Repository CI variables PERF_SERVER_CPUS and PERF_WORKER_CPUS supply disjoint CPU lists to dedicated workflows.

Exit codes

CodeMeaning
0Command completed without a failing execution/safety/regression condition. Results can still be descriptive, inconclusive, or unverified.
1Safety violation, performance regression, failed execution, failed diagnostic check, or size-budget failure, as applicable.
2Invalid arguments or setup failure.

For c1, 0 specifically means verified overdue rejection without callback execution, 1 means a late callback, and 2 means inconclusive verification or setup failure. An unrelated rejection is not a deadline safety pass.

On this page