vegeta: github.com/tsenart/vegeta/lib Index | Files | Directories

package vegeta

import "github.com/tsenart/vegeta/lib"

Index

Package Files

attack.go histogram.go metrics.go pacer.go reporters.go results.go results_easyjson.go targets.go targets_easyjson.go

Constants

const (
    // DefaultRedirects is the default number of times an Attacker follows
    // redirects.
    DefaultRedirects = 10
    // DefaultTimeout is the default amount of time an Attacker waits for a request
    // before it times out.
    DefaultTimeout = 30 * time.Second
    // DefaultConnections is the default amount of max open idle connections per
    // target host.
    DefaultConnections = 10000
    // DefaultWorkers is the default initial number of workers used to carry an attack.
    DefaultWorkers = 10
    // DefaultMaxWorkers is the default maximum number of workers used to carry an attack.
    DefaultMaxWorkers = math.MaxUint64
    // DefaultMaxBody is the default max number of bytes to be read from response bodies.
    // Defaults to no limit.
    DefaultMaxBody = int64(-1)
    // NoFollow is the value when redirects are not followed but marked successful
    NoFollow = -1
)
const (
    // MeanUp is a SinePacer Offset that causes the attack to start
    // at the Mean attack rate and increase towards the peak.
    MeanUp float64 = 0
    // Peak is a SinePacer Offset that causes the attack to start
    // at the peak (maximum) attack rate and decrease towards the Mean.
    Peak = math.Pi / 2
    // MeanDown is a SinePacer Offset that causes the attack to start
    // at the Mean attack rate and decrease towards the trough.
    MeanDown = math.Pi
    // Trough is a SinePacer Offset that causes the attack to start
    // at the trough (minimum) attack rate and increase towards the Mean.
    Trough = 3 * math.Pi / 2
)
const (
    // HTTPTargetFormat is the human readable identifier for the HTTP target format.
    HTTPTargetFormat = "http"
    // JSONTargetFormat is the human readable identifier for the JSON target format.
    JSONTargetFormat = "json"
)

Variables

var (
    // DefaultLocalAddr is the default local IP address an Attacker uses.
    DefaultLocalAddr = net.IPAddr{IP: net.IPv4zero}
    // DefaultTLSConfig is the default tls.Config an Attacker uses.
    DefaultTLSConfig = &tls.Config{InsecureSkipVerify: true}
)
var (
    // ErrNoTargets is returned when not enough Targets are available.
    ErrNoTargets = errors.New("no targets to attack")
    // ErrNilTarget is returned when the passed Target pointer is nil.
    ErrNilTarget = errors.New("nil target")
    // ErrNoMethod is returned by JSONTargeter when a parsed Target has
    // no method.
    ErrNoMethod = errors.New("target: required method is missing")
    // ErrNoURL is returned by JSONTargeter when a parsed Target has no
    // URL.
    ErrNoURL = errors.New("target: required url is missing")
    // TargetFormats contains the canonical list of the valid target
    // format identifiers.
    TargetFormats = []string{HTTPTargetFormat, JSONTargetFormat}
)

func ChunkedBody Uses

func ChunkedBody(b bool) func(*Attacker)

ChunkedBody returns a functional option which makes the attacker send the body of each request with the chunked transfer encoding.

func Client Uses

func Client(c *http.Client) func(*Attacker)

Client returns a functional option that allows you to bring your own http.Client

func Connections Uses

func Connections(n int) func(*Attacker)

Connections returns a functional option which sets the number of maximum idle open connections per target host.

func H2C Uses

func H2C(enabled bool) func(*Attacker)

H2C returns a functional option which enables H2C support on requests performed by an Attacker

func HTTP2 Uses

func HTTP2(enabled bool) func(*Attacker)

HTTP2 returns a functional option which enables or disables HTTP/2 support on requests performed by an Attacker.

func KeepAlive Uses

func KeepAlive(keepalive bool) func(*Attacker)

