runner

package
v1.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 7, 2026 License: Apache-2.0 Imports: 21 Imported by: 0

Documentation

Overview

Package runner runs a scenario in-process (no server or database) and produces a report. It backs `stampede run`.

Index

Constants

View Source
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

View Source
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

func Refine(ctx context.Context, bp *report.Breakpoint, mode string, rounds int, run Round) error

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 Run

func Run(ctx context.Context, o Options) (*report.Report, error)

Run executes the scenario and returns its report.

func RunDistributed

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.

func (*AbortWatcher) Observe

func (w *AbortWatcher) Observe(s *metrics.Snapshot) string

Observe adds an interval and returns a stop reason once the abort trips.

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

type FaultPlan struct {
	Client *agent.Client
	Steps  []scenario.FaultStep
}

FaultPlan is a scenario's fault timeline with a client for the agent that injects it.

func (*FaultPlan) Check

func (p *FaultPlan) Check(ctx context.Context) error

Check asks the agent whether it can carry out every step, so a run with an unreachable agent, a missing proxy or a missing permission fails before any load is sent.

func (*FaultPlan) Start

func (p *FaultPlan) Start(ctx context.Context, t0 time.Time, runID string, log *slog.Logger) *FaultRun

Start applies each step at t0 plus its offset. t0 may be in the future (a distributed run starts a few seconds after it is scheduled).

type FaultRun

type FaultRun struct {
	// contains filtered or unexported fields
}

FaultRun applies a plan's steps on time during one run.

func (*FaultRun) Stop

func (fr *FaultRun) Stop(end time.Time) []report.FaultEvent

Stop cancels faults not yet started, clears every fault of the run on the agent and returns what happened, in start order. Faults that would have outlasted the run end when it ends.

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

type Round func(ctx context.Context, level float64) (pass bool, failedOn []string, err error)

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) Close

func (m *SelfMonitor) Close()

Close stops sampling.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL