Documentation
¶
Overview ¶
Package runner runs a scenario in-process (no server or database) and produces a report. It backs `stampede run`.
Index ¶
- Constants
- Variables
- func Annotate(rep *report.Report, res *coordinator.Result)
- func ConfirmScenario(s *scenario.Scenario, plan *scenario.Plan, level float64) (*scenario.Scenario, *scenario.Plan, error)
- func Refine(ctx context.Context, bp *report.Breakpoint, mode string, rounds int, run Round) error
- func Run(ctx context.Context, o Options) (*report.Report, error)
- func RunDistributed(ctx context.Context, o DistributedOptions) (*report.Report, *coordinator.Result, error)
- type AbortWatcher
- type BreakpointTracker
- type DistributedOptions
- type FaultPlan
- type FaultRun
- type Options
- type Progress
- type Round
- type SelfMonitor
Constants ¶
const RefineRounds = 3
RefineRounds is how many confirmation holds narrow a breakpoint once a level fails: each halves the gap between the last level that held and the first that failed.
Variables ¶
var ErrNoTargets = fmt.Errorf("the breakpoint shape needs at least one target, for example targets: [\"http.p95 < 500ms\", \"errors < 1%%\"]")
ErrNoTargets explains that a breakpoint run needs targets.
Functions ¶
func Annotate ¶
func Annotate(rep *report.Report, res *coordinator.Result)
Annotate adds the per-worker table and explains losses, failures and saturation in the report's notes.
func ConfirmScenario ¶
func ConfirmScenario(s *scenario.Scenario, plan *scenario.Plan, level float64) (*scenario.Scenario, *scenario.Plan, error)
ConfirmScenario is s with its load replaced by one breakpoint step at level: the original ramp, then half the original hold, but at least 15s (or the whole hold when that is shorter).
func Refine ¶
Refine narrows a found breakpoint by bisection. The breakpoint's LastPass and FirstFail become the tightest bracket found, and each round is listed in Refined. A round that errors stops the refinement and keeps what was learned.
func RunDistributed ¶
func RunDistributed(ctx context.Context, o DistributedOptions) (*report.Report, *coordinator.Result, error)
RunDistributed runs a scenario across the coordinator's workers and builds its report the same way Run does for a single engine. The coordinator's result is returned too, for per-worker detail. When ctx is cancelled the run is stopped gracefully, like a local run.
If no worker finished, the report (built from whatever arrived), the result and an error are all returned.
Types ¶
type AbortWatcher ¶
type AbortWatcher struct {
// contains filtered or unexported fields
}
AbortWatcher trips when every interval in a sliding window exceeds a limit: the target has been failing for that long, not just for a blip. Intervals with no requests neither trip nor reset it.
func NewAbortWatcher ¶
func NewAbortWatcher(a *scenario.Abort, floor *scenario.Abort, interval time.Duration) *AbortWatcher
NewAbortWatcher builds a watcher from a scenario's abort block, falling back to floor (the server's default) for limits the scenario leaves out. It returns nil when no limit applies.
type BreakpointTracker ¶
type BreakpointTracker struct {
// contains filtered or unexported fields
}
BreakpointTracker evaluates targets at the end of each hold stage of a breakpoint plan and reports when a level fails. Feed it merged snapshots in interval order.
func NewBreakpointTracker ¶
func NewBreakpointTracker(prog *scenario.Program, plan *scenario.Plan) *BreakpointTracker
NewBreakpointTracker builds a tracker for a breakpoint plan.
func (*BreakpointTracker) Observe ¶
func (b *BreakpointTracker) Observe(s *metrics.Snapshot) bool
Observe adds an interval and returns true once a level has failed.
func (*BreakpointTracker) Result ¶
func (b *BreakpointTracker) Result() *report.Breakpoint
Result summarises the search so far.
type DistributedOptions ¶
type DistributedOptions struct {
Coordinator *coordinator.Coordinator
// Spec is the run to start. Spec.AllowHosts should name the verified
// target host when it is public; private hosts are always allowed.
Spec coordinator.RunSpec
Logger *slog.Logger
// Progress receives each merged interval for live display.
Progress func(Progress)
// OnEvent receives run events: workers joining, saturating, being
// lost, finishing.
OnEvent func(coordinator.RunEvent)
// AbortFloor stops runs that fail badly even when the scenario sets no
// abort limits.
AbortFloor *scenario.Abort
// OnStart receives the run once every worker accepted it, so the
// caller can Stop or Kill it.
OnStart func(*coordinator.Run)
}
DistributedOptions configures a run across workers.
type FaultPlan ¶
FaultPlan is a scenario's fault timeline with a client for the agent that injects it.
type FaultRun ¶
type FaultRun struct {
// contains filtered or unexported fields
}
FaultRun applies a plan's steps on time during one run.
type Options ¶
type Options struct {
Scenario *scenario.Scenario
RunID string
Env map[string]string
Secrets map[string]string
AllowHost func(*url.URL) bool
Logger *slog.Logger
// Progress receives each interval's merged snapshot for live display.
Progress func(p Progress)
// Faults, when set, injects the scenario's fault timeline through a
// stampede agent during the run. It is checked before any load.
Faults *FaultPlan
}
Options configures a local run.
type Progress ¶
type Progress struct {
Elapsed time.Duration
Total time.Duration
Snapshot *metrics.Snapshot
Planned float64
Mode string
}
Progress is a live update.
type Round ¶
Round runs one confirmation hold at level and reports whether every target held, and which failed if not.
type SelfMonitor ¶
type SelfMonitor struct {
// contains filtered or unexported fields
}
SelfMonitor watches the machine running an in-process engine (`stampede run`, or the server running load itself), as workers watch themselves, so a report can say when the generator rather than the target was the limit.
func NewSelfMonitor ¶
func NewSelfMonitor() *SelfMonitor
NewSelfMonitor starts sampling the process once a second; Close stops it.
func (*SelfMonitor) Annotate ¶
func (m *SelfMonitor) Annotate(rep *report.Report, interval time.Duration)
Annotate, when the generator was saturated, adds it as the report's one worker with its saturated windows, and the same notes and verdict a distributed run gets. A healthy run's report is unchanged.
func (*SelfMonitor) Latest ¶
func (m *SelfMonitor) Latest() (wire.Health, time.Time)
Latest is the most recent health sample and when it was taken; the time is zero before the first interval.
func (*SelfMonitor) Observe ¶
func (m *SelfMonitor) Observe(s *metrics.Snapshot)
Observe takes each interval's snapshot, in order.