docs(perf): Phase 2.11B deployment perf (path B)

[zzylol]

Summary

Phase 2.11B — deployment-level perf audit. Companion to Phase 2.11A
(Go-bench micro-results, PR #236, merged). Together they close
ADR-0002 §"Performance contract" with both micro and deployment-level
confirmation.

This doc reports what the existing docker-compose b3-delta harness
measures end-to-end, comparing commit 6b3258d (pre-shim) vs HEAD
c86a62c (post-shim, origin/main).

Methodology

• Stack: deploy/docker-compose/baseline-b3-delta.yml + agents-N1.yml.
• Workload: producer-paced, 1000 cardinality × 10 Hz, default SDK
  knobs (EXPORTER_FREQ_HZ=10, EXPORTER_SDK_WINDOW=15s).
• Per commit: built sketchcollector binary in a git worktree,
  packaged as asap/sketchcol:dev, recreated only the agent +
  gateway containers (producer / backend / Prometheus / MinIO stay
  continuously up — removes a source of cross-run drift).
• Soaked ≥ 200 s; took 2 samples ≥ 60 s apart; reported the mean.
• Pre-shim build at 6b3258d did not need PR build(sketchcollector): wire asap-precompute-go replace directive #231's local replace
  fix — that PR introduced asap-precompute-go which is precisely
  the dependency the shim added, so 6b3258d's go.mod has no reference
  to it. Only env-local fix was a /tmp/sketchlib-go symlink for
  the OCB-emitted relative path.

Results

Mean over 2 samples each:

Metric	Pre-shim	Post-shim	Δ%	Verdict
agent_cpu_cores	0.0025	0.0025	0.0%	pass
agent_rss_mib	291.1	302.6	+4.0%	pass
agent_in_kib_per_s	25.74	25.74	0.0%	pass
agent_out_kib_per_s	3.52	3.52	0.0%	pass
agent_points_per_s	133.3	133.3	0.0%	pass

Throughput / IO / CPU all within run-to-run noise. RSS moves +4%
which is well within tolerance (sketchlib-go DDSketch buffers and
OTel runtime are the dominant terms, ~ 10× larger).

Caveats

• Single host with shared tenants; not isolated to a cgroup.
• Producer-paced workload — agent runs at ~ 0.25% of one core, so
  CPU diffs are dominated by measurement noise. To detect a 10%
  shim regression at deployment level you'd need a saturating
  workload (e.g. 1e5 cardinality × 100 Hz).
• No cold-store / query traffic — backend_samples_per_s and
  backend_query_p99_ms NaN under ingest-only soak.

Gaps in the existing harness

Documented in the doc, not fixed:

1. Gateway metric-name skew — harness assumes v0.108, current is v0.141.
2. Backend /metrics empty under ingest-only.
3. No per-observation latency emitted from the deployed shim.
4. No direct sketch-payload-bytes counter.
5. run-baseline-sweep.sh still uses deprecated EXPORTER_RATE.
6. Producer-paced default doesn't stress the shim.

Test plan

• Pre-shim build succeeded (8 s OCB step after submodule init).
• Post-shim build was already present from a 4-h soak.
• Both commits exposed identical agent / gateway behaviour to the
  harness's queries (same NaN pattern on gateway/backend rows in both).
• Two samples per commit; means consistent with each other.
• If a future re-run wants to fill the saturation-stress cell,
  the doc has a reproduction recipe.

🤖 Generated with Claude Code