How to measure CPU time and allocations before and after a change, and how to
check that the change kept behavior.
Workflow
- Pick the benchmark that covers the code you change (table below).
- Record a baseline on the base branch.
- Make the change, then record the same benchmark again.
- Compare with
benchstat; keep only wins that are stable across runs.
- Run the safety checks below before you commit.
# Baseline, from a worktree of the base branch
go test ./html -run '^$' -bench '^BenchmarkRenderer$' -benchmem -count=10 > /tmp/old.txt
# After the change
go test ./html -run '^$' -bench '^BenchmarkRenderer$' -benchmem -count=10 > /tmp/new.txt
benchstat /tmp/old.txt /tmp/new.txt
benchstat comes from go install golang.org/x/perf/cmd/benchstat@latest. Use
-count=10 so it can report variation; a ~ in its output means no
significant change.
Benchmarks
| Area |
Package |
Benchmarks |
| VT parsing and screen writes |
. |
BenchmarkScreenPrintableASCII, BenchmarkScreenMixedUTF8, BenchmarkScreenCSIHeavy, BenchmarkScreenShellRedrawBurst, BenchmarkScreenFullscreenScrollRegion, BenchmarkScreenKittyAPC |
| Output flood into full history |
. |
BenchmarkScreenScrollbackFlood (history limit 0, 10k and 50k rows) |
| Damage capture and resize |
. |
BenchmarkScreenCaptureDamage, BenchmarkScreenResizeReflowViewport |
| History build, views and storage |
. |
BenchmarkHistoryBuild10Kx120, BenchmarkHistoryView10KRows*, BenchmarkHistoryRetained10Kx120, see storage-optimization.md |
| ANSI renderer |
./ansi |
BenchmarkRendererFullFrameDraw, BenchmarkRendererIncrementalOneCell, BenchmarkRendererFragmentedDamage, BenchmarkRendererBroadRegularDamage, BenchmarkRendererIncrementalNoBytePrepareCommit |
| HTML renderer |
./html |
BenchmarkRenderer (snapshot-* and one-row-* at 80x24, 120x40, 240x80) |
one-row-* is the common interactive case: one changed line in a full frame.
It must stay cheaper than snapshot-* at the same size.
Profiles
Use a CPU or memory profile to find where the time or bytes go:
go test ./html -run '^$' -bench '^BenchmarkRenderer$/one-row-240x80' -benchmem \
-cpuprofile /tmp/cpu.out -memprofile /tmp/mem.out
go tool pprof -top /tmp/cpu.out
go tool pprof -sample_index=alloc_space -top /tmp/mem.out
go tool pprof -http=:0 /tmp/cpu.out # flame graph in the browser
To see why a value escapes to the heap:
go build -gcflags=-m ./html 2>&1 | grep -v inlin
Tests can pin an allocation result with testing.AllocsPerRun; several
packages already do, for example TestCopyFromDoesNotAllocateOnceSized in
core.
Safety checks
A faster change must produce the same output:
go test ./... # includes TestDifferentialOracle
go test -race ./...
go vet ./... && staticcheck ./...
TestDifferentialOracle digests the output of every layer (VT, history,
graphics, ANSI, HTML) for seeded workloads. A performance change must leave
testdata/oracle/golden.txt unchanged. The property tests in ansi and html
compare reused-buffer renderers with clone-based references through random
edits, aborts and resets.
When a change reuses buffers, check:
- Nothing returned to a caller still points into a reused buffer.
- Retained scratch is bounded, so one huge frame does not pin memory.
- Reused slices of strings or pointers are cleared, so they do not keep old
values alive.
Browser rendering
For the HTML frontend, the browser's style, layout and paint usually cost more
than the Go side. The Playwright performance gate in
internal/htmlharness bounds sustained
snapshot and row work in Chromium:
npx playwright test internal/htmlharness/performance.spec.js --project=chromium
Measure user-visible scrolling in the host application, with a real GPU and the
user's zoom level: headless Chromium does not reproduce compositor costs.
source
1# Performance work
2
3How to measure CPU time and allocations before and after a change, and how to
4check that the change kept behavior.
5
6## Workflow
7
81. Pick the benchmark that covers the code you change (table below).
92. Record a baseline on the base branch.
103. Make the change, then record the same benchmark again.
114. Compare with `benchstat`; keep only wins that are stable across runs.
125. Run the safety checks below before you commit.
13
14```sh
15# Baseline, from a worktree of the base branch
16go test ./html -run '^$' -bench '^BenchmarkRenderer$' -benchmem -count=10 > /tmp/old.txt
17# After the change
18go test ./html -run '^$' -bench '^BenchmarkRenderer$' -benchmem -count=10 > /tmp/new.txt
19benchstat /tmp/old.txt /tmp/new.txt
20```
21
22`benchstat` comes from `go install golang.org/x/perf/cmd/benchstat@latest`. Use
23`-count=10` so it can report variation; a `~` in its output means no
24significant change.
25
26## Benchmarks
27
28| Area | Package | Benchmarks |
29|---|---|---|
30| VT parsing and screen writes | `.` | `BenchmarkScreenPrintableASCII`, `BenchmarkScreenMixedUTF8`, `BenchmarkScreenCSIHeavy`, `BenchmarkScreenShellRedrawBurst`, `BenchmarkScreenFullscreenScrollRegion`, `BenchmarkScreenKittyAPC` |
31| Output flood into full history | `.` | `BenchmarkScreenScrollbackFlood` (history limit 0, 10k and 50k rows) |
32| Damage capture and resize | `.` | `BenchmarkScreenCaptureDamage`, `BenchmarkScreenResizeReflowViewport` |
33| History build, views and storage | `.` | `BenchmarkHistoryBuild10Kx120`, `BenchmarkHistoryView10KRows*`, `BenchmarkHistoryRetained10Kx120`, see [storage-optimization.md](storage-optimization.md) |
34| ANSI renderer | `./ansi` | `BenchmarkRendererFullFrameDraw`, `BenchmarkRendererIncrementalOneCell`, `BenchmarkRendererFragmentedDamage`, `BenchmarkRendererBroadRegularDamage`, `BenchmarkRendererIncrementalNoBytePrepareCommit` |
35| HTML renderer | `./html` | `BenchmarkRenderer` (`snapshot-*` and `one-row-*` at 80x24, 120x40, 240x80) |
36
37`one-row-*` is the common interactive case: one changed line in a full frame.
38It must stay cheaper than `snapshot-*` at the same size.
39
40## Profiles
41
42Use a CPU or memory profile to find where the time or bytes go:
43
44```sh
45go test ./html -run '^$' -bench '^BenchmarkRenderer$/one-row-240x80' -benchmem \
46 -cpuprofile /tmp/cpu.out -memprofile /tmp/mem.out
47go tool pprof -top /tmp/cpu.out
48go tool pprof -sample_index=alloc_space -top /tmp/mem.out
49go tool pprof -http=:0 /tmp/cpu.out # flame graph in the browser
50```
51
52To see why a value escapes to the heap:
53
54```sh
55go build -gcflags=-m ./html 2>&1 | grep -v inlin
56```
57
58Tests can pin an allocation result with `testing.AllocsPerRun`; several
59packages already do, for example `TestCopyFromDoesNotAllocateOnceSized` in
60`core`.
61
62## Safety checks
63
64A faster change must produce the same output:
65
66```sh
67go test ./... # includes TestDifferentialOracle
68go test -race ./...
69go vet ./... && staticcheck ./...
70```
71
72`TestDifferentialOracle` digests the output of every layer (VT, history,
73graphics, ANSI, HTML) for seeded workloads. A performance change must leave
74`testdata/oracle/golden.txt` unchanged. The property tests in `ansi` and `html`
75compare reused-buffer renderers with clone-based references through random
76edits, aborts and resets.
77
78When a change reuses buffers, check:
79
80- Nothing returned to a caller still points into a reused buffer.
81- Retained scratch is bounded, so one huge frame does not pin memory.
82- Reused slices of strings or pointers are cleared, so they do not keep old
83 values alive.
84
85## Browser rendering
86
87For the HTML frontend, the browser's style, layout and paint usually cost more
88than the Go side. The Playwright performance gate in
89[`internal/htmlharness`](../internal/htmlharness/README.md) bounds sustained
90snapshot and row work in Chromium:
91
92```sh
93npx playwright test internal/htmlharness/performance.spec.js --project=chromium
94```
95
96Measure user-visible scrolling in the host application, with a real GPU and the
97user's zoom level: headless Chromium does not reproduce compositor costs.