Decision record · ADR
ADR-0031: Bridge AIPerf warmup and profiling with a release-owned phase barrier
Status: accepted | Date: 2026-08-02
References: RFC-0004:C-WORKLOAD-PROFILING, RFC-0004:C-MEASUREMENTS, RFC-0004:C-INFERLAB-TOOLCHAIN, ADR-0003, ADR-0026, ADR-0035, RFC-0004:C-BENCH-AGENTIC-TRACE-REPLAY
Context
Section titled “Context”A profiled serving-Bench case opens its framework range only after native warmup has drained, while preserving one AIPerf process, population, scheduler, transport pipeline, and metric pipeline. AIPerf exposes no external acknowledged phase barrier, so log observation races the first profiling request and splitting warmup from profiling changes the measured workflow.
The initial implementation and qualification used AIPerf 0.11.0. Its timing-strategy protocol calls setup_phase() before profiling credit issuance, and its plugin registry permits a release-owned package to replace the registered request_rate strategy while delegating the native implementation. ADR-0003 otherwise rejects private AIPerf imports, making this a deliberately bounded exception for capture coordination rather than a general runner integration pattern.
The measurement toolchain now pins AIPerf 0.12.0. Requalification established that the same setup and registry boundary remains available. Ordinary request and linear-session cases still use request_rate, while the qualified AgentX scenario uses a distinct agentic_replay strategy whose native instance owns trajectory continuation, branch scheduling, and warmup-to-profiling handoff. Captured AgentX replay therefore needs the same acknowledged gate around a different native delegate; routing it through request_rate or reconstructing its state would violate ADR-0035.
Decision
Section titled “Decision”Use a release-owned, exact-version phase-barrier shim as a bounded refinement of ADR-0003’s CLI-only AIPerf boundary. For the pinned AIPerf 0.12.0 toolchain, the shim replaces only the registered request_rate and agentic_replay timing strategies when Rust supplies a capture barrier, and delegates each strategy’s scheduling, arrivals, session or trajectory continuation, branch behavior, credit issuance, and metrics to its native AIPerf implementation.
The warmup wrapper retains the native phase progress needed to classify whether its terminal outcome permits profiling release. The profiling wrapper uses setup_phase() to report that warmup has drained and waits for acknowledgement from a runtime-local Rust control channel. Rust opens every planned capture target before acknowledging release. The AgentX wrapper also forwards the native strategy properties and methods required for pending branch handoff; it does not interpret or reconstruct the session tree.
The wrapper fails closed on any AIPerf version other than the qualified pin, missing registry replacement, invalid warmup outcome, failed capture start, lost acknowledgement, or client exit. Uncaptured runs continue through the native CLI without registry replacement. Post-run artifacts remain authoritative for recorded outcomes, and capture close remains at the existing client-completion boundary.
This direction prevails because it adds only the acknowledged setup gate that the pinned CLI lacks while preserving native one-run semantics and Rust capture authority. The version-sensitive imports remain contained in the release-owned Bench package and require requalification whenever the AIPerf pin or either delegated strategy contract changes.
Consequences
Section titled “Consequences”Positive: warmup traffic remains outside capture without splitting a native case, repeating population preparation, resetting cache state, or reproducing request-rate or AgentX scheduling. Rust retains acknowledged multi-target capture authority, while AIPerf retains all measurement and replay semantics.
Negative: the shim depends on exact AIPerf 0.12 plugin-registry, phase-progress, request_rate, and agentic_replay object contracts that are not a general stable Python API. Exact version checks, focused boundary tests, and real capture requalification are therefore required mitigations; an AIPerf upgrade cannot be treated as a dependency-only change.
Neutral: the AIPerf distribution remains unmodified, ordinary uncaptured Bench execution remains CLI/config/artifact based, result normalization and capture close are unchanged, and framework integrations gain no AIPerf-specific behavior. This decision does not authorize arbitrary AIPerf imports, custom scheduling, or public plugin controls.
Alternatives Considered
Section titled “Alternatives Considered”Install a release-owned, version-pinned phase-barrier shim that delegates native request-rate and agentic-replay scheduling (accepted)
Section titled “Install a release-owned, version-pinned phase-barrier shim that delegates native request-rate and agentic-replay scheduling (accepted)”- Pros: Uses the documented strategy setup boundary before the first profiling credit, Preserves one native AIPerf run, shared population, scheduler, transport, and metric pipeline, Keeps capture control and authoritative evidence in Rust
- Cons: Introduces a narrow dependency on pinned AIPerf phase progress plus request_rate and agentic_replay strategy internals, Requires registry replacement and cross-process barrier behavior to be requalified whenever the AIPerf pin changes
Run warmup and profiling as separate AIPerf invocations (rejected)
Section titled “Run warmup and profiling as separate AIPerf invocations (rejected)”- Pros: Needs no AIPerf extension point, Lets Rust place the capture window around the second process
- Cons: Recreates the native client, sampler, and phase state between warmup and profiling, Cannot preserve the governed one-run and one-reset semantics
- Rejected because: The apparent simplicity changes the measured workflow rather than observing its native profiling phase.
Observe AIPerf logs, artifacts, or asynchronous phase messages from Rust (rejected)
Section titled “Observe AIPerf logs, artifacts, or asynchronous phase messages from Rust (rejected)”- Pros: Avoids importing AIPerf implementation objects into the release-owned shim
- Cons: Provides notification but no acknowledged gate before the first profiling credit, Parsing logs or partially written artifacts creates a second phase-state interpretation
- Rejected because: An observational signal cannot prove every capture target opened before profiling traffic began.
Patch or vendor the installed AIPerf distribution (rejected)
Section titled “Patch or vendor the installed AIPerf distribution (rejected)”- Pros: Can add a direct native phase callback at any internal location
- Cons: Turns the pinned AIPerf distribution into an unpublished fork, Obscures package provenance and expands the maintained source surface
- Rejected because: A release-owned extension at an existing registry boundary is smaller and auditable without modifying the third-party distribution.
Defer warmup-excluding capture until a later AIPerf release (rejected)
Section titled “Defer warmup-excluding capture until a later AIPerf release (rejected)”- Pros: Can adopt an upstream profiler lifecycle hook once the AIPerf pin changes
- Cons: Leaves profiling traces on the current pinned toolchain polluted by warmup, Couples a contained capture fix to a broader measurement-engine upgrade and requalification
- Rejected because: The pinned toolchain already exposes a sufficient setup boundary, so waiting does not reduce the current product gap.