edison/chanora
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(perf,benchmark-infra): criterion bench harness + advisory CI workflows (SDD-120)

Browse Source 
Implementation of SDD-120 §1-§8:

Bench harness (crates/chanora_audio/benches/):
- common.rs: deterministic synthetic audio (440 Hz sine, no RNG).
- realtime_capture.rs: bench_capture_alloc_count (dhat) +
  bench_capture_callback_wall_clock (criterion).
- opus_codec.rs: bench_opus_encode_latency + bench_opus_decode_latency
  (direct audiopus, not AudioHandler — SDD-120 §3 item 4).
- resampler.rs: bench_resampler_throughput across 44.1->48 /
  16->48 / 48->48 passthrough.

CI tooling (crates/chanora_audio/examples/):
- emit_baseline.rs: aggregates criterion estimates.json outputs
  into the SRS-217 baseline schema.
- compare_baseline.rs: applies SRS-219 tolerance, renders markdown
  table with 🟢/🟡/🔴 markers + yellow simpler-form realization per
  SDD-120 §8.

  Deviation from SDD-120 §2 / §5 / §7 placement: these tools live
  under examples/, not benches/ or src/bin/. Rationale: they must
  consume serde_json (a dev-only dep — production builds must not
  pull it). Cargo only resolves dev-dependencies for [[test]],
  [[bench]], and [[example]] targets; [[bin]] targets under
  src/bin/ see only regular [dependencies]. examples/ keeps the
  binaries out of the production dep tree while still giving them
  cargo run --example invocation. An SDD-120 amendment should
  reflect this.

Workflows (.github/workflows/):
- bench-advisory.yml: PR + push triggers; runs benches; posts a
  sticky PR comment via actions/github-script@v7; job status is
  always success (SRS-218 clause 4 — non-blocking).
- bench-baseline-update.yml: workflow_dispatch only; runs benches;
  opens PR via peter-evans/create-pull-request@v6 (sole writer of
  the SAD-089 baseline JSON).

Cargo.toml additions ([dev-dependencies] only — verified excluded
from --release builds): criterion 0.5, dhat 0.3, serde_json 1.

Source-code seam: minimal pub-but-#[doc(hidden)] bench_seam module
in chanora_audio (engine.rs + lib.rs re-export) so the criterion
bench harness can construct a CaptureState and drive
CaptureState::ingest without re-implementing the engine (SDD-120
§3). Non-iOS targets only — CaptureState itself is iOS-gated.

Initial baseline seed: crates/chanora_audio/benches/baselines/
x86_64-unknown-linux-gnu.json = {}. compare_baseline handles the
missing-baseline case gracefully and emits a 'no red markers'
report; the first manual dispatch of bench-baseline-update.yml
after merge establishes the real values.

Out of scope per SDD-120 §10: production telemetry export,
build-failing hard CI gate, multi-host benchmarking, IDE
integration, Dart-side bridge round-trip bench.

Verification:
- cargo check --workspace --all-targets: PASS.
- cargo bench --bench realtime_capture --no-run: PASS.
- cargo bench --bench opus_codec --no-run: PASS.
- cargo bench --bench resampler --no-run: PASS.
- cargo build --example emit_baseline --example compare_baseline
  -p chanora_audio: PASS.
- cargo test --workspace: 106 passed, 0 failed, 3 ignored — no
  regression from prior count.
