nfs/docs/BENCHMARKING.md

Benchmarking

How the nfs project is measured. Every number a document, a README or a changelog quotes comes from here and nowhere else.

The method

• Two levels are measured, and they answer different questions. The backend level benchmarks the internal/nfsfs filesystem layer on its own: what one READ, WRITE, GETATTR or LOOKUP costs against a local directory. The wire level benchmarks whole NFS sessions: the server binary and the client library over a loopback connection, which adds the RPC, XDR and session layers on top of the backend.
• What is deliberately left out: kernel NFS mounts, the network beyond loopback, and any comparison against other NFS servers. Those are interop questions, not benchmark questions.
• The machine is idle, named, and stays the same across comparable reports.
• The toolchain is named with its version and its build flags.
• Comparisons run inside one process, with the order of the two sides alternated where a comparison is the point. Differences under two percent are noise, not results.
• A change is measured against its baseline, not against a memory of how fast it used to be. The baseline run is part of the measurement, and both sides land in the same report.

Running

just bench

The recipe sweeps ./internal/... with -benchmem -count=5.

A first look at one target, before the full battery is worth the time:

go test -run '^$' -bench 'BenchmarkRead64K' -benchtime=1x ./internal/nfsfs

The full battery runs once, deliberately, on an idle machine. A benchmark command is capped at about two minutes per round; longer sweeps are split.

Reports

Reports live in docs/_results/, one file per measurement round, named YYYY-MM-DD-subject.md, and follow BENCHMARK_TEMPLATE.md. A report carries its numbers, its machine, its toolchain and the exact command. A number without its provenance is not a result, and a performance claim without a report behind it is left out of the documentation rather than softened into an adjective.