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 |
| 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| Damage capture and resize | `.` | `BenchmarkScreenCaptureDamage`, `BenchmarkScreenResizeReflowViewport` |
32| History build, views and storage | `.` | `BenchmarkHistoryBuild10Kx120`, `BenchmarkHistoryView10KRows*`, `BenchmarkHistoryRetained10Kx120`, see [storage-optimization.md](storage-optimization.md) |
33| ANSI renderer | `./ansi` | `BenchmarkRendererFullFrameDraw`, `BenchmarkRendererIncrementalOneCell`, `BenchmarkRendererFragmentedDamage`, `BenchmarkRendererBroadRegularDamage`, `BenchmarkRendererIncrementalNoBytePrepareCommit` |
34| HTML renderer | `./html` | `BenchmarkRenderer` (`snapshot-*` and `one-row-*` at 80x24, 120x40, 240x80) |
35
36`one-row-*` is the common interactive case: one changed line in a full frame.
37It must stay cheaper than `snapshot-*` at the same size.
38
39## Profiles
40
41Use a CPU or memory profile to find where the time or bytes go:
42
43```sh
44go test ./html -run '^$' -bench '^BenchmarkRenderer$/one-row-240x80' -benchmem \
45 -cpuprofile /tmp/cpu.out -memprofile /tmp/mem.out
46go tool pprof -top /tmp/cpu.out
47go tool pprof -sample_index=alloc_space -top /tmp/mem.out
48go tool pprof -http=:0 /tmp/cpu.out # flame graph in the browser
49```
50
51To see why a value escapes to the heap:
52
53```sh
54go build -gcflags=-m ./html 2>&1 | grep -v inlin
55```
56
57Tests can pin an allocation result with `testing.AllocsPerRun`; several
58packages already do, for example `TestCopyFromDoesNotAllocateOnceSized` in
59`core`.
60
61## Safety checks
62
63A faster change must produce the same output:
64
65```sh
66go test ./... # includes TestDifferentialOracle
67go test -race ./...
68go vet ./... && staticcheck ./...
69```
70
71`TestDifferentialOracle` digests the output of every layer (VT, history,
72graphics, ANSI, HTML) for seeded workloads. A performance change must leave
73`testdata/oracle/golden.txt` unchanged. The property tests in `ansi` and `html`
74compare reused-buffer renderers with clone-based references through random
75edits, aborts and resets.
76
77When a change reuses buffers, check:
78
79- Nothing returned to a caller still points into a reused buffer.
80- Retained scratch is bounded, so one huge frame does not pin memory.
81- Reused slices of strings or pointers are cleared, so they do not keep old
82 values alive.
83
84## Browser rendering
85
86For the HTML frontend, the browser's style, layout and paint usually cost more
87than the Go side. The Playwright performance gate in
88[`internal/htmlharness`](../internal/htmlharness/README.md) bounds sustained
89snapshot and row work in Chromium:
90
91```sh
92npx playwright test internal/htmlharness/performance.spec.js --project=chromium
93```
94
95Measure user-visible scrolling in the host application, with a real GPU and the
96user's zoom level: headless Chromium does not reproduce compositor costs.