Documentation
¶
Overview ¶
Package scenarios is the registration API of tools/perfbench (contract:cli.perfbench v1). A scenario measures one thing about a built nself binary and returns raw samples; perfbench turns the samples into the perfbench/v1 JSON document.
Adding a scenario: implement Scenario in a new file of this package and call Register from that file's init(). A scenario that probes the binary with fixed argument lists should also implement Prober, so `perfbench ab` can interleave two binaries over the same probes.
Index ¶
- Constants
- Variables
- func Names() []string
- func PluginName(i int) (slug, binary string)
- func Register(s Scenario)
- func RunChecked(ctx context.Context, bin, side string, p Probe, o Opts) (float64, error)
- func RunOnce(ctx context.Context, bin string, args []string, o Opts) (float64, int, error)
- func WritePluginHome(home string, n int) error
- type Config
- type Opts
- type Probe
- type ProbeFailure
- type Prober
- type Sample
- type Scenario
Constants ¶
const DefaultTimeout = 30 * time.Second
DefaultTimeout bounds one probe run when Config.Timeout / Opts.Timeout is 0.
const PluginCount = 31
PluginCount is the number of CLI plugins in the generated HOME (the v1 count).
Variables ¶
var ErrTimeout = errors.New("timed out")
ErrTimeout is returned (wrapped) by RunOnce when the process was killed for running past Opts.Timeout.
Functions ¶
func PluginName ¶
PluginName returns the slug and binary of generated plugin i. The command name is never an ADR 0016 verb: names are tool-0 ... tool-30.
func Register ¶
func Register(s Scenario)
Register adds s to the registry. It panics on an empty or duplicate name, because both are programming errors caught at process start.
func RunChecked ¶
RunChecked runs probe p once and returns its wall time in ms. A timeout, a signal death or an exit code other than p.Exit is a *ProbeFailure naming the probe and side. side is "" outside `ab`.
func RunOnce ¶
RunOnce runs bin with args in a clean environment and returns the wall time in milliseconds and the exit code (-1 when a signal killed the process). The probe gets a fresh empty HOME and an empty working directory, telemetry off, stdin at /dev/null and stdout and stderr discarded. Only a failure to start or a timeout is an error; judging the exit code is RunChecked's job.
func WritePluginHome ¶
WritePluginHome creates n CLI plugins under home/.nself/plugins: one <slug>/plugin.json each and one executable stub per binary in plugins/bin.
Types ¶
type Config ¶
type Config struct {
Bin string // path of the nself binary under test
Runs int // measured runs per probe
Warmup int // discarded runs per probe, before the measured ones
Env []string // extra KEY=VALUE entries appended to the probe environment
// Timeout kills one probe run that takes longer (0 means DefaultTimeout).
Timeout time.Duration
}
Config is what perfbench hands to a scenario run.
type Opts ¶
type Opts struct {
Env []string // extra KEY=VALUE entries appended to the probe environment
Slowdown float64 // self-test only: > 1 makes the timed window Slowdown x the measured time
Timeout time.Duration // kill the process after this long; 0 means DefaultTimeout
}
Opts tunes one process run.
type Probe ¶
Probe is one named measurement of a fresh process: the binary is started with Args and its wall time (start to exit) is the sample, in milliseconds. Exit is the exit code the probe must produce (0 for most commands, 1 for a command that is expected to fail, such as `status` in an empty directory). Any other code, including death by signal, fails the run: a binary that crashes at startup is not fast.
type ProbeFailure ¶
type ProbeFailure struct {
Metric string
Side string // "base" or "head" for `ab`, empty for `run`
Reason string
}
ProbeFailure is a measured run that must fail the scenario or the A/B verdict: an unexpected exit code, death by signal, or a timeout.
func (*ProbeFailure) Error ¶
func (e *ProbeFailure) Error() string
type Prober ¶
type Prober interface {
Probes() []Probe
}
Prober is implemented by scenarios made of fixed probes. `perfbench ab` needs it to interleave two binaries over the same probes.
type Sample ¶
Sample is one measurement. Every sample of one Metric must carry the same Unit; perfbench fails the run otherwise.