KeepAlive returns a functional option which toggles KeepAlive connections on the dialer and transport.

func LocalAddr Uses

func LocalAddr(addr net.IPAddr) func(*Attacker)

LocalAddr returns a functional option which sets the local address an Attacker will use with its requests.

func MaxBody Uses

func MaxBody(n int64) func(*Attacker)

MaxBody returns a functional option which limits the max number of bytes read from response bodies. Set to -1 to disable any limits.

func MaxWorkers Uses

func MaxWorkers(n uint64) func(*Attacker)

MaxWorkers returns a functional option which sets the maximum number of workers an Attacker can use to hit its targets.

func Proxy Uses

func Proxy(proxy func(*http.Request) (*url.URL, error)) func(*Attacker)

Proxy returns a functional option which sets the `Proxy` field on the http.Client's Transport

func ProxyHeader Uses

func ProxyHeader(h http.Header) func(*Attacker)

ProxyHeader returns a functional option that allows you to add your own Proxy CONNECT headers

func Redirects Uses

func Redirects(n int) func(*Attacker)

Redirects returns a functional option which sets the maximum number of redirects an Attacker will follow.

func TLSConfig Uses

func TLSConfig(c *tls.Config) func(*Attacker)

TLSConfig returns a functional option which sets the *tls.Config for a Attacker to use with its requests.

func Timeout Uses

func Timeout(d time.Duration) func(*Attacker)

Timeout returns a functional option which sets the maximum amount of time an Attacker will wait for a request to be responded to and completely read.

func UnixSocket Uses

func UnixSocket(socket string) func(*Attacker)

UnixSocket changes the dialer for the attacker to use the specified unix socket file

func Workers Uses

func Workers(n uint64) func(*Attacker)

Workers returns a functional option which sets the initial number of workers an Attacker uses to hit its targets. More workers may be spawned dynamically to sustain the requested rate in the face of slow responses and errors.

type Attacker Uses

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

Attacker is an attack executor which wraps an http.Client

func NewAttacker Uses

func NewAttacker(opts ...func(*Attacker)) *Attacker

NewAttacker returns a new Attacker with default options which are overridden by the optionally provided opts.

func (*Attacker) Attack Uses

func (a *Attacker) Attack(tr Targeter, p Pacer, du time.Duration, name string) <-chan *Result

Attack reads its Targets from the passed Targeter and attacks them at the rate specified by the Pacer. When the duration is zero the attack runs until Stop is called. Results are sent to the returned channel as soon as they arrive and will have their Attack field set to the given name.

func (*Attacker) Stop Uses

func (a *Attacker) Stop()

Stop stops the current attack.

type Buckets Uses

type Buckets []time.Duration

Buckets represents an Histogram's latency buckets.

func (Buckets) Nth Uses

func (bs Buckets) Nth(i int) (left, right string)

Nth returns the nth bucket represented as a string.

func (*Buckets) UnmarshalText Uses

func (bs *Buckets) UnmarshalText(value []byte) error

UnmarshalText implements the encoding.TextUnmarshaler interface.

type ByteMetrics Uses

type ByteMetrics struct {
    // Total is the total number of flowing bytes in an attack.
    Total uint64 `json:"total"`
    // Mean is the mean number of flowing bytes per hit.
    Mean float64 `json:"mean"`
}

ByteMetrics holds computed byte flow metrics.

type Closer Uses

type Closer interface {
    // Close permantently closes a Report, running any necessary book keeping.
    Close()
}

Closer wraps the optional Report Close method.

type ConstantPacer Uses

type ConstantPacer struct {
    Freq int           // Frequency (number of occurrences) per ...
    Per  time.Duration // Time unit, usually 1s
}

A ConstantPacer defines a constant rate of hits for the target.

func (ConstantPacer) Pace Uses

func (cp ConstantPacer) Pace(elapsed time.Duration, hits uint64) (time.Duration, bool)

