tools

Documentation

Overview

generate_report.go — Fills REPORT_TEMPLATE.md with data from a completed benchmark run and writes BENCHMARK_REPORT.md to the results directory.

Usage:

go run benchmarks/tools/generate_report.go \
  -dir=benchmarks/results/<timestamp>/ \
  -template=benchmarks/reports/REPORT_TEMPLATE.md \
  -version=<onix-version>

The generator reads:

• latency_report.csv — per-benchmark latency and allocation data
• throughput_report.csv — RPS and latency by GOMAXPROCS level
• benchstat_summary.txt — raw benchstat output block
• run1.txt — goos / goarch / cpu metadata

Placeholders filled in the template:

__TIMESTAMP__         results dir basename (YYYY-MM-DD_HH-MM-SS)
__ONIX_VERSION__      -version flag value
__GOOS__              from run1.txt header
__GOARCH__            from run1.txt header
__CPU__               from run1.txt header
__GOMAXPROCS__        derived from the benchmark name suffix in run1.txt
__P50_US__            p50 latency in µs (from Discover_Percentiles row)
__P95_US__            p95 latency in µs
__P99_US__            p99 latency in µs
__MEAN_DISCOVER_US__  mean latency in µs for discover
__MEAN_SELECT_US__    mean latency in µs for select
__MEAN_INIT_US__      mean latency in µs for init
__MEAN_CONFIRM_US__   mean latency in µs for confirm
__ALLOCS_DISCOVER__   allocs/req for discover
__ALLOCS_SELECT__     allocs/req for select
__ALLOCS_INIT__       allocs/req for init
__ALLOCS_CONFIRM__    allocs/req for confirm
__BYTES_DISCOVER__    bytes/req for discover
__BYTES_SELECT__      bytes/req for select
__BYTES_INIT__        bytes/req for init
__BYTES_CONFIRM__     bytes/req for confirm
__MEM_DISCOVER_KB__   bytes/req converted to KB for discover
__MEM_SELECT_KB__     bytes/req converted to KB for select
__MEM_INIT_KB__       bytes/req converted to KB for init
__MEM_CONFIRM_KB__    bytes/req converted to KB for confirm
__PEAK_RPS__          highest RPS across all GOMAXPROCS levels
__CACHE_WARM_US__     mean latency in µs for CacheWarm
__CACHE_COLD_US__     mean latency in µs for CacheCold
__CACHE_WARM_ALLOCS__ allocs/req for CacheWarm
__CACHE_COLD_ALLOCS__ allocs/req for CacheCold
__CACHE_WARM_BYTES__  bytes/req for CacheWarm
__CACHE_COLD_BYTES__  bytes/req for CacheCold
__CACHE_DELTA__       formatted warm-vs-cold delta string
__THROUGHPUT_TABLE__  generated markdown table from throughput_report.csv
__BENCHSTAT_SUMMARY__ raw contents of benchstat_summary.txt

parse_results.go — Parses raw go test -bench output from the benchmark results directory and produces two CSV files for analysis and reporting.

Usage:

go run benchmarks/tools/parse_results.go \
  -dir=benchmarks/results/<timestamp>/ \
  -out=benchmarks/results/<timestamp>/

Output files:

latency_report.csv    — per-benchmark mean, p50, p95, p99 latency, allocs
throughput_report.csv — RPS and mean latency at each GOMAXPROCS level from the parallel sweep