perfgate

Catch performance regressions in CI before they ship.

Install

Use the binary installer path first:

cargo binstall perfgate-cli

Or install from source:

cargo install perfgate-cli

Prebuilt archives are published on GitHub Releases for Linux, macOS, and Windows. Verify the binary with:

perfgate --version
perfgate doctor --help

Current public release: v0.18.0. The five public crates, GitHub release assets, v0.18, and v0 action aliases are published for 0.18.0.

Start Here

From a repository root, use the smallest useful path first:

perfgate doctor
perfgate init --ci github --profile standard --suggest-benches
perfgate doctor --config perfgate.toml
perfgate check --config perfgate.toml --all
perfgate baseline promote --config perfgate.toml --all
perfgate check --config perfgate.toml --all --require-baseline
git add perfgate.toml .github/workflows/perfgate.yml baselines/ .perfgate/

For a concrete cold-start walkthrough, including expected files, artifacts, pass/fail behavior, and what to commit, see docs/FIRST_HOUR.md. --suggest-benches appends commented benchmark candidates so benchmark choice stays reviewable; edit or replace them before promoting a baseline.

perfgate init --ci github --profile standard --suggest-benches creates:

perfgate.toml
.github/workflows/perfgate.yml
baselines/.gitkeep
.perfgate/README.md

The generated config defaults to local checked-in baselines and predictable artifacts. Suggested benches are comments until you intentionally edit them into the config:

[defaults]
repeat = 7
warmup = 1
threshold = 0.20
warn_factor = 0.50
noise_threshold = 0.10
noise_policy = "warn"
out_dir = "artifacts/perfgate"
baseline_dir = "baselines"

[[bench]]
name = "my-service"
command = ["./target/release/my-bench"]

The generated GitHub workflow uses the repository action:

- uses: EffortlessMetrics/perfgate@v0
  with:
    config: perfgate.toml
    all: "true"
    require_baseline: "true"
    upload_artifact: "true"

Use @v0.18.0 for an exact patch pin, @v0.18 for the current 0.18 line, or @v0 to follow the current compatible action tag.

Performance Decisions

The normal gate is still perfgate check. When a repo has workload scenarios, probe evidence, or accepted tradeoff policy, use the one-command decision workflow after check:

perfgate decision evaluate --config perfgate.toml

It writes scenario.json, tradeoff.json, decision.md, and decision.index.json under the configured artifact directory. decision.md is the review surface: it explains the weighted workload result, probe movement, accepted or rejected tradeoff rules, policy reasons, evidence files, and the local reproduction command. decision.index.json is the machine-readable manifest for the evidence files behind that review. When scenarios configure probe baseline/current paths, decision evaluate also writes the configured probe-compare.json before evaluating the decision. To attach or archive the whole decision evidence set, export the indexed bundle:

perfgate decision bundle --index artifacts/perfgate/decision.index.json --out artifacts/perfgate/decision-bundle.json

Teams running the baseline server can persist that decision evidence as a ledger, export it for audits, and prune old records explicitly:

perfgate decision upload --file artifacts/perfgate/tradeoff.json --index artifacts/perfgate/decision.index.json
perfgate decision export --days 90 --out artifacts/perfgate/decision-history.jsonl
perfgate decision prune --older-than 365d --dry-run

In GitHub Actions, opt in with:

- uses: EffortlessMetrics/perfgate@v0
  with:
    config: perfgate.toml
    all: "true"
    require_baseline: "true"
    decision: "true"
    review_required: "warn"

Use review_required: "fail" when review-required decisions should block branch protection, or review_required: "pass" when another workflow step owns that review policy.

Adoption levels

Perfgate is designed to be adopted in stages:

• Basic gate — perfgate check and tracked baselines.
• Action gate — run the same checked-in policy in GitHub Actions.
• Decision mode — add [[scenario]] and [[tradeoff]] config plus perfgate decision evaluate.
• Ledger mode — connect a baseline server, upload decisions, and use decision export|history|debt|prune for auditability.

Use that order to start quickly, then opt into richer tradeoff review and auditable governance as teams become ready. See docs/ADOPTION_LEVELS.md for the commands, config, artifacts, failure examples, and next step for each level. For team ledger operations, see docs/DECISION_LEDGER_RUNBOOK.md.

Daily Use

Run the whole configured suite:

perfgate check --config perfgate.toml --all

Inspect local baseline state:

perfgate baseline status --config perfgate.toml

Promote a trusted current run into local baselines:

perfgate baseline promote --config perfgate.toml --all

Diagnose setup or path issues:

perfgate doctor --config perfgate.toml

Exit codes are stable: 0 pass, 1 tool/runtime error, 2 budget fail, and 3 warn treated as failure with --fail-on-warn.

Artifacts

check --bench <name> writes:

artifacts/perfgate/
  run.json
  compare.json  # when a baseline exists
  report.json
  comment.md

check --all writes per-benchmark subdirectories, even when the config only has one benchmark:

artifacts/perfgate/<bench>/
  run.json
  compare.json  # when a baseline exists
  report.json
  comment.md

run.json, compare.json, and report.json are versioned machine-readable receipts. compare.json is omitted while bootstrapping without a baseline. See Artifact Layouts and Output Schemas for the contract details.

What Gets Measured

Metric	Description
wall_ms	Wall-clock time
cpu_ms	User + system CPU time
max_rss_kb	Peak resident set size
page_faults	Major page faults where available
ctx_switches	Context switches where available
binary_bytes	Executable size
throughput_per_s	Ops/sec with --work

Metric availability is platform-specific. See docs/status/PLATFORM_SUPPORT.md before making non-wall-clock metrics required gates.

perfgate supports local baselines, cloud paths, and the optional baseline server, but local in-repo baselines are the default first setup.

Documentation

Start with:

• GitHub Actions
• Configuration
• Artifact Layouts
• Debugging the First CI Run
• Failure Playbook

For specific workflows:

• Performance Decisions
• Probe Instrumentation Quickstart
• Probe Design Patterns
• Signal Calibration
• Platform Metric Support
• Step-by-Step Pipeline
• Baseline Server
• Paired Benchmarking
• Flakiness History
• Fleet Aggregation
• Performance Decision Example
• Cockpit Integration
• Exporting Data
• Host Mismatch Detection

For project contracts and internals:

• Output Schemas
• Architecture
• Public Crate Seams
• Release Readiness

Public Crates

The intended public package surface is:

perfgate
perfgate-cli
perfgate-types
perfgate-client
perfgate-server

Internal seams live behind modules and private compatibility wrappers. The workspace enforces this with cargo run -p xtask -- public-surface --strict and cargo run -p xtask -- arch.

Contributing

See CONTRIBUTING.md for development setup, testing, and repo automation.

License

Dual-licensed under MIT or Apache-2.0.