docs(perf): clarify benchmark metric scope

commit: 284533ac3e6f83cb998eb490b7206d8c0985c861
author: brice · 3mo ago · 2026-07-11 08:40 UTC
parent: 640b699
signature: GPG VerifiedCD88F9E564E0102646FB6077A1A07C7C7C3E349D · arch-gpg Verified for the committer email

1 file · +12 -9

M docs/performance.md +12 -9


@@ -2,10 +2,11 @@
2	2
3	3		This baseline measures in-process daemon work only. It deliberately does not
4	4		measure coordinator behavior, chunk encoding, compression, GC tuning, or real
5		-	network latency. Output and snapshot metrics count encoded output bytes and
6		-	frames produced by the daemon; they are useful proxies for local rendering and
7		-	IPC payload work, not measurements of a Unix socket, SSH, or UDP transport.
8		-	Real Unix-socket, SSH, and UDP impairment/latency benchmarks are deferred.
	5	+	network latency. Output metrics count frames and encoded output data produced
	6	+	by the daemon; snapshot writes and serialized bytes are local snapshot-store
	7	+	proxies. These metrics approximate local rendering, IPC payload, and persistence
	8	+	work, not a Unix socket, SSH, or UDP transport. Real transport impairment and
	9	+	latency benchmarks are deferred.
9	10
10	11		## Large-history daemon baseline
11	12

@@ -41,10 +42,11 @@ prefix and patterned text. The layouts are:
41	42
42	43		The fixture starts no PTY readers, schedulers, clocks, or transports. It primes
43	44		the renderer shadow before timing; live paint then alternates fixed writes. The
44		-	reported `outputbytes/op`, `framepayloadbytes/op`, and `outputframes/op` values
45		-	are encoded in-process output proxies. `snapshotbytes/op` is the serialized
46		-	in-process snapshot size. They must not be presented as network throughput or
47		-	latency.
	45	+	reported `outputframes/op` value counts output messages. `outputbytes/op`
	46	+	counts their encoded terminal data and excludes the 24-byte output header;
	47	+	`framepayloadbytes/op` counts the complete output payload including that header.
	48	+	`snapshotwrites/op` and `snapshotbytes/op` are local snapshot-store writes and
	49	+	serialized bytes. They must not be presented as network throughput or latency.
48	50
49	51		Capture a pre-change result outside the repository, including Go and kernel
50	52		context:

@@ -90,7 +92,8 @@ Use this command to check renderer, VT, IPC, and daemon microbenchmarks without
90	92		claiming an end-to-end transport result:
91	93
92	94		```sh
93		-	go test ./pkg/renderer ./pkg/vt ./internal/adapters/ipc ./internal/usecase/daemon -run '^$' -bench=. -benchmem
	95	+	go test ./pkg/renderer ./pkg/vt ./internal/adapters/ipc -run '^$' -bench=. -benchmem
	96	+	go test ./internal/usecase/daemon -run '^$' -bench '^BenchmarkComposeFloatingFrameCached$' -benchmem
94	97		```
95	98
96	99		Enable daemon pprof explicitly when collecting a daemon profile:


@@ -2,10 +2,11 @@
2			2
3		This baseline measures in-process daemon work only. It deliberately does not	3		This baseline measures in-process daemon work only. It deliberately does not
4		measure coordinator behavior, chunk encoding, compression, GC tuning, or real	4		measure coordinator behavior, chunk encoding, compression, GC tuning, or real
5	-	network latency. Output and snapshot metrics count encoded output bytes and	5	+	network latency. Output metrics count frames and encoded output data produced
6	-	frames produced by the daemon; they are useful proxies for local rendering and	6	+	by the daemon; snapshot writes and serialized bytes are local snapshot-store
7	-	IPC payload work, not measurements of a Unix socket, SSH, or UDP transport.	7	+	proxies. These metrics approximate local rendering, IPC payload, and persistence
8	-	Real Unix-socket, SSH, and UDP impairment/latency benchmarks are deferred.	8	+	work, not a Unix socket, SSH, or UDP transport. Real transport impairment and
			9	+	latency benchmarks are deferred.
9			10
10		## Large-history daemon baseline	11		## Large-history daemon baseline
11			12

@@ -41,10 +42,11 @@ prefix and patterned text. The layouts are:
41			42
42		The fixture starts no PTY readers, schedulers, clocks, or transports. It primes	43		The fixture starts no PTY readers, schedulers, clocks, or transports. It primes
43		the renderer shadow before timing; live paint then alternates fixed writes. The	44		the renderer shadow before timing; live paint then alternates fixed writes. The
44	-	reported `outputbytes/op`, `framepayloadbytes/op`, and `outputframes/op` values	45	+	reported `outputframes/op` value counts output messages. `outputbytes/op`
45	-	are encoded in-process output proxies. `snapshotbytes/op` is the serialized	46	+	counts their encoded terminal data and excludes the 24-byte output header;
46	-	in-process snapshot size. They must not be presented as network throughput or	47	+	`framepayloadbytes/op` counts the complete output payload including that header.
47	-	latency.	48	+	`snapshotwrites/op` and `snapshotbytes/op` are local snapshot-store writes and
			49	+	serialized bytes. They must not be presented as network throughput or latency.
48			50
49		Capture a pre-change result outside the repository, including Go and kernel	51		Capture a pre-change result outside the repository, including Go and kernel
50		context:	52		context:

@@ -90,7 +92,8 @@ Use this command to check renderer, VT, IPC, and daemon microbenchmarks without
90		claiming an end-to-end transport result:	92		claiming an end-to-end transport result:
91			93
92		```sh	94		```sh
93	-	go test ./pkg/renderer ./pkg/vt ./internal/adapters/ipc ./internal/usecase/daemon -run '^$' -bench=. -benchmem	95	+	go test ./pkg/renderer ./pkg/vt ./internal/adapters/ipc -run '^$' -bench=. -benchmem
			96	+	go test ./internal/usecase/daemon -run '^$' -bench '^BenchmarkComposeFloatingFrameCached$' -benchmem
94		```	97		```
95			98
96		Enable daemon pprof explicitly when collecting a daemon profile:	99		Enable daemon pprof explicitly when collecting a daemon profile: