GETTING STARTED
A better benchmark,
one command at a time.
perfratio is a Rust command-line benchmarking tool descended from joulex and hyperfine. Compare arbitrary shell commands with timing, peak memory, optional energy telemetry and statistical analysis.
Install from source
Install Rust 1.88 or newer with rustup ↗, then build the current source with Cargo:
cargo install --git https://github.com/UnitedOpen-Source/perfratio --locked perfratioThe executable is installed into Cargo’s binary directory. Make sure that directory is on your PATH.
perfratio --helpPrebuilt artifacts, when available, are listed on the release page ↗. Package-manager commands for hyperfine install hyperfine; use perfratio’s own source or releases to get perfratio.
Run your first comparison
perfratio --warmup 3 'sleep 0.1' 'sleep 0.2'Quote each command separately. Warmup runs execute before measurements. By default, perfratio performs at least 10 measurement runs and measures for at least 3 seconds.
perfratio --runs 20 './baseline' './optimized'Reduce environmental noise
perfratio --check-system --schedule round-robin --warmup 3 './baseline' './optimized'System checks report supported environmental diagnostics. Round-robin scheduling interleaves commands to distribute slow drift more fairly. Keep workloads, inputs and hardware conditions comparable.
Commands execute on your machine. Use commands and parameter values you trust; parameter substitution is verbatim, not shell-escaped. For very short commands, --shell=none avoids shell startup calibration noise and shell syntax.
Read the output
- Time (mean ± σ): average elapsed time and standard deviation across runs.
- User / System: CPU time spent in application code and in the kernel.
- Peak memory: process peak resident memory, distinct from total allocations.
- Relative speed: timing ratios between compared commands, with uncertainty.
A ratio alone does not prove statistical significance. Look at variability, workload conditions and distributions.
perfratio --deep-stats './baseline' './optimized'Deep statistics add bootstrapped 95% confidence intervals for mean and median, and two-sample hypothesis testing against reference commands with deterministic bootstrap resampling.
Full output reference ↗Measure energy and power
perfratio --energy './benchmark'Energy measurement requires supported, accessible hardware sensors. Linux RAPL reads counters from the powercap interface. Availability and permissions depend on the machine.
Energy is reported in Joules and average active power in Watts. Measurements cover the hardware domains exposed by the sensors; they are not an isolated measurement of only your process. Background work can influence the result.
Export and share results
perfratio --export results.json --export report.html './benchmark'The file extension selects the export format. Use JSON for per-run analysis, CSV for tabular workflows, Markdown for documentation or HTML for a standalone report.
Compare a saved baseline
perfratio --export baseline.json './benchmark'perfratio --compare baseline.json './benchmark'Run the same workload after your change, keeping inputs and environment consistent. Read CLI help for additional comparison options.