periodic

Documentation

Overview

Package periodic for fortio (from greek for load) is a set of utilities to run a given task at a target rate (qps) and gather statistics - for instance http requests.

The main executable using the library is fortio but there is also ../histogram to use the stats from the command line and ../echosrv as a very light http server that can be used to test proxies etc like the Istio components.

Index

• Variables
• type Aborter
  • func NewAborter() *Aborter
  • func (a *Aborter) Abort()
• type HasRunnerResult
• type PeriodicRunner
  • func NewPeriodicRunner(params *RunnerOptions) PeriodicRunner
• type Runnable
• type RunnerOptions
  • func (r *RunnerOptions) Abort()
  • func (r *RunnerOptions) MakeRunners(rr Runnable)
  • func (r *RunnerOptions) Normalize()
  • func (r *RunnerOptions) ReleaseRunners()
• type RunnerResults
  • func (r *RunnerResults) ID() string
  • func (r *RunnerResults) Result() *RunnerResults

Variables

var DefaultRunnerOptions = RunnerOptions{
	QPS:         8,
	Duration:    5 * time.Second,
	NumThreads:  4,
	Percentiles: []float64{90.0},
	Resolution:  0.001,
}

DefaultRunnerOptions are the default values for options (do not mutate!). This is only useful for initializing flag default values. You do not need to use this directly, you can pass a newly created RunnerOptions and 0 valued fields will be reset to these defaults.

Types

type Aborter

type Aborter struct {
	sync.Mutex
	StopChan chan struct{}
}

Aborter is the object controlling Abort() of the runs.

func NewAborter

func NewAborter() *Aborter

NewAborter makes a new Aborter and initialize its StopChan. The pointer should be shared. The structure is NoCopy.

func (*Aborter) Abort

func (a *Aborter) Abort()

Abort signals all the go routine of this run to stop. Implemented by closing the shared channel. The lock is to make sure we close it exactly once to avoid go panic.

type HasRunnerResult

type HasRunnerResult interface {
	Result() *RunnerResults
}

HasRunnerResult is the interface implictly implemented by HTTPRunnerResults and GrpcRunnerResults so the common results can ge extracted irrespective of the type.

type PeriodicRunner

type PeriodicRunner interface {
	// Starts the run. Returns actual QPS and Histogram of function durations.
	Run() RunnerResults
	// Returns the options normalized by constructor - do not mutate
	// (where is const when you need it...)
	Options() *RunnerOptions
}

PeriodicRunner let's you exercise the Function at the given QPS and collect statistics and histogram about the run.

func NewPeriodicRunner

func NewPeriodicRunner(params *RunnerOptions) PeriodicRunner

NewPeriodicRunner constructs a runner from input parameters/options. The options will be moved and normalized to the returned object, do not use the original options after this call, call Options() instead. Abort() must be called if Run() is not called.

type Runnable

type Runnable interface {
	Run(tid int)
}

Runnable are the function to run periodically.

type RunnerOptions

type RunnerOptions struct {
	// Type of run (to be copied into results)
	RunType string
	// Array of objects to run in each thread (use MakeRunners() to clone the same one)
	Runners []Runnable
	// At which (target) rate to run the Runners across NumThreads.
	QPS float64
	// How long to run the test for. Unless Exactly is specified.
	Duration time.Duration
	// Note that this actually maps to gorountines and not actual threads
	// but threads seems like a more familiar name to use for non go users
	// and in a benchmarking context
	NumThreads  int
	Percentiles []float64
	Resolution  float64
	// Where to write the textual version of the results, defaults to stdout
	Out io.Writer
	// Extra data to be copied back to the results (to be saved/JSON serialized)
	Labels string
	// Aborter to interrupt a run. Will be created if not set/left nil. Or you
	// can pass your own. It is very important this is a pointer and not a field
	// as RunnerOptions themselves get copied while the channel and lock must
	// stay unique (per run).
	Stop *Aborter
	// Mode where an exact number of iterations is requested. Default (0) is
	// to not use that mode. If specified Duration is not used.
	Exactly int64
	// When multiple clients are used to generate requests, they tend to send
	// requests very close to one another, causing a thundering herd problem
	// Enabling jitter (+/-10%) allows these requests to be de-synchronized
	// When enabled, it is only effective in the '-qps' mode.
	Jitter bool
	// Optional run id; used by the server to identify runs.
	RunID int64
}

RunnerOptions are the parameters to the PeriodicRunner.

func (*RunnerOptions) Abort

func (r *RunnerOptions) Abort()

Abort safely aborts the run by closing the channel and resetting that channel to nil under lock so it can be called multiple times and not create panic for already closed channel.

func (*RunnerOptions) MakeRunners

func (r *RunnerOptions) MakeRunners(rr Runnable)

MakeRunners creates an array of NumThreads identical Runnable instances (for the (rare/test) cases where there is no unique state needed).

func (*RunnerOptions) Normalize

func (r *RunnerOptions) Normalize()

Normalize initializes and normalizes the runner options. In particular it sets up the channel that can be used to interrupt the run later. Once Normalize is called, if Run() is skipped, Abort() must be called to cleanup the watchers.

func (*RunnerOptions) ReleaseRunners

func (r *RunnerOptions) ReleaseRunners()

ReleaseRunners clear the runners state.

type RunnerResults

type RunnerResults struct {
	RunType           string
	Labels            string
	StartTime         time.Time
	RequestedQPS      string
	RequestedDuration string // String version of the requested duration or exact count
	ActualQPS         float64
	ActualDuration    time.Duration
	NumThreads        int
	Version           string
	DurationHistogram *stats.HistogramData
	Exactly           int64 // Echo back the requested count
	Jitter            bool
	RunID             int64 // Echo back the optional run id.
}

RunnerResults encapsulates the actual QPS observed and duration histogram.

func (*RunnerResults) ID

func (r *RunnerResults) ID() string

ID Returns an id for the result: 96 bytes YYYY-MM-DD-HHmmSS_{RunID}_{alpha_labels} where RunID is the RunID if not 0. where alpha_labels is the filtered labels with only alphanumeric characters and all non alpha num replaced by _; truncated to 96 bytes.

func (*RunnerResults) Result

func (r *RunnerResults) Result() *RunnerResults

Result returns the common RunnerResults.