Pace determines the length of time to sleep until the next hit is sent.

func (ConstantPacer) String Uses

func (cp ConstantPacer) String() string

String returns a pretty-printed description of the ConstantPacer's behaviour:

ConstantPacer{Freq: 1, Per: time.Second} => Constant{1 hits/1s}

type Decoder Uses

type Decoder func(*Result) error

A Decoder decodes a Result and returns an error in case of failure.

func DecoderFor Uses

func DecoderFor(r io.Reader) Decoder

DecoderFor automatically detects the encoding of the first few bytes in the given io.Reader and then returns the corresponding Decoder or nil in case of failing to detect a supported encoding.

func NewCSVDecoder Uses

func NewCSVDecoder(r io.Reader) Decoder

NewCSVDecoder returns a Decoder that decodes CSV encoded Results.

func NewDecoder Uses

func NewDecoder(rd io.Reader) Decoder

NewDecoder returns a new gob Decoder for the given io.Reader.

func NewJSONDecoder Uses

func NewJSONDecoder(r io.Reader) Decoder

NewJSONDecoder returns a Decoder that decodes JSON encoded Results.

func NewRoundRobinDecoder Uses

func NewRoundRobinDecoder(dec ...Decoder) Decoder

NewRoundRobinDecoder returns a new Decoder that round robins across the given Decoders on every invocation or decoding error.

func (Decoder) Decode Uses

func (dec Decoder) Decode(r *Result) error

Decode is an an adapter method calling the Decoder function itself with the given parameters.

type DecoderFactory Uses

type DecoderFactory func(io.Reader) Decoder

A DecoderFactory constructs a new Decoder from a given io.Reader.

type Encoder Uses

type Encoder func(*Result) error

An Encoder encodes a Result and returns an error in case of failure.

func NewCSVEncoder Uses

func NewCSVEncoder(w io.Writer) Encoder

NewCSVEncoder returns an Encoder that dumps the given *Result as a CSV record. The columns are: UNIX timestamp in ns since epoch, HTTP status code, request latency in ns, bytes out, bytes in, response body, and lastly the error.

func NewEncoder Uses

func NewEncoder(r io.Writer) Encoder

NewEncoder returns a new Result encoder closure for the given io.Writer

func NewJSONEncoder Uses

func NewJSONEncoder(w io.Writer) Encoder

NewJSONEncoder returns an Encoder that dumps the given *Results as a JSON object.

func (Encoder) Encode Uses

func (enc Encoder) Encode(r *Result) error

Encode is an an adapter method calling the Encoder function itself with the given parameters.

type Histogram Uses

type Histogram struct {
    Buckets Buckets
    Counts  []uint64
    Total   uint64
}

Histogram is a bucketed latency Histogram.

func (*Histogram) Add Uses

func (h *Histogram) Add(r *Result)

Add implements the Add method of the Report interface by finding the right Bucket for the given Result latency and increasing its count by one as well as the total count.

func (*Histogram) MarshalJSON Uses

func (h *Histogram) MarshalJSON() ([]byte, error)

MarshalJSON returns a JSON encoding of the buckets and their counts.

type LatencyMetrics Uses

type LatencyMetrics struct {
    // Total is the total latency sum of all requests in an attack.
    Total time.Duration `json:"total"`
    // Mean is the mean request latency.
    Mean time.Duration `json:"mean"`
    // P50 is the 50th percentile request latency.
    P50 time.Duration `json:"50th"`
    // P90 is the 90th percentile request latency.
    P90 time.Duration `json:"90th"`
    // P95 is the 95th percentile request latency.
    P95 time.Duration `json:"95th"`
    // P99 is the 99th percentile request latency.
    P99 time.Duration `json:"99th"`
    // Max is the maximum observed request latency.
    Max time.Duration `json:"max"`
    // contains filtered or unexported fields
}

LatencyMetrics holds computed request latency metrics.

func (*LatencyMetrics) Add Uses

