vegeta

package
v12.8.6 Latest Latest
Warning

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

 Go to latest Published: May 17, 2022 License: MIT Imports: 30 Imported by: 0

Documentation

Index

Constants

View Source 
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
	// DefaultMaxConnections is the default amount of connections per target
	// host.
	DefaultMaxConnections = 0
	// 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
)
View Source 
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
)
View Source 
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

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

Functions

func ChunkedBody 

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 

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

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

func Connections 

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 

func H2C(enabled bool) func(*Attacker)

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

func HTTP2 

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 

func KeepAlive(keepalive bool) func(*Attacker)

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

func LocalAddr 

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 

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 MaxConnections 

func MaxConnections(n int) func(*Attacker)

MaxConnections returns a functional option which sets the number of maximum connections per target host.

func MaxWorkers 

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 

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 

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

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

func Redirects 

func Redirects(n int) func(*Attacker)

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

func TLSConfig 

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 

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 

func UnixSocket(socket string) func(*Attacker)

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

func Workers 

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.

Types

type Attacker 

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

Attacker is an attack executor which wraps an http.Client

func NewAttacker 

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 

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 

func (a *Attacker) Stop()

Stop stops the current attack.

type Buckets 

type Buckets []time.Duration

Buckets represents an Histogram's latency buckets.

func (Buckets) Nth 

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

Nth returns the nth bucket represented as a string.

func (*Buckets) UnmarshalText 

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

UnmarshalText implements the encoding.TextUnmarshaler interface.

type ByteMetrics 

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 

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

Closer wraps the optional Report Close method.

type ConstantPacer 

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 

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

func (cp ConstantPacer) Rate(elapsed time.Duration) float64

Rate returns a ConstantPacer's instantaneous hit rate (i.e. requests per second) at the given elapsed duration of an attack. Since it's constant, the return value is independent of the given elapsed duration.

func (ConstantPacer) String 

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 

type Decoder func(*Result) error

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

func DecoderFor 

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 

func NewCSVDecoder(r io.Reader) Decoder

NewCSVDecoder returns a Decoder that decodes CSV encoded Results.

func NewDecoder 

func NewDecoder(rd io.Reader) Decoder

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

func NewJSONDecoder 

func NewJSONDecoder(r io.Reader) Decoder

NewJSONDecoder returns a Decoder that decodes JSON encoded Results.

func NewRoundRobinDecoder 

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 

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

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

type DecoderFactory 

type DecoderFactory func(io.Reader) Decoder

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

type Encoder 

type Encoder func(*Result) error

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

func NewCSVEncoder 

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 

func NewEncoder(r io.Writer) Encoder

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

func NewJSONEncoder 

func NewJSONEncoder(w io.Writer) Encoder

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

func (Encoder) Encode 

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

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

type Histogram 

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

Histogram is a bucketed latency Histogram.

func (*Histogram) Add 

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 

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

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

type LatencyMetrics 

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"`
	// Min is the minimum observed request latency.
	Min time.Duration `json:"min"`
	// contains filtered or unexported fields
}

LatencyMetrics holds computed request latency metrics.

func (*LatencyMetrics) Add 

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

Add adds the given latency to the latency metrics.

func (LatencyMetrics) Quantile 

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

Quantile returns the nth quantile from the latency summary.

type LinearPacer 

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 

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.

func (LinearPacer) Rate 

func (p LinearPacer) Rate(elapsed time.Duration) float64

Rate returns a LinearPacer's instantaneous hit rate (i.e. requests per second) at the given elapsed duration of an attack.

type Metrics 

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 

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 

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 

type Pacer interface {
	// Pace returns the duration an Attacker should wait until
	// hitting the next Target, given an already elapsed duration and
	// completed hits. If the second return value is true, an attacker
	// should stop sending hits.
	Pace(elapsed time.Duration, hits uint64) (wait time.Duration, stop bool)

	// Rate returns a Pacer's instantaneous hit rate (per seconds)
	// at the given elapsed duration of an attack.
	Rate(elapsed time.Duration) float64
}

A Pacer defines the rate of hits during an Attack.

type PacerFunc 

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

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

func (PacerFunc) Pace 

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

Pace implements the Pacer interface.

type Rate 

type Rate = ConstantPacer

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

type Report 

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 

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 

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 

func NewHistogramReporter(h *Histogram) Reporter

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

func NewJSONReporter 

func NewJSONReporter(m *Metrics) Reporter

NewJSONReporter returns a Reporter that writes out Metrics as JSON.

func NewTextReporter 

func NewTextReporter(m *Metrics) Reporter

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

func (Reporter) Report 

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

Report is a convenience method wrapping the Reporter function type.

type Result 

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"`
	Headers   http.Header   `json:"headers"`
}

Result contains the results of a single Target hit.

func (*Result) End 

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

End returns the time at which a Result ended.

func (Result) Equal 

func (r Result) Equal(other Result) bool

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

type Results 

type Results []Result

Results is a slice of Result type elements.

func (*Results) Add 

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 

func (rs *Results) Close()

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

func (Results) Len 

func (rs Results) Len() int

The following methods implement sort.Interface

func (Results) Less 

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

func (Results) Swap 

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

type SinePacer 

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 

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

func (sp SinePacer) Rate(elapsed time.Duration) float64

Rate returns a SinePacer's instantaneous hit rate (i.e. requests per second) at the given elapsed duration of an attack.

func (SinePacer) String 

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 

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.

func ReadAllTargets 

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

ReadAllTargets eagerly reads all Targets out of the provided Targeter.

func (*Target) Equal 

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

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

func (*Target) Request 

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 

type TargetEncoder func(*Target) error

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

func NewJSONTargetEncoder 

func NewJSONTargetEncoder(w io.Writer) TargetEncoder

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

func (TargetEncoder) Encode 

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

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

type Targeter 

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 

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 

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 

func NewStaticTargeter(tgts ...Target) Targeter

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

func (Targeter) Decode 

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

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

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.