docs(perf): document coordinator benchmark metrics
- commit
- 70a176f25737662ce603c6b4a1b593f2aeb693a5
- author
- brice · · 2026-07-11 19:37 UTC
- committer
- brice · · 2026-07-11 19:38 UTC
- parent
- 6732890
- signature
- GPG Verified
CD88F9E564E0102646FB6077A1A07C7C7C3E349D· arch-gpg Verified for the committer email
1 file · +13 -10
M docs/performance.md +13 -10
| @@ -1,8 +1,8 @@ | |||
| 1 | 1 | # Performance methodology (M5) | |
| 2 | 2 | ||
| 3 | - | This baseline measures in-process daemon work only. It deliberately does **not** | |
| 4 | - | measure coordinator behavior, chunk encoding, compression, GC tuning, or real | |
| 5 | - | network latency. Output metrics count frames and encoded output data produced | |
| 3 | + | This baseline measures in-process daemon work only. It includes coordinator-enabled | |
| 4 | + | fixture scheduling metrics, but deliberately does **not** measure chunk | |
| 5 | + | encoding, compression, GC tuning, or real network latency. Output metrics count frames and encoded output data produced | |
| 6 | 6 | by the daemon; snapshot writes and serialized bytes are local snapshot-store | |
| 7 | 7 | proxies. These metrics approximate local rendering, IPC payload, and persistence | |
| 8 | 8 | work, not a Unix socket, SSH, or UDP transport. Real transport impairment and | |
| @@ -40,13 +40,17 @@ prefix and patterned text. The layouts are: | |||
| 40 | 40 | - 4 tabs x 4 panes | |
| 41 | 41 | - 8 tabs x 1 pane | |
| 42 | 42 | ||
| 43 | - | The fixture starts no PTY readers, schedulers, clocks, or transports. It primes | |
| 44 | - | the renderer shadow before timing; live paint then alternates fixed writes. The | |
| 45 | - | reported `outputframes/op` value counts output messages. `outputbytes/op` | |
| 43 | + | The fixture starts no PTY readers or transports. It primes the renderer shadow | |
| 44 | + | before timing; live paint then alternates fixed writes through the coordinator. | |
| 45 | + | The reported `outputframes/op` value counts output messages. `outputbytes/op` | |
| 46 | 46 | counts their encoded terminal data and excludes the 24-byte output header; | |
| 47 | 47 | `framepayloadbytes/op` counts the complete output payload including that header. | |
| 48 | 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. | |
| 49 | + | serialized bytes. `coordinatorinvalidations/op`, `coordinatorwakes/op`, and | |
| 50 | + | `coordinatorcoalesced/op` respectively count scheduling requests, delivered | |
| 51 | + | wakes, and requests coalesced into those wakes; `coordinatorcoalescingratio` | |
| 52 | + | is their coalesced-to-invalidation ratio. They must not be presented as network | |
| 53 | + | throughput or latency. | |
| 50 | 54 | ||
| 51 | 55 | Capture a pre-change result outside the repository, including Go and kernel | |
| 52 | 56 | context: | |
| @@ -82,9 +86,8 @@ wide row widths; `B/op` may grow by at most 2x, a conservative relative | |||
| 82 | 86 | allowance that catches full cell-row copies without depending on an absolute | |
| 83 | 87 | Go-version-specific budget. This scope does not yet include an | |
| 84 | 88 | incremental/full-text search index: queries still scan the immutable document | |
| 85 | - | and produce a fresh match list. Coordinator | |
| 86 | - | behavior, chunk encoding, compression, GC tuning, and real Unix-socket, SSH, or | |
| 87 | - | UDP impairment/latency remain out of scope. | |
| 89 | + | and produce a fresh match list. Chunk encoding, compression, GC tuning, and real Unix-socket, SSH, or UDP | |
| 90 | + | impairment/latency remain out of scope. | |
| 88 | 91 | ||
| 89 | 92 | ## Lower-level smoke baseline | |
| 90 | 93 | ||
| @@ -1,8 +1,8 @@ | |||||
| 1 | # Performance methodology (M5) | 1 | # Performance methodology (M5) | ||
| 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 includes coordinator-enabled |
| 4 | - | measure coordinator behavior, chunk encoding, compression, GC tuning, or real | 4 | + | fixture scheduling metrics, but deliberately does **not** measure chunk |
| 5 | - | network latency. Output metrics count frames and encoded output data produced | 5 | + | encoding, compression, GC tuning, or real network latency. Output metrics count frames and encoded output data produced |
| 6 | by the daemon; snapshot writes and serialized bytes are local snapshot-store | 6 | by the daemon; snapshot writes and serialized bytes are local snapshot-store | ||
| 7 | proxies. These metrics approximate local rendering, IPC payload, and persistence | 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 | 8 | work, not a Unix socket, SSH, or UDP transport. Real transport impairment and | ||
| @@ -40,13 +40,17 @@ prefix and patterned text. The layouts are: | |||||
| 40 | - 4 tabs x 4 panes | 40 | - 4 tabs x 4 panes | ||
| 41 | - 8 tabs x 1 pane | 41 | - 8 tabs x 1 pane | ||
| 42 | 42 | ||||
| 43 | - | The fixture starts no PTY readers, schedulers, clocks, or transports. It primes | 43 | + | The fixture starts no PTY readers or transports. It primes the renderer shadow |
| 44 | - | the renderer shadow before timing; live paint then alternates fixed writes. The | 44 | + | before timing; live paint then alternates fixed writes through the coordinator. |
| 45 | - | reported `outputframes/op` value counts output messages. `outputbytes/op` | 45 | + | The reported `outputframes/op` value counts output messages. `outputbytes/op` |
| 46 | counts their encoded terminal data and excludes the 24-byte output header; | 46 | counts their encoded terminal data and excludes the 24-byte output header; | ||
| 47 | `framepayloadbytes/op` counts the complete output payload including that header. | 47 | `framepayloadbytes/op` counts the complete output payload including that header. | ||
| 48 | `snapshotwrites/op` and `snapshotbytes/op` are local snapshot-store writes and | 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. | 49 | + | serialized bytes. `coordinatorinvalidations/op`, `coordinatorwakes/op`, and |
| 50 | + | `coordinatorcoalesced/op` respectively count scheduling requests, delivered | |||
| 51 | + | wakes, and requests coalesced into those wakes; `coordinatorcoalescingratio` | |||
| 52 | + | is their coalesced-to-invalidation ratio. They must not be presented as network | |||
| 53 | + | throughput or latency. | |||
| 50 | 54 | ||||
| 51 | Capture a pre-change result outside the repository, including Go and kernel | 55 | Capture a pre-change result outside the repository, including Go and kernel | ||
| 52 | context: | 56 | context: | ||
| @@ -82,9 +86,8 @@ wide row widths; `B/op` may grow by at most 2x, a conservative relative | |||||
| 82 | allowance that catches full cell-row copies without depending on an absolute | 86 | allowance that catches full cell-row copies without depending on an absolute | ||
| 83 | Go-version-specific budget. This scope does not yet include an | 87 | Go-version-specific budget. This scope does not yet include an | ||
| 84 | incremental/full-text search index: queries still scan the immutable document | 88 | incremental/full-text search index: queries still scan the immutable document | ||
| 85 | - | and produce a fresh match list. Coordinator | 89 | + | and produce a fresh match list. Chunk encoding, compression, GC tuning, and real Unix-socket, SSH, or UDP |
| 86 | - | behavior, chunk encoding, compression, GC tuning, and real Unix-socket, SSH, or | 90 | + | impairment/latency remain out of scope. |
| 87 | - | UDP impairment/latency remain out of scope. | |||
| 88 | 91 | ||||
| 89 | ## Lower-level smoke baseline | 92 | ## Lower-level smoke baseline | ||
| 90 | 93 | ||||