moonbench

moonbench is a MoonBit benchmark statistics and reporting toolkit for OSC2026. It is not a replacement for the official moon bench runner. It is a small library layer that accepts elapsed nanosecond samples from MoonBit code, platform clocks, CI scripts, or external benchmark logs, then produces:

• aggregate timing summaries: count, total, min, max, mean, spread, throughput;
• distribution statistics: p50, p90, p95, p99, variance, standard deviation;
• sample cleanup for coarse clocks, imported logs, and outliers;
• warm-up removal, sample clamping, and quality scoring;
• baseline regression checks for release and CI review;
• CI budget checks with pass/fail reports;
• machine-readable CSV, JSON, and Markdown output;
• a replaceable Clock adapter for real platform clocks or deterministic tests.

The Mooncakes package README is README.mbt.md. Concrete run data is recorded in data/benchmark-runs.csv with notes in docs/benchmark-data.md.

Quick Start

moon add sa2360/moonbench

In moon.pkg.json or moon.pkg, import the package as bench, then use it from code:

let set = @bench.sample_set_from([1_000_000, 1_200_000, 1_100_000])
println(@bench.sample_set_json(set))

Repository development commands:

moon check
moon build
moon fmt
moon info
moon test
moon run cmd/main

Example

let set = @bench.benchmark_with_clock(5, @bench.system_clock(), () => {
  let mut total = 0
  for i in 0..<20_000_000 {
    total = total + i % 17
  }
  ignore(total)
})

println(@bench.describe(set.summary))
println(@bench.summary_csv(set.summary))
println(@bench.sample_set_json(set))

cmd/main uses the portable env.now() clock. On some platforms that clock is millisecond-grained, so very short samples may round to 0 ns and the demo budget line may occasionally print fail; the command still exits successfully and the CSV/JSON reports remain valid.

External data can be passed in directly:

let imported = @bench.sample_set_from([0, 12_000_000, 12_400_000, 80_000_000])
let cleaned = @bench.filter_samples(
  imported,
  @bench.SampleFilter::{ min_ns: 1, max_ns: 50_000_000, drop_zero: true },
)
let baseline = @bench.sample_set_from([12_200_000, 12_200_000, 12_300_000])

println(@bench.sample_set_markdown(cleaned))
println(@bench.regression_report(cleaned.summary, baseline.summary, 80_000))
println(@bench.quality_report(cleaned, 100_000))

Difference from moon bench

moon bench is the official benchmark command for running benchmark targets. moonbench focuses on the reusable library pieces around benchmark data: statistics, percentiles, budget decisions, report formatting, and clock injection. It can consume samples produced by other tools, including an official benchmark workflow, then turn those samples into release notes or CI guards. See docs/moon-bench-comparison.md.

Project Status

• Language: MoonBit.
• License: MIT.
• CI: GitHub Actions with check, format, info, tests, and runnable example.
• Tests: moonbench_test.mbt covers aggregation, injected clocks, sample cleanup, percentiles, variance, regression budgets, and report output.
• Publishing: run moon login, then moon publish after release review.