Performance evidence

Run benchmarks on the same idle machine, with the same Go toolchain and power settings. The scripts default to GOMAXPROCS=10, ten samples, one second per sample, and store raw results below the ignored .cache/perf directory.

GOEXPERIMENT=nojsonv2 scripts/perf/run_benchmarks.sh base
GOEXPERIMENT=nojsonv2 scripts/perf/run_benchmarks.sh head
scripts/perf/compare_benchmarks.sh .cache/perf/base.bench.txt .cache/perf/head.bench.txt
GOEXPERIMENT=nojsonv2 scripts/perf/measure_binaries.sh head

These commands select the release JSON runtime explicitly. Set GOEXPERIMENT= instead when measuring the Go 1.27 default JSON runtime.

Use run_json_benchmarks.sh to compare the WebSocket marshal/unmarshal hot paths without running unrelated benchmarks:

GOEXPERIMENT= scripts/perf/run_json_benchmarks.sh default-json
GOEXPERIMENT=nojsonv2 scripts/perf/run_json_benchmarks.sh nojsonv2
go tool benchstat .cache/perf/nojsonv2.bench.txt .cache/perf/default-json.bench.txt

If a result crosses a merge threshold without a statistically clear result, repeat both sides with BENCH_COUNT=20. Generate CPU and heap profiles for a single representative benchmark with:

GOEXPERIMENT=nojsonv2 scripts/perf/profile_benchmark.sh ./trace BenchmarkMTRAggregatorSnapshot64TTL4Paths profile-name

Record go version, go env GOEXPERIMENT, the exact commit IDs, machine, operating system, GOMAXPROCS, sample count, and any profiler or UPX version in the pull request. Keep raw profiles and binaries as CI artifacts rather than committing them.

measure_binaries.sh records stripped local-platform sizes. Set UPX_BIN to an exact UPX executable when that target format is supported; use the same binary and flags for both sides of a comparison. Set PERF_LDFLAGS when reproducing release-specific linker metadata such as Darwin's -macos=13.0.

On macOS, measure_help_startup.sh records ten no-warmup --help process launches and the maximum resident set size reported by /usr/bin/time -l:

scripts/perf/measure_help_startup.sh go127 \
  nexttrace /path/to/nexttrace \
  nexttrace-tiny /path/to/nexttrace-tiny \
  ntr /path/to/ntr

Default PGO evaluation

Generate a 30-second candidate profile from one deterministic composite workload with three equally timed phases. It covers the protocol decoders, fake-prober MTR aggregation with direct and cached fake Geo provider paths and JSON output, and WebSocket JSON encode/decode:

scripts/perf/generate_pgo_profile.sh candidate

Compare -pgo=off with the candidate using ten one-second samples. The workload files contain only the three equally weighted profile workloads; the guardrail files contain the individual critical paths:

scripts/perf/run_pgo_benchmarks.sh pgo-off off
scripts/perf/run_pgo_benchmarks.sh pgo-on .cache/perf/candidate.candidate.pgo
go tool benchstat .cache/perf/pgo-off.workload.bench.txt .cache/perf/pgo-on.workload.bench.txt
go tool benchstat .cache/perf/pgo-off.guardrail.bench.txt .cache/perf/pgo-on.guardrail.bench.txt

The scripts fix GOEXPERIMENT=nojsonv2, GOMAXPROCS=10, and seed 20260905 by default. If a threshold is crossed without statistical confidence, rerun both sides with BENCH_COUNT=20.

Set PERF_BINARY_DIR to keep the exact binaries built by measure_binaries.sh for startup and RSS comparison:

GOEXPERIMENT=nojsonv2 GOFLAGS=-pgo=off \
  PERF_BINARY_DIR=.cache/perf/pgo-off-bin scripts/perf/measure_binaries.sh pgo-off
GOEXPERIMENT=nojsonv2 GOFLAGS=-pgo=$PWD/.cache/perf/candidate.candidate.pgo \
  PERF_BINARY_DIR=.cache/perf/pgo-on-bin scripts/perf/measure_binaries.sh pgo-on