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 ¶
Constants ¶
This section is empty.
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.
Functions ¶
This section is empty.
Types ¶
type Aborter ¶ added in v0.6.8
type Aborter struct {
sync.Mutex
StopChan chan struct{}
StartChan chan bool // Used to signal actual start of the run. Also (re)used in rapi/ to signal completion of the Run().
// contains filtered or unexported fields
}
Aborter is the object controlling Abort() of the runs.
func NewAborter ¶ added in v0.6.8
func NewAborter() *Aborter
NewAborter makes a new Aborter and initialize its StopChan. The pointer should be shared. The structure is NoCopy.
func (*Aborter) Abort ¶ added in v0.6.8
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. If wait is true, waits for the run to be started before closing.
func (*Aborter) RecordStart ¶ added in v1.57.4
RecordStart records the start of the run. (used by httprunner in error cases to fake start so rapi stop and wait can work).
type AccessLogger ¶ added in v1.21.0
type AccessLogger interface {
// Start is called just before each Run(). Can be used to start tracing spans for instance.
// returns possibly updated context.
Start(ctx context.Context, threadID ThreadID, iter int64, startTime time.Time) context.Context
// Report is called just after each Run() to logs a single request.
Report(ctx context.Context, threadID ThreadID, iter int64, startTime time.Time, latency float64, status bool, details string)
Info() string
}
AccessLogger defines an interface to report a single request.
func NewFileAccessLogger ¶ added in v1.21.0
func NewFileAccessLogger(filePath, format string) (AccessLogger, error)
NewFileAccessLogger creates an AccessLogger that writes to the provided file in the provided format.
func NewFileAccessLoggerByType ¶ added in v1.21.0
func NewFileAccessLoggerByType(filePath string, accessType AccessLoggerType) (AccessLogger, error)
NewFileAccessLoggerByType creates an AccessLogger that writes to the file in the AccessLoggerType enum format.
type AccessLoggerType ¶ added in v1.21.0
type AccessLoggerType int
AccessLoggerType is the possible formats of the access logger (ACCESS_JSON or ACCESS_INFLUX).
const ( // AccessJSON for json format of access log: {"latency":%f,"timestamp":%d,"thread":%d}. AccessJSON AccessLoggerType = iota // AccessInflux of influx format of access log. // https://docs.influxdata.com/influxdb/v2.2/reference/syntax/line-protocol/ AccessInflux )
func (AccessLoggerType) String ¶ added in v1.21.0
func (t AccessLoggerType) String() string
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. You can also keep a pointer to the original Aborter and use it, if needed.
type Runnable ¶ added in v0.4.2
type Runnable interface {
// Run returns a boolean, true for normal/success, false otherwise.
// with details being an optional string that can be put in the access logs.
// Statistics are split into two sets.
Run(context.Context, ThreadID) (status bool, details string)
}
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 `json:"-"`
// 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
// List of percentiles to calculate.
Percentiles []float64
// Divider to apply to duration data in seconds. Defaults to 0.001 or 1 millisecond.
Resolution float64
// Where to write the textual version of the results, defaults to stdout
Out io.Writer `json:"-"`
// 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 `json:"-"`
// 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
// When multiple clients are used to generate requests, they tend to send
// requests very close to one another, causing a thundering herd problem
// Enabling uniform causes the requests between connections to be uniformly staggered.
// When enabled, it is only effective in the '-qps' mode.
Uniform bool
// Optional run id; used by the server to identify runs.
RunID int64
// Optional Offset Duration; to offset the histogram function duration
Offset time.Duration
// Optional AccessLogger to log every request made. See AddAccessLogger.
AccessLogger AccessLogger `json:"-"`
// No catch-up: if true we will do exactly the requested QPS and not try to catch up if the target is temporarily slow.
NoCatchUp bool
// Unique 96 character ID used as reference to saved json file. Created during Normalize().
ID string
// contains filtered or unexported fields
}
RunnerOptions are the parameters to the PeriodicRunner.
func (*RunnerOptions) Abort ¶ added in v0.5.2
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) AddAccessLogger ¶ added in v1.21.0
func (r *RunnerOptions) AddAccessLogger(filePath, format string) error
AddAccessLogger adds an AccessLogger that writes to the provided file in the provided format.
func (*RunnerOptions) GenID ¶ added in v1.35.0
func (r *RunnerOptions) GenID()
GenID creates and set the 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 (*RunnerOptions) MakeRunners ¶ added in v0.4.2
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 ¶ added in v0.5.2
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 ¶ added in v0.8.0
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 all the Run. If you want to exclude the error cases; subtract ErrorsDurationHistogram to each bucket.
DurationHistogram *stats.HistogramData
// ErrorsDurationHistogram is the durations of the error (Run returning false) cases.
ErrorsDurationHistogram *stats.HistogramData
Exactly int64 // Echo back the requested count
Jitter bool
Uniform bool
NoCatchUp bool
RunID int64 // Echo back the optional run id
AccessLoggerInfo string
// Same as RunnerOptions ID: Unique 96 character ID used as reference to saved json file. Created during Normalize().
ID string
// If the run doesn't even start because of for instance an invalid host name, this will be set (all omitted on success)
jrpc.ServerReply
}
RunnerResults encapsulates the actual QPS observed and duration histogram.
func (*RunnerResults) Result ¶
func (r *RunnerResults) Result() *RunnerResults
Result returns the common RunnerResults.
Source Files