Performance measurement

S5a transport observability

S5a is measurement-only. It records process-local runtime marks and harness-owned end-to-end boundaries without changing rendering, pacing, transport policy, wire bytes, or ProtocolVersion. The canonical matrix and workload/topology/ transport coverage are in testdata/perf/manifest.json: 1x4, 4x1, 4x4, and 8x1, all at 120x40 with 10,000 rows per pane; idle, active/all/inactive output, interactive flood, copy search, resize sweep, snapshot/output/resize, and attach/restore/tab switch; local, SSH stdio, UDP baseline, UDP 25/100 ms, and UDP 0%/1% loss. It has 252 scenarios (4×9×7), with inapplicable cases required to be explicit. The seven transport entries are local, ssh_stdio, udp_baseline, udp_loss_0pct, udp_25ms, udp_100ms, and udp_loss_1pct.

Trace schema and clock domains

Every process JSONL record has exactly these fields: schema (uint), process_id (string), component (string), scenario (string), run, sequence, request_id, epoch (uint), kind (string), tick (int64), bytes, fragments, retransmits, pending (uint), ack_rtt_nanos (int64), and valid (bool). Schema 1 is represented by:

{"schema":1,"process_id":"p","component":"daemon","scenario":"s","run":1,"sequence":1,"request_id":1,"epoch":1,"kind":"diff_start","tick":0,"bytes":0,"fragments":0,"retransmits":0,"pending":0,"ack_rtt_nanos":0,"valid":true}

tick is stamped only by the concrete JSONL observer using its process-local injected monotonic clock; producers supply no timestamp. The harness sets VEV_PERF_TRACE, VEV_PERF_PROCESS_ID, VEV_PERF_SCENARIO, and VEV_PERF_RUN for every launched role, identifying its exclusive trace path and process/scenario/run mapping. Components in one OS process share that observer. The harness clock is a separate monotonic domain and is the sole clock for input-injection → terminal-bytes-successfully-flushed end-to-end samples. Cross-process ticks are never ordered or subtracted; records correlate only by scenario/run/sequence/request/epoch IDs.

The named process-local spans are capture, compose, diff, queue wait, ACK-blocked interval, emit, adapter send, and adapter receive. Their start/end marks are paired within one process and summarized by component/adapter with raw records, counts, p50/p95/p99, and max. Diagnostic fields (bytes, fragments, retransmits, pending, ACK RTT) remain separate from duration calculations.

Baseline procedure and validity

Use the public CLI harness (not internal packages):

go build -o /tmp/vev-perf ./
rm -rf testdata/perf/results
go run ./cmd/vev-perf-harness --vev-bin /tmp/vev-perf \
  --manifest testdata/perf/manifest.json --out testdata/perf/results \
  --warmup 10s --duration 30s --repetitions 10

The minimums are 30 seconds measured and 10 independent repetitions; warmup is excluded. During the measured interval the harness injects at most one event per second. At least 10 complete event pairs are required: both injection and successful terminal flush must fall inside the measured interval; straddling or failed events are retained only as raw diagnostics and are not samples. Each run must contain manifest.json, raw-harness.jsonl, per-process JSONL, runs.json, and summary.json. Reject results with missing input/flush boundaries, unmatched IDs, bad correlation, nonmonotonic same-process sequence, negative same-domain spans, fewer than 10 complete in-interval event pairs, invalid denominators, any cross-process tick arithmetic, or unmet duration/repetition minima. Raw JSONL and run manifests are the evidence files; no result authorizes a policy or optimization change.

Existing in-process smoke checks

These commands measure local daemon work only and are not end-to-end transport results:

go test ./internal/usecase/daemon -run '^$' -bench '^BenchmarkDaemonHistory' -benchtime=1x -benchmem
go test ./pkg/renderer ./pkg/vt ./internal/adapters/ipc -run '^$' -bench=. -benchmem
go test ./internal/usecase/daemon -run '^$' -bench '^BenchmarkComposeFloatingFrameCached$' -benchmem

source