This commit is contained in:
EdisonJwa
2026-05-18 13:52:15 +08:00
parent 575a6cbc5c
commit 7188a5a69d
13 changed files with 1248 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
crates/chanora_audio/examples/compare_baseline.rs
+240
View File
@@ -0,0 +1,240 @@
// SDD-120 §8 — PR-vs-baseline comparator binary.
//
// Reads `current.json` (from §5 emit_baseline) and `baseline.json`
// (extracted from the SAD-089 path at the merge-base by the §6
// workflow) and emits a markdown report applying:
//
// - Zero-tolerance metrics (SRS-219 clause a — capture_alloc_count):
// 🔴 if c != 0 else 🟢. Yellow does not apply.
// - Otherwise (t > 0):
// delta_pct = (c - b) / b (or 0 if b == 0)
// 🔴 if delta_pct > t
// 🟡 if 0.5*t < delta_pct ≤ t
// 🟢 otherwise (including improvements, delta_pct < 0)
//
// Always exits 0 — regression detection is rendered as a 🔴 marker
// inside the markdown comment, NOT as a non-zero exit code
// (SRS-218 clause 4).
//
// CLI:
// cargo run --bin compare_baseline -- \
// --current ./current.json \
// --baseline ./baseline.json \
// --output ./report.md
use std::collections::HashMap;
use std::fs;
use std::path::PathBuf;
use std::process::ExitCode;
use serde_json::Value;
struct Args {
current: PathBuf,
baseline: PathBuf,
output: PathBuf,
}
fn parse_args() -> Args {
let mut current = PathBuf::from("current.json");
let mut baseline = PathBuf::from("baseline.json");
let mut output = PathBuf::from("report.md");
let mut it = std::env::args().skip(1);
while let Some(a) = it.next() {
match a.as_str() {
"--current" => current = PathBuf::from(it.next().unwrap_or_default()),
"--baseline" => baseline = PathBuf::from(it.next().unwrap_or_default()),
"--output" => output = PathBuf::from(it.next().unwrap_or_default()),
_ => {}
}
}
Args {
current,
baseline,
output,
}
}
fn read_metrics(path: &PathBuf) -> (Option<Value>, HashMap<String, MetricRow>) {
let mut out = HashMap::new();
let text = match fs::read_to_string(path) {
Ok(t) => t,
Err(_) => return (None, out),
};
if text.trim().is_empty() || text.trim() == "{}" {
return (None, out);
}
let v: Value = match serde_json::from_str(&text) {
Ok(v) => v,
Err(_) => return (None, out),
};
let metrics = v.get("metrics").and_then(|m| m.as_array()).cloned();
if let Some(arr) = metrics {
for m in arr {
let name = m
.get("metric")
.and_then(|s| s.as_str())
.unwrap_or("")
.to_string();
let unit = m
.get("unit")
.and_then(|s| s.as_str())
.unwrap_or("")
.to_string();
let value = m.get("value").and_then(|n| n.as_f64());
let tolerance = m
.get("tolerance_pct")
.and_then(|n| n.as_f64())
.unwrap_or(0.0);
if !name.is_empty() {
out.insert(
name.clone(),
MetricRow {
metric: name,
unit,
value,
tolerance_pct: tolerance,
},
);
}
}
}
(Some(v), out)
}
#[derive(Clone)]
struct MetricRow {
metric: String,
unit: String,
value: Option<f64>,
tolerance_pct: f64,
}
fn fmt_value(v: Option<f64>) -> String {
match v {
Some(x) if x.is_finite() => {
if x.abs() >= 1_000_000.0 {
format!("{:.3e}", x)
} else if x.abs() >= 1.0 {
format!("{:.3}", x)
} else {
format!("{:.6}", x)
}
}
_ => "n/a".to_string(),
}
}
fn marker(b: Option<f64>, c: Option<f64>, t: f64) -> (String, String) {
// Returns (marker, delta_str)
let (b, c) = match (b, c) {
(Some(b), Some(c)) => (b, c),
_ => return ("⚪".to_string(), "n/a".to_string()),
};
if t == 0.0 {
// Zero-tolerance metric (SRS-219 clause a).
if c != 0.0 {
return ("🔴".to_string(), format!("{:+}", c as i64));
} else {
return ("🟢".to_string(), "+0".to_string());
}
}
let delta_pct = if b > 0.0 { (c - b) / b } else { 0.0 };
let delta_str = format!("{:+.2}%", delta_pct * 100.0);
let m = if delta_pct > t {
"🔴"
} else if delta_pct > 0.5 * t {
"🟡"
} else {
"🟢"
};
(m.to_string(), delta_str)
}
fn main() -> ExitCode {
let args = parse_args();
let (cur_doc, cur) = read_metrics(&args.current);
let (base_doc, base) = read_metrics(&args.baseline);
let mut md = String::new();
md.push_str("<!-- chanora-bench-advisory -->\n");
md.push_str("### Chanora realtime-audio benchmark advisory (SDD-120)\n\n");
if cur_doc.is_none() {
md.push_str("_No `current.json` found — bench harness did not produce results._\n");
fs::write(&args.output, &md).expect("write report");
return ExitCode::SUCCESS;
}
if base.is_empty() {
md.push_str(
"_Baseline not yet established at merge-base; first dispatch of \
`bench-baseline-update.yml` on the default branch will establish \
it. No red markers emitted on this first run._\n\n",
);
md.push_str("| Metric | Unit | Current |\n");
md.push_str("|---|---|---|\n");
let mut keys: Vec<&String> = cur.keys().collect();
keys.sort();
for k in keys {
let row = &cur[k];
md.push_str(&format!(
"| `{}` | {} | {} |\n",
row.metric,
row.unit,
fmt_value(row.value)
));
}
fs::write(&args.output, &md).expect("write report");
return ExitCode::SUCCESS;
}
if let Some(d) = base_doc.as_ref() {
if let Some(sha) = d.get("git_sha").and_then(|s| s.as_str()) {
md.push_str(&format!("Baseline `git_sha`: `{}`\n\n", sha));
}
}
md.push_str("| Metric | Unit | Baseline | Current | Δ | Tolerance | Status |\n");
md.push_str("|---|---|---|---|---|---|---|\n");
// Iterate over the union of metric names, sorted.
let mut all: Vec<String> = cur.keys().chain(base.keys()).cloned().collect();
all.sort();
all.dedup();
for name in all {
let c = cur.get(&name);
let b = base.get(&name);
let unit = c
.map(|r| r.unit.clone())
.or_else(|| b.map(|r| r.unit.clone()))
.unwrap_or_default();
let tol = c
.map(|r| r.tolerance_pct)
.or_else(|| b.map(|r| r.tolerance_pct))
.unwrap_or(0.0);
let (m, delta) = marker(b.and_then(|r| r.value), c.and_then(|r| r.value), tol);
md.push_str(&format!(
"| `{}` | {} | {} | {} | {} | {} | {} |\n",
name,
unit,
fmt_value(b.and_then(|r| r.value)),
fmt_value(c.and_then(|r| r.value)),
delta,
if tol == 0.0 {
"0 (zero-tolerance)".to_string()
} else {
format!("{:.1}%", tol * 100.0)
},
m,
));
}
md.push_str(
"\n_Advisory only — this workflow never fails a check on regression \
(SRS-218 clause 4)._\n",
);
fs::write(&args.output, &md).expect("write report");
ExitCode::SUCCESS
}
crates/chanora_audio/examples/emit_baseline.rs
+207
View File
@@ -0,0 +1,207 @@
// SDD-120 §5 — JSON post-processor binary.
//
// Reads criterion's per-bench `target/criterion/<group>/<bench>/estimates.json`
// outputs, plus the `capture_alloc_count.sidecar` value written by
// `realtime_capture.rs`, and projects them into the SRS-217 schema:
// {
// "host": "x86_64-unknown-linux-gnu",
// "toolchain": "<rustc -V>",
// "git_sha": "<HEAD>",
// "timestamp": "<RFC3339 UTC>",
// "metrics": [
// { "metric": "<name>", "value": <f64>, "unit": "<u>",
// "tolerance_pct": <f64>, ... },
// ...
// ]
// }
//
// Writes the document to `./current.json`.
//
// Run as: `cargo run --bin emit_baseline -p chanora_audio`.
use std::env;
use std::fs;
use std::path::{Path, PathBuf};
use std::process::Command;
use std::time::{SystemTime, UNIX_EPOCH};
use serde_json::{json, Value};
/// Per-metric SRS-219 tolerance entries. Zero-tolerance metrics
/// per SRS-219 clause a use 0.0 here; the comparator collapses
/// them to 🔴/🟢 only.
fn metric_table() -> Vec<(&'static str, &'static str, f64)> {
// (metric_name, unit, tolerance_pct)
vec![
("capture_alloc_count", "blocks", 0.0),
("capture_callback_wall_clock", "ns", 0.10),
("opus_encode_latency", "ns", 0.10),
("opus_decode_latency", "ns", 0.10),
("resampler_44100_to_48000", "samples_per_sec", 0.10),
("resampler_16000_to_48000", "samples_per_sec", 0.10),
("resampler_48000_passthrough", "samples_per_sec", 0.10),
]
}
fn target_dir() -> PathBuf {
env::var("CARGO_TARGET_DIR")
.map(PathBuf::from)
.unwrap_or_else(|_| PathBuf::from("target"))
}
/// Read criterion `estimates.json` for a given bench function
/// name (criterion writes one per non-grouped bench under
/// `target/criterion/<bench>/new/estimates.json`).
fn read_estimate_ns(name: &str) -> Option<f64> {
let path = target_dir()
.join("criterion")
.join(name)
.join("new")
.join("estimates.json");
let text = fs::read_to_string(&path).ok()?;
let v: Value = serde_json::from_str(&text).ok()?;
// criterion estimates.json has `mean.point_estimate` (in ns).
v.get("mean")
.and_then(|m| m.get("point_estimate"))
.and_then(|p| p.as_f64())
}
/// Read criterion `estimates.json` for a sub-bench inside a group
/// (criterion writes group sub-benches under
/// `target/criterion/<group>/<sub>/new/estimates.json`).
fn read_estimate_group_ns(group: &str, sub: &str) -> Option<f64> {
let path = target_dir()
.join("criterion")
.join(group)
.join(sub)
.join("new")
.join("estimates.json");
let text = fs::read_to_string(&path).ok()?;
let v: Value = serde_json::from_str(&text).ok()?;
v.get("mean")
.and_then(|m| m.get("point_estimate"))
.and_then(|p| p.as_f64())
}
/// Resampler reports throughput; convert ns-per-iter to samples
/// per second using the per-iter input length (1s @ rate).
fn ns_to_throughput(ns_per_iter: f64, samples_per_iter: f64) -> f64 {
if ns_per_iter <= 0.0 {
return 0.0;
}
samples_per_iter * 1_000_000_000.0 / ns_per_iter
}
fn read_alloc_sidecar() -> Option<f64> {
let path = target_dir()
.join("criterion")
.join("capture_alloc_count.sidecar");
let s = fs::read_to_string(&path).ok()?;
s.trim().parse::<f64>().ok()
}
fn rustc_version() -> String {
Command::new("rustc")
.arg("-V")
.output()
.ok()
.and_then(|o| {
if o.status.success() {
Some(String::from_utf8_lossy(&o.stdout).trim().to_string())
} else {
None
}
})
.unwrap_or_else(|| "unknown".to_string())
}
fn git_sha() -> String {
Command::new("git")
.args(["rev-parse", "HEAD"])
.output()
.ok()
.and_then(|o| {
if o.status.success() {
Some(String::from_utf8_lossy(&o.stdout).trim().to_string())
} else {
None
}
})
.unwrap_or_else(|| "unknown".to_string())
}
fn rfc3339_now() -> String {
let secs = SystemTime::now()
.duration_since(UNIX_EPOCH)
.map(|d| d.as_secs())
.unwrap_or(0);
// Minimal RFC3339-style UTC encoder; avoids pulling chrono.
// Algorithm: civil-from-days (Howard Hinnant).
let z = secs / 86_400;
let day_secs = secs % 86_400;
let hh = day_secs / 3600;
let mm = (day_secs % 3600) / 60;
let ss = day_secs % 60;
let z_shift = z as i64 + 719_468;
let era = z_shift.div_euclid(146_097);
let doe = z_shift.rem_euclid(146_097) as u64;
let yoe = (doe - doe / 1460 + doe / 36_524 - doe / 146_096) / 365;
let y = yoe as i64 + era * 400;
let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
let mp = (5 * doy + 2) / 153;
let d = doy - (153 * mp + 2) / 5 + 1;
let m = if mp < 10 { mp + 3 } else { mp - 9 };
let year = if m <= 2 { y + 1 } else { y };
format!(
"{:04}-{:02}-{:02}T{:02}:{:02}:{:02}Z",
year, m, d, hh, mm, ss
)
}
fn main() {
let mut metrics: Vec<Value> = Vec::new();
for (name, unit, tol) in metric_table() {
let value = match name {
"capture_alloc_count" => read_alloc_sidecar(),
"capture_callback_wall_clock" => read_estimate_ns(name),
"opus_encode_latency" => read_estimate_ns(name),
"opus_decode_latency" => read_estimate_ns(name),
"resampler_44100_to_48000" => read_estimate_group_ns(
"resampler_throughput",
"44100_to_48000",
)
.map(|ns| ns_to_throughput(ns, 44_100.0)),
"resampler_16000_to_48000" => read_estimate_group_ns(
"resampler_throughput",
"16000_to_48000",
)
.map(|ns| ns_to_throughput(ns, 16_000.0)),
"resampler_48000_passthrough" => read_estimate_group_ns(
"resampler_throughput",
"48000_passthrough",
)
.map(|ns| ns_to_throughput(ns, 48_000.0)),
_ => None,
};
let v = value.unwrap_or(f64::NAN);
metrics.push(json!({
"metric": name,
"value": if v.is_finite() { Value::from(v) } else { Value::Null },
"unit": unit,
"tolerance_pct": tol,
}));
}
let doc = json!({
"host": "x86_64-unknown-linux-gnu",
"toolchain": rustc_version(),
"git_sha": git_sha(),
"timestamp": rfc3339_now(),
"metrics": metrics,
});
let out_path = Path::new("current.json");
fs::write(out_path, serde_json::to_string_pretty(&doc).unwrap())
.expect("write current.json");
eprintln!("emit_baseline: wrote {}", out_path.display());
}