Expand description
Versioned JSONL performance recorder for Ailloli UI.
New integrations should retain the BenchInit returned by
try_init_from_env and call BenchInit::finish before shutdown. The
session writes to a staging file through a bounded queue and publishes the
final artifact only after a successful flush and sync.
record and metric remain global conveniences. init_from_env is a
deprecated, append-only compatibility path and must not be used for a
regression gate.
§Command-line gate
The ailloli-ui-bench binary is intentionally opt-in. Every Cargo command
which uses it must enable the cli feature explicitly, for example:
cargo run --release -p ailloli_ui_bench --features cli \
--bin ailloli-ui-bench --locked -- summarize --input <scenario-directory>A canonical native matrix first builds the measured child, then gives that
executable to the CLI after --:
cargo build --release --locked -p ailloli_ui_winit \
--features test_support --example winit_regression_bench
cargo run --release --locked -p ailloli_ui_bench --features cli \
--bin ailloli-ui-bench -- run-matrix \
--output-root artifacts/bench/winit_host_architecture --phase candidate \
--winit-version 0.30.13 --backend wayland --profile release \
--harness winit_regression_bench --scenario wake_single \
-- target/release/examples/winit_regression_benchCompare one exact backend/scenario pair at a time. run-matrix writes a
matrix-index.json beside each scenario’s replicates; summarize and
compare validate that index and every recorded SHA-256 when it is present.
cargo run --release --locked -p ailloli_ui_bench --features cli \
--bin ailloli-ui-bench -- compare \
--baseline artifacts/bench/winit_host_architecture/baseline/winit-0.30.13/wayland/wake_single \
--candidate artifacts/bench/winit_host_architecture/candidate/winit-0.30.13/wayland/wake_singleThe only compatibility field which can be waived is winit_version, via an
explicit compare --allow-winit-version-diff; schema, scenario, profile,
geometry, requested/observed DPR and environment identity remain exact.
There is no valid legacy pre-architecture wake/mailbox baseline: that path did not exist before the refactor. Its historical value is therefore N/A, not a synthetic measurement. The matrix index exposes this status explicitly.
Structs§
- Bench
Config - Scripted benchmark parameters read by integration harnesses.
- Bench
Event Record - Parsed correlated event line. The payload remains a JSON value so readers can retain events introduced by future schema revisions.
- Bench
Session - Guard for a single, explicitly finalized benchmark run.
- Bench
Surface Id - Stable logical surface identifier used by benchmark correlation.
- Bench
Window Id - Stable logical window identifier used by benchmark correlation.
- Completed
Run - Successfully published benchmark artifact.
- Event
Context - Correlation attached to a recorded event.
- EventId
- Monotonic identifier of an event within one run.
- FrameId
- Identifier of a rendered frame within one run.
- Memory
Trend Summary - Deterministic memory-trend decision for a sampled process.
- Metadata
Update Record - Parsed
metadata_updateline. - Metric
Comparison - Regression decision for one metric.
- Metric
Sample - One finite numeric sample together with its explicit regression role.
- Metric
Summary - Summary of one named metric, including its gate behavior and process count.
- Parsed
Run - Parsed representation of one run.
- Process
Resource Snapshot - One out-of-band sample of a benchmark process.
- Recorder
- Legacy append-only JSONL writer.
- RunEnd
Record - Parsed
run_endline. - RunId
- Identifier of one benchmark run.
- RunMetadata
- Reproducibility metadata for one benchmark run.
- RunStart
Record - Parsed
run_startline. - Sample
Summary - Deterministic summary of one finite sample series.
- Span
- Scoped timing helper; see
span.
Enums§
- Bench
Init - Result of environment-driven benchmark initialization.
- Bench
Init Error - Failure while creating a benchmark session.
- Bench
Read Error - Failure while reading a benchmark artifact.
- Bench
Write Error - Failure while recording or finalizing a benchmark run.
- Comparison
Mode - Whether a comparison represents steady-state or cold-start measurements.
- Event
- One JSONL event payload.
- LogRecord
- One parsed line from a benchmark artifact.
- Metric
Role - Regression role carried by an explicit numeric metric.
- Process
Sample Error - Failure to obtain an exact process-resource snapshot.
- Sample
Phase - Classification of a sample for deterministic warmup exclusion.
- Stats
Error - Invalid input for deterministic statistics.
- Time
Origin - Origin used by elapsed-time measurements in a run.
Constants§
- MAX_
RSS_ EXTENT_ MIB - Maximum accepted RSS extent after the soak warmup period.
- MAX_
RSS_ SLOPE_ MIB_ PER_ SEC - Maximum accepted RSS growth during a tree virtualization steady-state soak.
- SCHEMA_
VERSION - Version of the JSONL wire schema emitted by this crate.
Functions§
- bench_
enabled - Whether benchmark recording is enabled through the environment.
- bench_
phase_ from_ env - Bench phase selected through the framework environment namespace.
- bench_
scenario_ from_ env - Scenario name selected through the framework environment namespace.
- collect_
run_ files - Recursively finds
.jsonlartifacts without following directory symlinks. - compare_
metric - Compares two summaries using
baseline + max(10%, 3 * baseline MAD). - compare_
metric_ with_ role - Compares two summaries according to the role carried by the metric.
- config_
from_ env - Builds
BenchConfigfrom framework and compatibility environment names. - frames_
from_ env - Frame count for integration benchmarks (
AILLOLI_UI_BENCH_FRAMES, default 60). - init_
from_ env Deprecated - Enables the historical append-only global recorder.
- metadata_
from_ env - Builds the initial reproducibility metadata snapshot from the environment.
- metric
- Records a named metric on the global recorder.
- metric_
with_ role - Records a named metric with explicit regression behavior.
- read_
run - Reads a version-tolerant benchmark JSONL artifact.
- record
- Records an event on the global recorder. This convenience intentionally
ignores errors; gating integrations should call
try_recordor use the retainedBenchSessiondirectly. - sample_
current_ process - Samples the current process from the operating system’s process interface.
- sample_
process - Samples RSS, proportional set size, threads, and open descriptors.
- span
- Starts an RAII timing span recorded as a marker on drop.
- summarize_
memory_ trend - Evaluates the locked tree virtualization RSS slope and extent limits.
- summarize_
runs - Aggregates samples without exposing gate roles to compatibility callers.
- summarize_
runs_ with_ roles - Aggregates all metric samples, roles, and process counts from parsed runs.
- summarize_
samples - Computes standard median, nearest-rank p95/p99, and median absolute deviation.
- theil_
sen_ slope - Computes the deterministic Theil–Sen slope of
(seconds, value)samples. - try_
allocate_ frame_ id - Allocates a frame identifier on the global session.
Returns
Ok(None)when the recorder is disabled or legacy. - try_
init_ from_ env - Initializes a gating benchmark session from environment variables.
- try_
record - Attempts to record a globally correlated event.
- try_
update_ metadata - Publishes provider metadata learned after startup on the global session.
Returns
Ok(false)when the recorder is disabled or legacy. - try_
update_ window_ observation - Publishes the effective winit backend and DPR observed from a live window.