Skip to content

performance.md

Latest commit

 

History

History
69 lines (50 loc) · 2.15 KB

performance.md

File metadata and controls

69 lines (50 loc) · 2.15 KB

Performance Baselines

Use this workflow before optimizing engine hot paths. The goal is to compare changes against a local Criterion baseline instead of relying on one-off timings.

Focused Hot Paths

Start with the focused ECS/render workflow:

scripts/perf_baseline.sh smoke
scripts/perf_baseline.sh save main
scripts/perf_baseline.sh compare main

The script runs:

  • euca-ecs/ecs_bench: spawn, query, query cache, change detection, scheduler, archetype fragmentation, and batch spawn paths.
  • euca-render/render_bench: CPU-side render extraction, extractor sync, partial sync, and batch building.

Criterion output is written to target/criterion.

Local Workflow

  1. Run scripts/perf_baseline.sh smoke after dependency or benchmark changes. This compiles and executes the benchmark targets as tests, which is much faster than taking full measurements.
  2. Before a performance change, run scripts/perf_baseline.sh save main.
  3. Make the change.
  4. Run scripts/perf_baseline.sh compare main.
  5. Inspect target/criterion/report/index.html for the full Criterion report.

For broad engine changes, also run the full workspace benchmark suite:

cargo bench --workspace

Interpreting Results

  • Treat changes under 5% as noise unless they reproduce several times.
  • Treat 5-10% slowdowns as suspicious and worth a second run.
  • Treat slowdowns over 10% on ECS/render hot paths as regressions unless there is a clear product tradeoff.
  • Compare on the same machine, power mode, and thermal state. Do not compare local numbers across different machines.

CI

The GitHub Actions benchmark job runs on macOS. Push and pull request builds compile all workspace benchmark targets, then run the measured smoke suite:

scripts/ci_bench.sh smoke

Pushes to main save the smoke measurements as the main Criterion baseline. Pull requests restore the most recent main baseline when one is available, run scripts/ci_bench.sh smoke-compare main, and report regressions over the configured threshold.

Full workspace Criterion measurements are reserved for scheduled and manual CI runs:

scripts/ci_bench.sh full-save main