func (l *LatencyMetrics) Add(latency time.Duration)

Add adds the given latency to the latency metrics.

func (LatencyMetrics) Quantile Uses

func (l LatencyMetrics) Quantile(nth float64) time.Duration

Quantile returns the nth quantile from the latency summary.

type LinearPacer Uses

type LinearPacer struct {
    StartAt Rate
    Slope   float64
}

LinearPacer paces an attack by starting at a given request rate and increasing linearly with the given slope.

func (LinearPacer) Pace Uses

func (p LinearPacer) Pace(elapsed time.Duration, hits uint64) (time.Duration, bool)

Pace determines the length of time to sleep until the next hit is sent.

type Metrics Uses

type Metrics struct {
    // Latencies holds computed request latency metrics.
    Latencies LatencyMetrics `json:"latencies"`
    // Histogram, only if requested
    Histogram *Histogram `json:"buckets,omitempty"`
    // BytesIn holds computed incoming byte metrics.
    BytesIn ByteMetrics `json:"bytes_in"`
    // BytesOut holds computed outgoing byte metrics.
    BytesOut ByteMetrics `json:"bytes_out"`
    // Earliest is the earliest timestamp in a Result set.
    Earliest time.Time `json:"earliest"`
    // Latest is the latest timestamp in a Result set.
    Latest time.Time `json:"latest"`
    // End is the latest timestamp in a Result set plus its latency.
    End time.Time `json:"end"`
    // Duration is the duration of the attack.
    Duration time.Duration `json:"duration"`
    // Wait is the extra time waiting for responses from targets.
    Wait time.Duration `json:"wait"`
    // Requests is the total number of requests executed.
    Requests uint64 `json:"requests"`
    // Rate is the rate of sent requests per second.
    Rate float64 `json:"rate"`
    // Throughput is the rate of successful requests per second.
    Throughput float64 `json:"throughput"`
    // Success is the percentage of non-error responses.
    Success float64 `json:"success"`
    // StatusCodes is a histogram of the responses' status codes.
    StatusCodes map[string]int `json:"status_codes"`
    // Errors is a set of unique errors returned by the targets during the attack.
    Errors []string `json:"errors"`
    // contains filtered or unexported fields
}

Metrics holds metrics computed out of a slice of Results which are used in some of the Reporters

func (*Metrics) Add Uses

func (m *Metrics) Add(r *Result)

Add implements the Add method of the Report interface by adding the given Result to Metrics.

func (*Metrics) Close Uses

func (m *Metrics) Close()

Close implements the Close method of the Report interface by computing derived summary metrics which don't need to be run on every Add call.

type Pacer Uses

type Pacer interface {
    Pace(elapsed time.Duration, hits uint64) (wait time.Duration, stop bool)
}

A Pacer defines the rate of hits during an Attack by returning the duration an Attacker should wait until hitting the next Target. If the second return value is true, the attack will terminate.

type PacerFunc Uses

type PacerFunc func(time.Duration, uint64) (time.Duration, bool)

A PacerFunc is a function adapter type that implements the Pacer interface.

func (PacerFunc) Pace Uses

func (pf PacerFunc) Pace(elapsed time.Duration, hits uint64) (time.Duration, bool)

Pace implements the Pacer interface.

type Rate Uses

type Rate = ConstantPacer

Rate is a type alias for ConstantPacer for backwards-compatibility.

type Report Uses

type Report interface {
    // Add adds a given *Result to a Report.
    Add(*Result)
}

A Report represents the state a Reporter uses to write out its reports.

type Reporter Uses

type Reporter func(io.Writer) error

A Reporter function writes out reports to the given io.Writer or returns an error in case of failure.

func NewHDRHistogramPlotReporter Uses

func NewHDRHistogramPlotReporter(m *Metrics) Reporter

NewHDRHistogramPlotReporter returns a Reporter that writes out latency metrics in a format plottable by http://hdrhistogram.github.io/HdrHistogram/plotFiles.html.

