CLI command

probierz durations compare

Decide whether an optimization cut an operation's median time by the share this instance requires.

Invocation#

Shell
probierz durations compare (<name> [--baseline <id>] [--candidate <id>] | --all)

Required inputs and options#

  • The share is this instance's durations.reduction (probierz config set durations.reduction <share>): the candidate's median may be at most 1 - reduction of the baseline's.
  • With <name>, the baseline is its first measurement and the candidate its newest unless named. With --all, every operation whose first measurement was slow, past durations.slow-seconds, is compared, first against newest.

Output and state effects#

Reads only. Writes {reduction, required, operations: [{name, baseline: {id, medianSeconds, sha256, revision}, candidate: {id, medianSeconds, sha256, revision}, ratio, reduced, sameCode, why}]}; ratio is the candidate's median over the baseline's, required is 1 - reduction, and an operation is reduced when its ratio is at most required. sameCode says both measurements ran the same executable from the same checkout revision: the time then changed elsewhere (a program it calls, the data it reads, the machine), which the reader weighs; it does not change the verdict. An operation measured once, or whose first measurement took no measurable time, is not reduced, why saying so.

Exact refusals#

  • reduction-unset (exit 1): durations.reduction is unset; threshold-unset (exit 1): --all with durations.slow-seconds unset; nothing is compared.
  • measurement-unknown (exit 2): no such operation or measurement; baseline-missing (exit 1): the named operation was measured once.
  • not-reduced (exit 1): an operation compared did not reach the required share; each is named with its two medians and its ratio, after the answer is written. Real test: tests/durations/durations.rs.

Declared refusals#

What probierz refusals list declares for this command at revision d2cd6156e8b8dc6204dab7b46ec0b34b2bb03cea (probierz 0.1.7 (revision unknown, not built from a git checkout)): each cause's id, the operation declaring it, its exit status and code, and its remedy.

  • threshold-unset (probierz.durations, exit 1, config): {doing}: no threshold names how long an operation may take before it counts as slow: neither --over nor this instance's durations.slow-seconds is set. set the threshold with probierz config set durations.slow-seconds <seconds>, or name it with --over.
  • register-unread (probierz.durations, exit 69, infra_down): reading the waits Stado measured on this machine ({command}): {why}. install Stado where PATH finds it (stado --version), then repair what its answer names; stado waits measured --json is the reading.
  • name-invalid (probierz.durations, exit 2, refused): naming the operation {name}: an operation's name is lowercase letters, digits, ., - and _, starting with a letter or digit, so it is one directory of the kept measurements. name it like oko-defects-list.
  • runs-invalid (probierz.durations, exit 2, refused): measuring {name} {runs} time(s): a measurement runs the operation at least once. pass --runs with a whole number above zero.
  • cwd-invalid (probierz.durations, exit 2, refused): running {name} in {cwd}: the directory an operation runs in is absolute and exists, so every measurement of it runs in the same place. pass --cwd with an absolute directory that exists.
  • command-changed (probierz.durations, exit 2, refused): measuring {name} as {command} in {cwd}: {name} was first measured as {first} in {first_cwd}; an optimization changes the code a command runs, not the command, so its measurements compare only while the command stays. measure it with its first command, or name the new command another operation.
  • program-missing (probierz.durations, exit 1, config): finding the program {program} of {name}: {why}. name the program by a path that exists, or install it where PATH finds it.
  • run-failed (probierz.durations, exit 1, config): run {run} of {runs} of {name} ({command}): {status}, and a command that fails measures nothing. make the command succeed in {cwd}, then measure it again.
  • measurement-unreadable (probierz.durations, exit 1, config): reading the kept measurement {file}: {why}. remove the file, or put back the measurement probierz durations measure wrote.
  • measurement-unknown (probierz.durations, exit 2, refused): finding {what}: no measurement is kept under that name or id. name one probierz durations list (or show <name>) shows.
  • reduction-unset (probierz.durations, exit 1, config): deciding whether {name} was cut by the share this instance requires: this instance's durations.reduction is unset, so no share decides it. set the share with probierz config set durations.reduction <share>.
  • baseline-missing (probierz.durations, exit 1, config): comparing {name} with its first measurement: {name} was measured once, so nothing is there to compare it with. measure it again after the optimization: probierz durations measure {name} … with its first command.
  • not-reduced (probierz.durations, exit 1, config): cutting the time of {count} operation(s) by {reduction}: their median is above {required} of their first measurement's. optimize what each named operation spends its time on, then measure it again.

Source snapshot#

Generated from the Rust binaries at revision 99a74945a3598a8d73b6c6cbe5aae4f283becea3 of Probierz's private source repository.

Combined help SHA-256: 77529678a61237f774b59e76df0d1907cb749ef5da56d2ed913b040793b7d30b; binary SHA-256: be9e0eaff0e6ea50403a0c6f6d467697a4eac676f9523b8dc13a596d2b5526c5.