1# Performance measurement
2
3## S5a transport observability
4
5S5a is measurement-only. It records process-local runtime marks and harness-owned
6end-to-end boundaries without changing rendering, pacing, transport policy, wire
7bytes, or `ProtocolVersion`. The canonical matrix and workload/topology/
8transport coverage are in [`testdata/perf/manifest.json`](../testdata/perf/manifest.json):
9`1x4`, `4x1`, `4x4`, and `8x1`, all at `120x40` with 10,000 rows per pane;
10idle, active/all/inactive output, interactive flood, copy search, resize sweep,
11snapshot/output/resize, and attach/restore/tab switch; local, SSH stdio, UDP
12baseline, UDP 25/100 ms, and UDP 0%/1% loss. It has 252 scenarios (4×9×7),
13with inapplicable cases required to be explicit. The seven transport entries are
14`local`, `ssh_stdio`, `udp_baseline`, `udp_loss_0pct`, `udp_25ms`, `udp_100ms`,
15and `udp_loss_1pct`.
16
17### Trace schema and clock domains
18
19Every process JSONL record has exactly these fields:
20`schema` (uint), `process_id` (string), `component` (string), `scenario`
21(string), `run`, `sequence`, `request_id`, `epoch` (uint), `kind` (string),
22`tick` (int64), `bytes`, `fragments`, `retransmits`, `pending` (uint),
23`ack_rtt_nanos` (int64), and `valid` (bool). Schema 1 is represented by:
24
25```json
26{"schema":1,"process_id":"p","component":"daemon","scenario":"s","run":1,"sequence":1,"request_id":1,"epoch":1,"kind":"diff_start","tick":0,"bytes":0,"fragments":0,"retransmits":0,"pending":0,"ack_rtt_nanos":0,"valid":true}
27```
28
29`tick` is stamped only by the concrete JSONL observer using its process-local
30injected monotonic clock; producers supply no timestamp. The harness sets `VEV_PERF_TRACE`,
31`VEV_PERF_PROCESS_ID`, `VEV_PERF_SCENARIO`, and `VEV_PERF_RUN` for every
32launched role, identifying its exclusive trace path and process/scenario/run
33mapping. Components in one OS
34process share that observer. The harness clock is a separate monotonic domain
35and is the sole clock for input-injection → terminal-bytes-successfully-flushed
36end-to-end samples. Cross-process ticks are never ordered or subtracted;
37records correlate only by scenario/run/sequence/request/epoch IDs.
38
39The named process-local spans are capture, compose, diff, queue wait,
40ACK-blocked interval, emit, adapter send, and adapter receive. Their start/end
41marks are paired within one process and summarized by component/adapter with
42raw records, counts, p50/p95/p99, and max. Diagnostic fields (bytes, fragments,
43retransmits, pending, ACK RTT) remain separate from duration calculations.
44
45### Baseline procedure and validity
46
47Use the public CLI harness (not internal packages):
48
49```sh
50go build -o /tmp/vev-perf ./
51rm -rf testdata/perf/results
52go run ./cmd/vev-perf-harness --vev-bin /tmp/vev-perf \
53  --manifest testdata/perf/manifest.json --out testdata/perf/results \
54  --warmup 10s --duration 30s --repetitions 10
55```
56
57The minimums are 30 seconds measured and 10 independent repetitions; warmup is
58excluded. During the measured interval the harness injects at most one event per
59second. At least 10 complete event pairs are required: both injection and
60successful terminal flush must fall inside the measured interval; straddling or
61failed events are retained only as raw diagnostics and are not samples. Each run must contain `manifest.json`, `raw-harness.jsonl`, per-process
62JSONL, `runs.json`, and `summary.json`. Reject results with missing input/flush
63boundaries, unmatched IDs, bad correlation, nonmonotonic same-process sequence,
64negative same-domain spans, fewer than 10 complete in-interval event pairs,
65invalid denominators,
66any cross-process tick arithmetic, or unmet duration/repetition minima. Raw
67JSONL and run manifests are the evidence files; no result authorizes a policy
68or optimization change.
69
70## Existing in-process smoke checks
71
72These commands measure local daemon work only and are not end-to-end transport
73results:
74
75```sh
76go test ./internal/usecase/daemon -run '^$' -bench '^BenchmarkDaemonHistory' -benchtime=1x -benchmem
77go test ./pkg/renderer ./pkg/vt ./internal/adapters/ipc -run '^$' -bench=. -benchmem
78go test ./internal/usecase/daemon -run '^$' -bench '^BenchmarkComposeFloatingFrameCached$' -benchmem
79```