func NewHistogramReporter Uses

func NewHistogramReporter(h *Histogram) Reporter

NewHistogramReporter returns a Reporter that writes out a Histogram as aligned, formatted text.

func NewJSONReporter Uses

func NewJSONReporter(m *Metrics) Reporter

NewJSONReporter returns a Reporter that writes out Metrics as JSON.

func NewTextReporter Uses

func NewTextReporter(m *Metrics) Reporter

NewTextReporter returns a Reporter that writes out Metrics as aligned, formatted text.

func (Reporter) Report Uses

func (rep Reporter) Report(w io.Writer) error

Report is a convenience method wrapping the Reporter function type.

type Result Uses

type Result struct {
    Attack    string        `json:"attack"`
    Seq       uint64        `json:"seq"`
    Code      uint16        `json:"code"`
    Timestamp time.Time     `json:"timestamp"`
    Latency   time.Duration `json:"latency"`
    BytesOut  uint64        `json:"bytes_out"`
    BytesIn   uint64        `json:"bytes_in"`
    Error     string        `json:"error"`
    Body      []byte        `json:"body"`
    Method    string        `json:"method"`
    URL       string        `json:"url"`
}

Result contains the results of a single Target hit.

func (*Result) End Uses

func (r *Result) End() time.Time

End returns the time at which a Result ended.

func (Result) Equal Uses

func (r Result) Equal(other Result) bool

Equal returns true if the given Result is equal to the receiver.

type Results Uses

type Results []Result

Results is a slice of Result type elements.

func (*Results) Add Uses

func (rs *Results) Add(r *Result)

Add implements the Add method of the Report interface by appending the given Result to the slice.

func (*Results) Close Uses

func (rs *Results) Close()

Close implements the Close method of the Report interface by sorting the Results.

func (Results) Len Uses

func (rs Results) Len() int

The following methods implement sort.Interface

func (Results) Less Uses

func (rs Results) Less(i, j int) bool

func (Results) Swap Uses

func (rs Results) Swap(i, j int)

type SinePacer Uses

type SinePacer struct {
    // The period of the sine wave, e.g. 20*time.Minute
    // MUST BE > 0
    Period time.Duration
    // The mid-point of the sine wave in freq-per-Duration,
    // MUST BE > 0
    Mean Rate
    // The amplitude of the sine wave in freq-per-Duration,
    // MUST NOT BE EQUAL TO OR LARGER THAN MEAN
    Amp Rate
    // The offset, in radians, for the sine wave at t=0.
    StartAt float64
}

SinePacer is a Pacer that describes attack request rates with the equation:

R = MA sin(O+(2𝛑/P)t)

Where:

R = Instantaneous attack rate at elapsed time t, hits per nanosecond
M = Mean attack rate over period P, sp.Mean, hits per nanosecond
A = Amplitude of sine wave, sp.Amp, hits per nanosecond
O = Offset of sine wave, sp.StartAt, radians
P = Period of sine wave, sp.Period, nanoseconds
t = Elapsed time since attack start, nanoseconds

Many thanks to http://ascii.co.uk/art/sine and "sps" for the ascii here :-)

Mean -|         ,-'''-.
+Amp  |      ,-'   |   `-.
      |    ,'      |      `.       O=𝛑
      |  ,'      O=𝛑/2      `.     MeanDown
      | /        Peak         \   /
      |/                       \ /
Mean -+-------------------------\--------------------------> t
      |\                         \                       /
      | \                         \       O=3𝛑/2        /
      |  O=0                       `.     Trough      ,'
      |  MeanUp                      `.      |      ,'
Mean  |                                `-.   |   ,-'
-Amp -|                                   `-,,,-'
      |<-------------------- Period --------------------->|

This equation is integrated with respect to time to derive the expected number of hits served at time t after the attack began:

H = Mt - (AP/2𝛑)cos(O+(2𝛑/P)t) + (AP/2𝛑)cos(O)

Where:

H = Total number of hits triggered during t

func (SinePacer) Pace Uses

func (sp SinePacer) Pace(elapsedTime time.Duration, elapsedHits uint64) (time.Duration, bool)

Pace determines the length of time to sleep until the next hit is sent.

func (SinePacer) String Uses

func (sp SinePacer) String() string

String returns a pretty-printed description of the SinePacer's behaviour:

SinePacer{
    Period:  time.Hour,
    Mean:    Rate{100, time.Second},
    Amp:     Rate{50, time.Second},
    StartAt: MeanDown,
} =>
Sine{Constant{100 hits/1s} ± Constant{50 hits/1s} / 1h, offset 1𝛑}

type Target Uses

type Target struct {
    Method string      `json:"method"`
    URL    string      `json:"url"`
    Body   []byte      `json:"body,omitempty"`
    Header http.Header `json:"header,omitempty"`
}

Target is an HTTP request blueprint.

go:generate go run ../internal/cmd/jsonschema/main.go -type=Target -output=target.schema.json

func ReadAllTargets Uses

func ReadAllTargets(t Targeter) (tgts []Target, err error)

ReadAllTargets eagerly reads all Targets out of the provided Targeter.

func (*Target) Equal Uses

func (t *Target) Equal(other *Target) bool

Equal returns true if the target is equal to the other given target.

func (*Target) Request Uses

func (t *Target) Request() (*http.Request, error)

Request creates an *http.Request out of Target and returns it along with an error in case of failure.

type TargetEncoder Uses

type TargetEncoder func(*Target) error

A TargetEncoder encodes a Target in a format that can be read by a Targeter.

func NewJSONTargetEncoder Uses

func NewJSONTargetEncoder(w io.Writer) TargetEncoder

NewJSONTargetEncoder returns a TargetEncoder that encods Targets in the JSON format.

func (TargetEncoder) Encode Uses

func (enc TargetEncoder) Encode(t *Target) error

Encode is a convenience method that calls the underlying TargetEncoder function.

type Targeter Uses

type Targeter func(*Target) error

A Targeter decodes a Target or returns an error in case of failure. Implementations must be safe for concurrent use.

func NewHTTPTargeter Uses

func NewHTTPTargeter(src io.Reader, body []byte, hdr http.Header) Targeter

NewHTTPTargeter returns a new Targeter that decodes one Target from the given io.Reader on every invocation. The format is as follows:

GET https://foo.bar/a/b/c
Header-X: 123
Header-Y: 321
@/path/to/body/file

POST https://foo.bar/b/c/a
Header-X: 123

body will be set as the Target's body if no body is provided. hdr will be merged with the each Target's headers.

func NewJSONTargeter Uses

func NewJSONTargeter(src io.Reader, body []byte, header http.Header) Targeter

NewJSONTargeter returns a new targeter that decodes one Target from the given io.Reader on every invocation. Each target is one JSON object in its own line.

The method and url fields are required. If present, the body field must be base64 encoded. The generated [JSON Schema](lib/target.schema.json) defines the format in detail.

{"method":"POST", "url":"https://goku/1", "header":{"Content-Type":["text/plain"], "body": "Rk9P"}
{"method":"GET",  "url":"https://goku/2"}

body will be set as the Target's body if no body is provided in each target definiton. hdr will be merged with the each Target's headers.

func NewStaticTargeter Uses

func NewStaticTargeter(tgts ...Target) Targeter

NewStaticTargeter returns a Targeter which round-robins over the passed Targets.

func (Targeter) Decode Uses

func (tr Targeter) Decode(t *Target) error

Decode is a convenience method that calls the underlying Targeter function.

Directories

PathSynopsis
lttb
plot

Package vegeta imports 29 packages (graph) and is imported by 72 packages. Updated 2019-11-03. Refresh now. Tools for package owners.