lib

package
v0.0.0-...-6202178 Latest Latest
Warning

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

 Go to latest Published: Aug 24, 2023 License: AGPL-3.0 Imports: 38 Imported by: 0

Documentation

Overview

Package lib is a kitchen sink of... basically anything that doesn't belong in a specific part of the codebase, ranging from utility functions to universal types to core interfaces.

Some of the things in lib do not actually belong in lib, and need to be moved into either submodules, or separate modules like core. Other things are in files that are far too long, or that do not actually make sense.

Feel free to move these things.

Index

Constants

View Source 
const DefaultScenarioName = "default"

DefaultScenarioName is used as the default key/ID of the scenario config entries that were created due to the use of the shortcut execution control options (i.e. duration+vus, iterations+vus, or stages)

View Source 
const GroupSeparator = "::"

Separator for group IDs.

View Source 
const MaxRetriesGetPlannedVU = 5

MaxRetriesGetPlannedVU how many times we should wait for MaxTimeToWaitForPlannedVU before we actually return an error.

View Source 
const MaxTimeToWaitForPlannedVU = 400 * time.Millisecond

MaxTimeToWaitForPlannedVU specifies the maximum allowable time for an executor to wait for a planned VU to be retrieved from the ExecutionState.PlannedVUs buffer. If it's exceeded, k6 will emit a warning log message, since it either means that there's a bug in the k6 scheduling code, or that the machine is overloaded and the scheduling code suffers from delays.

Critically, exceeding this time *doesn't* result in an aborted test or any test errors, and the executor will continue to try and borrow the VU (potentially resulting in further warnings). We likely should emit a k6 metric about it in the future. TODO: emit a metric every time this is exceeded?

Variables

View Source 
var DefaultSummaryTrendStats = []string{"avg", "min", "med", "max", "p(90)", "p(95)"}

DefaultSummaryTrendStats are the default trend columns shown in the test summary output

View Source 
var ErrNameContainsGroupSeparator = errors.New("group and check names may not contain '::'")

Error emitted if you attempt to instantiate a Group or Check that contains the separator.

View Source 
var SupportedTLSCipherSuites = map[string]uint16{

	"TLS_RSA_WITH_RC4_128_SHA":                tls.TLS_RSA_WITH_RC4_128_SHA,
	"TLS_RSA_WITH_3DES_EDE_CBC_SHA":           tls.TLS_RSA_WITH_3DES_EDE_CBC_SHA,
	"TLS_RSA_WITH_AES_128_CBC_SHA":            tls.TLS_RSA_WITH_AES_128_CBC_SHA,
	"TLS_RSA_WITH_AES_256_CBC_SHA":            tls.TLS_RSA_WITH_AES_256_CBC_SHA,
	"TLS_RSA_WITH_AES_128_CBC_SHA256":         tls.TLS_RSA_WITH_AES_128_CBC_SHA256,
	"TLS_RSA_WITH_AES_128_GCM_SHA256":         tls.TLS_RSA_WITH_AES_128_GCM_SHA256,
	"TLS_RSA_WITH_AES_256_GCM_SHA384":         tls.TLS_RSA_WITH_AES_256_GCM_SHA384,
	"TLS_ECDHE_ECDSA_WITH_RC4_128_SHA":        tls.TLS_ECDHE_ECDSA_WITH_RC4_128_SHA,
	"TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA":    tls.TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,
	"TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA":    tls.TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA,
	"TLS_ECDHE_RSA_WITH_RC4_128_SHA":          tls.TLS_ECDHE_RSA_WITH_RC4_128_SHA,
	"TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA":     tls.TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA,
	"TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA":      tls.TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,
	"TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA":      tls.TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,
	"TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256":   tls.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
	"TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256": tls.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
	"TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384":   tls.TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
	"TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384": tls.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
	"TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256": tls.TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256,
	"TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305":    tls.TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,
	"TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305":  tls.TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,
	"TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256":   tls.TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,

	"TLS_AES_128_GCM_SHA256":       tls.TLS_AES_128_GCM_SHA256,
	"TLS_AES_256_GCM_SHA384":       tls.TLS_AES_256_GCM_SHA384,
	"TLS_CHACHA20_POLY1305_SHA256": tls.TLS_CHACHA20_POLY1305_SHA256,
}

SupportedTLSCipherSuites is string-to-constant map of available TLS cipher suites.

View Source 
var SupportedTLSCipherSuitesToString = map[uint16]string{
	tls.TLS_RSA_WITH_RC4_128_SHA:                "TLS_RSA_WITH_RC4_128_SHA",
	tls.TLS_RSA_WITH_3DES_EDE_CBC_SHA:           "TLS_RSA_WITH_3DES_EDE_CBC_SHA",
	tls.TLS_RSA_WITH_AES_128_CBC_SHA:            "TLS_RSA_WITH_AES_128_CBC_SHA",
	tls.TLS_RSA_WITH_AES_256_CBC_SHA:            "TLS_RSA_WITH_AES_256_CBC_SHA",
	tls.TLS_RSA_WITH_AES_128_CBC_SHA256:         "TLS_RSA_WITH_AES_128_CBC_SHA256",
	tls.TLS_RSA_WITH_AES_128_GCM_SHA256:         "TLS_RSA_WITH_AES_128_GCM_SHA256",
	tls.TLS_RSA_WITH_AES_256_GCM_SHA384:         "TLS_RSA_WITH_AES_256_GCM_SHA384",
	tls.TLS_ECDHE_ECDSA_WITH_RC4_128_SHA:        "TLS_ECDHE_ECDSA_WITH_RC4_128_SHA",
	tls.TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA:    "TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA",
	tls.TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA:    "TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA",
	tls.TLS_ECDHE_RSA_WITH_RC4_128_SHA:          "TLS_ECDHE_RSA_WITH_RC4_128_SHA",
	tls.TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA:     "TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA",
	tls.TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA:      "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA",
	tls.TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA:      "TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA",
	tls.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256:   "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
	tls.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256: "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256",
	tls.TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384:   "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384",
	tls.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384: "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384",
	tls.TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256: "TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256",
	tls.TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305:    "TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305",
	tls.TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305:  "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305",
	tls.TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256:   "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256",
	tls.TLS_AES_128_GCM_SHA256:                  "TLS_AES_128_GCM_SHA256",
	tls.TLS_AES_256_GCM_SHA384:                  "TLS_AES_256_GCM_SHA384",
	tls.TLS_CHACHA20_POLY1305_SHA256:            "TLS_CHACHA20_POLY1305_SHA256",
}

SupportedTLSCipherSuitesToString is constant-to-string map of available TLS cipher suites.

View Source 
var SupportedTLSVersions = map[string]TLSVersion{
	"tls1.0": tls.VersionTLS10,
	"tls1.1": tls.VersionTLS11,
	"tls1.2": tls.VersionTLS12,
	"tls1.3": tls.VersionTLS13,
}

SupportedTLSVersions is string-to-constant map of available TLS versions.

View Source 
var SupportedTLSVersionsToString = map[TLSVersion]string{
	tls.VersionTLS10: "tls1.0",
	tls.VersionTLS11: "tls1.1",
	tls.VersionTLS12: "tls1.2",
	tls.VersionTLS13: "tls1.3",
}

SupportedTLSVersionsToString is constant-to-string map of available TLS versions.

Functions

func ConcatErrors 

func ConcatErrors(errors []error, separator string) string

ConcatErrors is a a helper function for joining error messages into a single string.

TODO: use Go 2.0/xerrors style errors so we don't lose error type information and metadata.

func GetEndOffset 

func GetEndOffset(steps []ExecutionStep) (lastStepOffset time.Duration, isFinal bool)

GetEndOffset returns the time offset of the last step of the execution plan, and whether that step is a final one, i.e. whether the number of planned or unplanned is 0.

func GetMaxPlannedVUs 

func GetMaxPlannedVUs(steps []ExecutionStep) (result uint64)

GetMaxPlannedVUs returns the maximum number of planned VUs at any stage of the execution plan.

func GetMaxPossibleVUs 

func GetMaxPossibleVUs(steps []ExecutionStep) (result uint64)

GetMaxPossibleVUs returns the maximum number of planned + unplanned (i.e. initialized mid-test) VUs at any stage of the execution plan. Unplanned VUs are possible in some executors, like the arrival-rate ones, as a way to have a low number of pre-allocated VUs, but be able to initialize new ones in the middle of the test, if needed. For example, if the remote system starts responding very slowly and all of the pre-allocated VUs are waiting for it.

IMPORTANT 1: Getting planned and unplanned VUs separately for the whole duration of a test can often lead to mistakes. That's why this function is called GetMaxPossibleVUs() and why there is no GetMaxUnplannedVUs() function.

As an example, imagine that you have an executor with MaxPlannedVUs=20 and MaxUnplannedVUs=0, followed immediately after by another executor with MaxPlannedVUs=10 and MaxUnplannedVUs=10. The MaxPlannedVUs number for the whole test is 20, and MaxUnplannedVUs is 10, but since those executors won't run concurrently, MaxVUs for the whole test is not 30, rather it's 20, since 20 VUs will be sufficient to run the whole test.

IMPORTANT 2: this has one very important exception. The externally controlled executor doesn't use the MaxUnplannedVUs (i.e. this function will return 0), since their initialization and usage is directly controlled by the user and is effectively bounded only by the resources of the machine k6 is running on.

func Max 

func Max(a, b int64) int64

Returns the maximum value of a and b.

func Min 

func Min(a, b int64) int64

Returns the minimum value of a and b.

func NormalizeAndAnonymizePath 

func NormalizeAndAnonymizePath(path string) string

NormalizeAndAnonymizePath Normalizes (to use a / path separator) and anonymizes a file path, by scrubbing usernames from home directories.

func RegisterExecutorConfigType 

func RegisterExecutorConfigType(configType string, constructor ExecutorConfigConstructor)

RegisterExecutorConfigType adds the supplied ExecutorConfigConstructor as the constructor for its type in the configConstructors map, in a thread-safe manner

func StrictJSONUnmarshal 

func StrictJSONUnmarshal(data []byte, v interface{}) error

StrictJSONUnmarshal decodes a JSON in a strict manner, emitting an error if there are unknown fields or unexpected data

func WithExecutionState 

func WithExecutionState(ctx context.Context, s *ExecutionState) context.Context

WithExecutionState embeds an ExecutionState in ctx.

func WithScenarioState 

func WithScenarioState(ctx context.Context, s *ScenarioState) context.Context

WithScenarioState embeds a ScenarioState in ctx.

Types

type ActiveVU 

type ActiveVU interface {
	// Run the configured exported function in the VU once. The only
	// way to interrupt the execution is to cancel the context given
	// to InitializedVU.Activate()
	RunOnce() error
}

ActiveVU represents an actively running virtual user.

type Archive 

type Archive struct {
	// The runner to use, eg. "js".
	Type string `json:"type"`

	// Options to use.
	Options Options `json:"options"`

	// TODO: rewrite the encoding, decoding of json to use another type with only the fields it
	// needs in order to remove Filename and Pwd from this
	// Filename and contents of the main file being executed.
	Filename    string   `json:"filename"` // only for json
	FilenameURL *url.URL `json:"-"`
	Data        []byte   `json:"-"`

	// Working directory for resolving relative paths.
	Pwd    string   `json:"pwd"` // only for json
	PwdURL *url.URL `json:"-"`

	Filesystems map[string]fsext.Fs `json:"-"`

	// Environment variables
	Env map[string]string `json:"env"`

	CompatibilityMode string `json:"compatibilityMode"`

	K6Version string `json:"k6version"`
	Goos      string `json:"goos"`
}

An Archive is a rollup of all resources and options needed to reproduce a test identically elsewhere.

func ReadArchive 

func ReadArchive(in io.Reader) (*Archive, error)

ReadArchive reads an archive created by Archive.Write from a reader.

func (*Archive) Write 

func (arc *Archive) Write(out io.Writer) error

Write serialises the archive to a writer.

The format should be treated as opaque; currently it is simply a TAR rollup, but this may change. If it does change, ReadArchive must be able to handle all previous formats as well as the current one.

type BufferPool 

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

BufferPool implements a bytes.Buffer pool using sync.Pool

func NewBufferPool 

func NewBufferPool() *BufferPool

NewBufferPool create a new instance of BufferPool using a sync.Pool implementation returning a bytes.NewBuffer for each pooled new element

func (BufferPool) Get 

func (bp BufferPool) Get() *bytes.Buffer

Get return a bytes.Buffer from the pool

func (BufferPool) Put 

func (bp BufferPool) Put(b *bytes.Buffer)

Put return the given bytes.Buffer to the pool calling Buffer.Reset() before

type Check 

type Check struct {
	// Arbitrary name of the check.
	Name string `json:"name"`

	// A Check belongs to a Group, which may belong to other groups. The Path describes
	// the hierarchy of these groups, with the segments delimited by '::'.
	// As an example: a check "My Check" within a group "Inner" within a group "Outer"
	// would have a Path of "::Outer::Inner::My Check". The empty first item is the root group,
	// which is always named "".
	Group *Group `json:"-"`
	Path  string `json:"path"`

	// A check's ID is a hash of the Path. It is deterministic between different k6
	// instances of the same version, but should be treated as opaque - the hash function
	// or length may change.
	ID string `json:"id"`

	// Counters for how many times this check has passed and failed respectively.
	Passes int64 `json:"passes"`
	Fails  int64 `json:"fails"`
}

A Check stores a series of successful or failing tests against a value.

For more information, refer to the js/modules/k6.K6.Check() function.

func NewCheck 

func NewCheck(name string, group *Group) (*Check, error)

Creates a new check with the given name and parent group. The group may not be nil.

type CompatibilityMode 

type CompatibilityMode uint8

CompatibilityMode specifies the JS compatibility mode 

const (
	// CompatibilityModeExtended achieves ES6+ compatibility with Babel
	CompatibilityModeExtended CompatibilityMode = iota + 1
	// CompatibilityModeBase is standard goja ES5.1+
	CompatibilityModeBase
)

func CompatibilityModeString 

func CompatibilityModeString(s string) (CompatibilityMode, error)

CompatibilityModeString retrieves an enum value from the enum constants string name. Throws an error if the param is not part of the enum.

func CompatibilityModeValues 

func CompatibilityModeValues() []CompatibilityMode

CompatibilityModeValues returns all values of the enum

func ValidateCompatibilityMode 

func ValidateCompatibilityMode(val string) (cm CompatibilityMode, err error)

ValidateCompatibilityMode checks if the provided val is a valid compatibility mode

func (CompatibilityMode) IsACompatibilityMode 

func (i CompatibilityMode) IsACompatibilityMode() bool

IsACompatibilityMode returns "true" if the value is listed in the enum definition. "false" otherwise

func (CompatibilityMode) String 

func (i CompatibilityMode) String() string

type DialContexter 

type DialContexter interface {
	DialContext(ctx context.Context, network, addr string) (net.Conn, error)
}

DialContexter is an interface that can dial with a context

type ExecutionSegment 

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

ExecutionSegment represents a (start, end] partition of the total execution work for a specific test. For example, if we want the split the execution of a test in 2 different parts, we can split it in two segments (0, 0.5] and (0,5, 1].

We use rational numbers so it's easier to verify the correctness and easier to reason about portions of indivisible things, like VUs. This way, we can easily split a test in thirds (i.e. (0, 1/3], (1/3, 2/3], (2/3, 1]), without fearing that we'll lose a VU along the way...

The most important part is that if work is split between multiple k6 instances, each k6 instance can precisely and reproducibly calculate its share of the work, just by knowing its own segment. There won't be a need to schedule the execution from a master node, or to even know how many other k6 instances are running!

func NewExecutionSegment 

func NewExecutionSegment(from, to *big.Rat) (*ExecutionSegment, error)

NewExecutionSegment validates the supplied arguments (basically, that 0 <= from < to <= 1) and either returns an error, or it returns a fully-initialized and usable execution segment.

func NewExecutionSegmentFromString 

func NewExecutionSegmentFromString(toStr string) (result *ExecutionSegment, err error)

NewExecutionSegmentFromString validates the supplied string value and returns the newly created ExecutionSegment or and error from it.

We are able to parse both single percentage/float/fraction values, and actual (from: to] segments. For the single values, we just treat them as the beginning segment - thus the execution segment can be used as a shortcut for quickly running an arbitrarily scaled-down version of a test.

The parsing logic is that values with a colon, i.e. ':', are full segments: 

`1/2:3/4`, `0.5:0.75`, `50%:75%`, and even `2/4:75%` should be (1/2, 3/4]

And values without a colon are the end of a first segment: 

`20%`, `0.2`,  and `1/5` should be converted to (0, 1/5]

empty values should probably be treated as "1", i.e. the whole execution

func (*ExecutionSegment) CopyScaleRat 

func (es *ExecutionSegment) CopyScaleRat(value *big.Rat) *big.Rat

CopyScaleRat scales rational numbers without changing them - creates a new bit.Rat object and uses it for the calculation.

func (*ExecutionSegment) Equal 

func (es *ExecutionSegment) Equal(other *ExecutionSegment) bool

Equal returns true only if the two execution segments have the same from and to values.

func (*ExecutionSegment) FloatLength 

func (es *ExecutionSegment) FloatLength() float64

FloatLength is a helper method for getting some more human-readable information about the execution segment.

func (*ExecutionSegment) InPlaceScaleRat 

func (es *ExecutionSegment) InPlaceScaleRat(value *big.Rat) *big.Rat

InPlaceScaleRat scales rational numbers in-place - it changes the passed argument (and also returns it, to allow for chaining, like many other big.Rat methods).

func (*ExecutionSegment) MarshalText 

func (es *ExecutionSegment) MarshalText() ([]byte, error)

MarshalText implements the encoding.TextMarshaler interface, so is used for text and JSON encoding of the execution segment.

func (*ExecutionSegment) Scale 

func (es *ExecutionSegment) Scale(value int64) int64

Scale proportionally scales the supplied value, according to the execution segment's position and size of the work.

func (*ExecutionSegment) Split 

func (es *ExecutionSegment) Split(numParts int64) ([]*ExecutionSegment, error)

Split evenly divides the execution segment into the specified number of equal consecutive execution sub-segments.

func (*ExecutionSegment) String 

func (es *ExecutionSegment) String() string

func (*ExecutionSegment) SubSegment 

func (es *ExecutionSegment) SubSegment(child *ExecutionSegment) *ExecutionSegment

SubSegment returns a new execution sub-segment - if a is (1/2:1] and b is (0:1/2], then a.SubSegment(b) will return a new segment (1/2, 3/4].

The basic formula for c = a.SubSegment(b) is: 

c.from = a.from + b.from * (a.to - a.from)
c.to = c.from + (b.to - b.from) * (a.to - a.from)

func (*ExecutionSegment) UnmarshalText 

func (es *ExecutionSegment) UnmarshalText(text []byte) (err error)

UnmarshalText implements the encoding.TextUnmarshaler interface, so that execution segments can be specified as CLI flags, environment variables, and JSON strings. It is a wrapper for the NewExecutionFromString() constructor.

type ExecutionSegmentSequence 

type ExecutionSegmentSequence []*ExecutionSegment

ExecutionSegmentSequence represents an ordered chain of execution segments, where the end of one segment is the beginning of the next. It can serialized as a comma-separated string of rational numbers "r1,r2,r3,...,rn", which represents the sequence (r1, r2], (r2, r3], (r3, r4], ..., (r{n-1}, rn]. The empty value should be treated as if there is a single (0, 1] segment.

func GetFilledExecutionSegmentSequence 

func GetFilledExecutionSegmentSequence(
	sequence *ExecutionSegmentSequence, fallback *ExecutionSegment,
) (result ExecutionSegmentSequence)

GetFilledExecutionSegmentSequence makes sure we don't have any gaps in the given execution segment sequence, or a nil one. It makes sure that the whole 0-1 range is filled.

func NewExecutionSegmentSequence 

func NewExecutionSegmentSequence(segments ...*ExecutionSegment) (ExecutionSegmentSequence, error)

NewExecutionSegmentSequence validates the that the supplied execution segments are non-overlapping and without gaps. It will return a new execution segment sequence if that is true, and an error if it's not.

func NewExecutionSegmentSequenceFromString 

func NewExecutionSegmentSequenceFromString(strSeq string) (ExecutionSegmentSequence, error)

NewExecutionSegmentSequenceFromString parses strings of the format "r1,r2,r3,...,rn", which represents the sequences like (r1, r2], (r2, r3], (r3, r4], ..., (r{n-1}, rn].

func (ExecutionSegmentSequence) FindSegmentPosition 

func (ess ExecutionSegmentSequence) FindSegmentPosition(segment *ExecutionSegment) (int, error)

FindSegmentPosition returns the index of the supplied execution segment in the sequence, or an error if the segment isn't present. This shouldn't be used on a nil or empty sequence, it's best to use this method on the result of GetFilledExecutionSegmentSequence().

func (ExecutionSegmentSequence) IsFull 

func (ess ExecutionSegmentSequence) IsFull() bool

IsFull returns whether the sequences is full, that is, whether it starts at 0 and ends at 1. Use GetFilledExecutionSegmentSequence() to get a full sequence.

func (ExecutionSegmentSequence) LCD 

func (ess ExecutionSegmentSequence) LCD() int64

LCD calculates the lowest common denominator of the sequence. https://en.wikipedia.org/wiki/Least_common_multiple#Using_the_greatest_common_divisor

func (ExecutionSegmentSequence) MarshalText 

func (ess ExecutionSegmentSequence) MarshalText() ([]byte, error)

MarshalText implements the encoding.TextMarshaler interface, so is used for text and JSON encoding of the execution segment sequences.

func (ExecutionSegmentSequence) String 

func (ess ExecutionSegmentSequence) String() string

String just implements the fmt.Stringer interface, encoding the sequence of segments as "start1,end1,end2,end3,...,endn".

func (*ExecutionSegmentSequence) UnmarshalText 

func (ess *ExecutionSegmentSequence) UnmarshalText(text []byte) (err error)

UnmarshalText implements the encoding.TextUnmarshaler interface, so that execution segment sequences can be specified as CLI flags, environment variables, and JSON strings.

type ExecutionSegmentSequenceWrapper 

type ExecutionSegmentSequenceWrapper struct {
	ExecutionSegmentSequence // a filled-out segment sequence
	// contains filtered or unexported fields
}

ExecutionSegmentSequenceWrapper is a caching layer on top of the execution segment sequence that allows us to make fast and useful calculations, after a somewhat slow initialization.

func NewExecutionSegmentSequenceWrapper 

func NewExecutionSegmentSequenceWrapper(ess ExecutionSegmentSequence) *ExecutionSegmentSequenceWrapper

NewExecutionSegmentSequenceWrapper expects a filled-out execution segment sequence. It pre-calculates the initial caches of and returns a new ExecutionSegmentSequenceWrapper, but doesn't calculate the striped offsets.

func (*ExecutionSegmentSequenceWrapper) GetNewExecutionSegmentSequenceFromValue 

func (essw *ExecutionSegmentSequenceWrapper) GetNewExecutionSegmentSequenceFromValue(value int64, trackedIndex int) (
	newSequence *ExecutionSegmentSequenceWrapper, newIndex int, err error,
)

GetNewExecutionSegmentSequenceFromValue uses the value provided, splits it between all the segments, using the striping offsets in the sequence, generating a new segment sequence. It then returns a new ExecutionSegmentSequenceWrapper, with the new sequence and segments, such that each new segment in the new sequence has length `Scale(value)/value` while keeping the order.

Additionally, the position of a given segment index can be tracked (since empty segments are removed), so that you can reconstruct an ExecutionTuple, if required. If the segment with the trackedIndex is not part of the new sequence, or if a new sequence cannot be generated (for example, for 0 values), an error will be returned.

func (*ExecutionSegmentSequenceWrapper) GetStripedOffsets 

func (essw *ExecutionSegmentSequenceWrapper) GetStripedOffsets(segmentIndex int) (int64, []int64, int64)

GetStripedOffsets returns the stripped offsets for the given segment the returned values are as follows in order:

  • start: the first value that is for the segment
  • offsets: a list of offsets from the previous value for the segment. This are only the offsets to from the start to the next start if we chunk the elements we are going to strip into lcd sized chunks
  • lcd: the LCD of the lengths of all segments in the sequence. This is also the number of elements after which the algorithm starts to loop and give the same values

func (*ExecutionSegmentSequenceWrapper) GetTuple 

func (essw *ExecutionSegmentSequenceWrapper) GetTuple(segmentIndex int) *ExecutionTuple

GetTuple returns an ExecutionTuple for the specified segment index.

func (*ExecutionSegmentSequenceWrapper) LCD 

func (essw *ExecutionSegmentSequenceWrapper) LCD() int64

LCD returns the (cached) least common denominator of the sequence - no need to calculate it again, since we did it in the constructor.

func (*ExecutionSegmentSequenceWrapper) ScaleInt64 

func (essw *ExecutionSegmentSequenceWrapper) ScaleInt64(segmentIndex int, value int64) int64

ScaleInt64 scales the provided value for the given segment.

type ExecutionState 

type ExecutionState struct {
	// A portal to the broader test run state, so the different executors have
	// access to the test options, built-in metrics, etc.. They will need to
	// access things like the current execution segment, the per-run metrics
	// tags, different metrics to emit, etc.
	//
	// Obviously, things here are not meant to be changed... They should be a
	// constant during the execution of a single test, but we can't easily
	// enforce that via the Go type system...
	Test *TestRunState

	ExecutionTuple *ExecutionTuple // TODO Rename, possibly move
	// contains filtered or unexported fields
}

ExecutionState contains a few different things:

  • Some convenience items, that are needed by all executors, like the execution segment and the unique VU ID generator. By keeping those here, we can just pass the ExecutionState to the different executors, instead of individually passing them each item.
  • Mutable counters that different executors modify and other parts of k6 can read, e.g. for the vus and vus_max metrics k6 emits every second.
  • Pausing controls and statistics.

The counters and timestamps here are primarily meant to be used for information extraction and avoidance of ID collisions. Using many of the counters here for synchronization between VUs could result in HIDDEN data races, because the Go data race detector can't detect any data races involving atomics...

The only functionality intended for synchronization is the one revolving around pausing, and uninitializedUnplannedVUs for restricting the number of unplanned VUs being initialized.

func GetExecutionState 

func GetExecutionState(ctx context.Context) *ExecutionState

GetExecutionState returns an ExecutionState from ctx.

func NewExecutionState 

func NewExecutionState(
	testRunState *TestRunState, et *ExecutionTuple, maxPlannedVUs, maxPossibleVUs uint64,
) *ExecutionState

NewExecutionState initializes all of the pointers in the ExecutionState with zeros. It also makes sure that the initial state is unpaused, by setting resumeNotify to an already closed channel.

func (*ExecutionState) AddFullIterations 

func (es *ExecutionState) AddFullIterations(count uint64) uint64

AddFullIterations increments the number of full (i.e uninterrupted) iterations by the provided amount.

IMPORTANT: for UI/information purposes only, don't use for synchronization.

func (*ExecutionState) AddInitializedVU 

func (es *ExecutionState) AddInitializedVU(vu InitializedVU)

AddInitializedVU is a helper function that adds VUs into the buffer and increases the initialized VUs counter.

func (*ExecutionState) AddInterruptedIterations 

func (es *ExecutionState) AddInterruptedIterations(count uint64) uint64

AddInterruptedIterations increments the number of partial (i.e interrupted) iterations by the provided amount.

IMPORTANT: for UI/information purposes only, don't use for synchronization.

func (*ExecutionState) GetCurrentExecutionStatus 

func (es *ExecutionState) GetCurrentExecutionStatus() ExecutionStatus

GetCurrentExecutionStatus returns the current execution status. Don't use this for synchronization unless you've made the k6 behavior somewhat predictable with options like --paused or --linger.

func (*ExecutionState) GetCurrentTestRunDuration 

func (es *ExecutionState) GetCurrentTestRunDuration() time.Duration

GetCurrentTestRunDuration returns the duration for which the test has already ran. If the test hasn't started yet, that's 0. If it has started, but has been paused midway through, it will return the time up until the pause time. And if it's currently running, it will return the time since the start time.

IMPORTANT: for UI/information purposes only, don't use for synchronization.

func (*ExecutionState) GetCurrentlyActiveVUsCount 

func (es *ExecutionState) GetCurrentlyActiveVUsCount() int64

GetCurrentlyActiveVUsCount returns the number of VUs that are currently executing the test script. This also includes any VUs that are in the process of gracefully winding down.

IMPORTANT: for UI/information purposes only, don't use for synchronization.

func (*ExecutionState) GetFullIterationCount 

func (es *ExecutionState) GetFullIterationCount() uint64

GetFullIterationCount returns the total of full (i.e uninterrupted) iterations that have been completed so far.

IMPORTANT: for UI/information purposes only, don't use for synchronization.

func (*ExecutionState) GetInitializedVUsCount 

func (es *ExecutionState) GetInitializedVUsCount() int64

GetInitializedVUsCount returns the total number of currently initialized VUs.

Important: this doesn't include any temporary/service VUs that are destroyed after they are used. These are created for the initial retrieval of the exported script options and for the execution of setup() and teardown()

IMPORTANT: for UI/information purposes only, don't use for synchronization.

func (*ExecutionState) GetPartialIterationCount 

func (es *ExecutionState) GetPartialIterationCount() uint64

GetPartialIterationCount returns the total of partial (i.e interrupted) iterations that have been completed so far.

IMPORTANT: for UI/information purposes only, don't use for synchronization.

func (*ExecutionState) GetPlannedVU 

func (es *ExecutionState) GetPlannedVU(logger *logrus.Entry, modifyActiveVUCount bool) (InitializedVU, error)

GetPlannedVU tries to get a pre-initialized VU from the buffer channel. This shouldn't fail and should generally be an instantaneous action, but if it doesn't happen for MaxTimeToWaitForPlannedVU (for example, because the system is overloaded), a warning will be printed. If we reach that timeout more than MaxRetriesGetPlannedVU number of times, this function will return an error, since we either have a bug with some executor, or the machine is very, very overloaded.

If modifyActiveVUCount is true, the method would also increment the counter for active VUs. In most cases, that's the desired behavior, but some executors might have to retrieve their reserved VUs without using them immediately - for example, the externally-controlled executor when the configured maxVUs number is greater than the configured starting VUs.

func (*ExecutionState) GetUniqueVUIdentifiers 

func (es *ExecutionState) GetUniqueVUIdentifiers() (uint64, uint64)

GetUniqueVUIdentifiers returns the next unique VU IDs, both local (for the current instance, exposed as __VU) and global (across k6 instances, exposed in the k6/execution module). It starts from 1, for backwards compatibility.

func (*ExecutionState) GetUnplannedVU 

func (es *ExecutionState) GetUnplannedVU(ctx context.Context, logger *logrus.Entry) (InitializedVU, error)

GetUnplannedVU checks if any unplanned VUs remain to be initialized, and if they do, it initializes one and returns it. If all unplanned VUs have already been initialized, it returns one from the global vus buffer, but doesn't automatically increment the active VUs counter in either case.

IMPORTANT: GetUnplannedVU() doesn't do any checking if the requesting executor is actually allowed to have the VU at this particular time. Executors are trusted to correctly declare their needs (via their GetExecutionRequirements() methods) and then to never ask for more VUs than they have specified in those requirements.

func (*ExecutionState) HasEnded 

func (es *ExecutionState) HasEnded() bool

HasEnded returns true if the test has finished executing. It will return false until MarkEnded() is called.

func (*ExecutionState) HasStarted 

func (es *ExecutionState) HasStarted() bool

HasStarted returns true if the test has actually started executing. It will return false while a test is in the init phase, or if it has been initially paused. But if will return true if a test is paused midway through its execution (see above for details regarding the feasibility of that pausing for normal executors).

func (*ExecutionState) InitializeNewVU 

func (es *ExecutionState) InitializeNewVU(ctx context.Context, logger *logrus.Entry) (InitializedVU, error)

InitializeNewVU creates and returns a brand new VU, updating the relevant tracking counters.

func (*ExecutionState) IsPaused 

func (es *ExecutionState) IsPaused() bool

IsPaused quickly returns whether the test is currently paused, by reading the atomic currentPauseTime timestamp

func (*ExecutionState) MarkEnded 

func (es *ExecutionState) MarkEnded()

MarkEnded saves the current timestamp as the test end time.

CAUTION: Calling MarkEnded() a second time for the same execution state will result in a panic!

func (*ExecutionState) MarkStarted 

func (es *ExecutionState) MarkStarted()

MarkStarted saves the current timestamp as the test start time.

CAUTION: Calling MarkStarted() a second time for the same execution state will result in a panic!

func (*ExecutionState) ModCurrentlyActiveVUsCount 

func (es *ExecutionState) ModCurrentlyActiveVUsCount(mod int64) int64

ModCurrentlyActiveVUsCount changes the total number of currently active VUs.

IMPORTANT: for UI/information purposes only, don't use for synchronization.

func (*ExecutionState) ModInitializedVUsCount 

func (es *ExecutionState) ModInitializedVUsCount(mod int64) int64

ModInitializedVUsCount changes the total number of currently initialized VUs.

IMPORTANT: for UI/information purposes only, don't use for synchronization.

func (*ExecutionState) Pause 

func (es *ExecutionState) Pause() error

Pause pauses the current execution. It acquires the lock, writes the current timestamp in currentPauseTime, and makes a new channel for resumeNotify. Pause can return an error if the test was already paused.

func (*ExecutionState) Resume 

func (es *ExecutionState) Resume() error

Resume unpauses the test execution. Unless the test wasn't yet started, it calculates the duration between now and the old currentPauseTime and adds it to Resume will emit an error if the test wasn't paused.

func (*ExecutionState) ResumeNotify 

func (es *ExecutionState) ResumeNotify() <-chan struct{}

ResumeNotify returns a channel which will be closed (i.e. could be read from) as soon as the test execution is resumed.

Since tests would likely be paused only rarely, unless you directly need to be notified via a channel that the test isn't paused or that it has resumed, it's probably a good idea to first use the IsPaused() method, since it will be much faster.

And, since tests won't be paused most of the time, it's probably better to check for that like this: 

if executionState.IsPaused() {
    <-executionState.ResumeNotify()
}

func (*ExecutionState) ReturnVU 

func (es *ExecutionState) ReturnVU(vu InitializedVU, wasActive bool)

ReturnVU is a helper function that puts VUs back into the buffer and decreases the active VUs counter.

func (*ExecutionState) SetExecutionStatus 

func (es *ExecutionState) SetExecutionStatus(newStatus ExecutionStatus) (oldStatus ExecutionStatus)

SetExecutionStatus changes the current execution status to the supplied value and returns the current value.

func (*ExecutionState) SetInitVUFunc 

func (es *ExecutionState) SetInitVUFunc(initVUFunc InitVUFunc)

SetInitVUFunc is called by the execution scheduler's init function, and it's used for setting the "constructor" function used for the initializing unplanned VUs.

TODO: figure out a better dependency injection method?

type ExecutionStatus 

type ExecutionStatus uint32

ExecutionStatus is used to mark the possible states of a test run at any given time in its execution, from its start to its finish. 

const (
	ExecutionStatusCreated ExecutionStatus = iota
	ExecutionStatusInitVUs
	ExecutionStatusInitExecutors
	ExecutionStatusInitDone
	ExecutionStatusPausedBeforeRun
	ExecutionStatusStarted
	ExecutionStatusSetup
	ExecutionStatusRunning
	ExecutionStatusTeardown
	ExecutionStatusEnded
	ExecutionStatusInterrupted
)

Possible execution status values

func ExecutionStatusString 

func ExecutionStatusString(s string) (ExecutionStatus, error)

ExecutionStatusString retrieves an enum value from the enum constants string name. Throws an error if the param is not part of the enum.

func ExecutionStatusValues 

func ExecutionStatusValues() []ExecutionStatus

ExecutionStatusValues returns all values of the enum

func (ExecutionStatus) IsAExecutionStatus 

func (i ExecutionStatus) IsAExecutionStatus() bool

IsAExecutionStatus returns "true" if the value is listed in the enum definition. "false" otherwise

func (ExecutionStatus) String 

func (i ExecutionStatus) String() string

type ExecutionStep 

type ExecutionStep struct {
	TimeOffset      time.Duration
	PlannedVUs      uint64
	MaxUnplannedVUs uint64
}

ExecutionStep is used by different executors to specify the planned number of VUs they will need at a particular time. The times are relative to their StartTime, i.e. they don't take into account the specific starting time of the executor, as that will be considered by the external execution executor separately.

A slice [{t1, v1}, {t2, v2}, {t3, v3}, ..., {tn, vn}] of execution steps means that an executor will need 0 VUs until t1, it will need v1 number of VUs from time t1 until t2, need v2 number of VUs from time t2 to t3, and so on. t1 is usually 0, tn is usually the same as GetMaxDuration() and vn is usually 0.

Keep in mind that t(i) may be exactly equal to t(i+i), when there's an abrupt transition in the number of VUs required by an executor. For example, the ramping-vus executor may have 0-duration stages, or it may scale up VUs in its last stage right until the end. These immediate transitions cannot be ignored, since the gracefulStop/gracefulRampDown options potentially allow any started iterations to finish.

[]ExecutionStep is also used by the ScenarioConfigs, to represent the amount of needed VUs among all executors, during the whole execution of a test script. In that context, each executor's StartTime is accounted for and included in the offsets.

type ExecutionTuple 

type ExecutionTuple struct {
	Sequence     *ExecutionSegmentSequenceWrapper
	Segment      *ExecutionSegment
	SegmentIndex int
}

ExecutionTuple is the combination of an ExecutionSegmentSequence(Wrapper) and a specific ExecutionSegment from it. It gives easy access to the efficient scaling and striping algorithms for that specific segment, since the results are cached in the sequence wrapper. It is also the basis for the SegmentedIndex type below, which is the actual implementation of a segmented (striped) iterator, usable both for segmenting actual iterations and for partitioning data between multiple instances.

For example, let's try to segment a load test in 3 unequal parts: 50%, 25% and 25% (so the ExecutionSegmentSequence will contain these segments: 0:1/2, 1/2:3/4, 3/4:1). The building blocks that k6 needs for distributed execution are segmented (non-overlapping) iterators and proportionally dividing integer numbers as fairly as possible between multiple segments in a stable manner.

The segmented iterators (i.e. SegmentedIndex values below) will be like this: 

Normal iterator:              0   1   2   3   4   5   6   7   8   9   10  11 ...
Instance 1 (0:1/2) iterator:  0       2       4       6       8       10     ...
Instance 2 (1/2:3/4) iterator:    1               5               9          ...
Instance 2 (3/4:1) iterator:              3               7               11 ...

See how every instance has its own uniqe non-overlapping iterator, but when we combine all of them, we cover every possible value in the original one.

We also can use this property to scale integer numbers proportionally, as fairly as possible, between the instances, like this: 

Global int value to scale:    1   2   3   4   5   6   7   8   9   10  11  12 ...
Calling ScaleInt64():
- Instance 1 (0:1/2) value:   1   1   2   2   3   3   4   4   5   5   6   6  ...
- Instance 2 (1/2:3/4) value: 0   1   1   1   1   2   2   2   2   3   3   3  ...
- Instance 2 (3/4:1) value:   0   0   0   1   1   1   1   2   2   2   2   3  ...

Notice how the sum of the per-instance values is always equal to the global value - this is what ExecutionTuple.ScaleInt64() does. Also compare both tables (their positions match), see how we only increment the value for a particular instance when we would have cycled the iterator on that step.

This also makes the scaling stable, in contrast to ExecutionSegment.Scale(). Scaled values will only ever increase, since we just increment them in a specific order between instances. There will never be a situation where `ScaleInt64(i)` is less than `ScaleInt64(i+n)` for any positive n!

The algorithm that calculates the offsets and everything that's necessary to have these segmented iterators is in NewExecutionSegmentSequenceWrapper(). The ExecutionTuple simply exposes them efficiently for a single segment of the sequence, so it's the thing that most users will probably need.

func NewExecutionTuple 

func NewExecutionTuple(segment *ExecutionSegment, sequence *ExecutionSegmentSequence) (*ExecutionTuple, error)

NewExecutionTuple returns a new ExecutionTuple for the provided segment and sequence.

TODO: don't return a pointer?

func (*ExecutionTuple) GetNewExecutionTupleFromValue 

func (et *ExecutionTuple) GetNewExecutionTupleFromValue(value int64) (*ExecutionTuple, error)

GetNewExecutionTupleFromValue re-segments the sequence, based on the given value (see GetNewExecutionSegmentSequenceFromValue() above), and either returns the new tuple, or an error if the current segment isn't present in the new sequence.

func (*ExecutionTuple) GetStripedOffsets 

func (et *ExecutionTuple) GetStripedOffsets() (int64, []int64, int64)

GetStripedOffsets returns the striped offsets for our execution segment.

func (*ExecutionTuple) ScaleInt64 

func (et *ExecutionTuple) ScaleInt64(value int64) int64

ScaleInt64 scales the provided value for our execution segment.

func (*ExecutionTuple) String 

func (et *ExecutionTuple) String() string

type Executor 

type Executor interface {
	GetConfig() ExecutorConfig
	GetProgress() *pb.ProgressBar
	GetLogger() *logrus.Entry

	Init(ctx context.Context) error
	Run(ctx context.Context, engineOut chan<- metrics.SampleContainer) error
}

Executor is the interface all executors should implement

type ExecutorConfig 

type ExecutorConfig interface {
	Validate() []error

	GetName() string
	GetType() string
	GetStartTime() time.Duration
	GetGracefulStop() time.Duration

	// This is used to validate whether a particular script can run in the cloud
	// or, in the future, in the native k6 distributed execution. Currently only
	// the externally-controlled executor should return false.
	IsDistributable() bool

	GetEnv() map[string]string
	// Allows us to get the non-default function the executor should run, if it
	// has been specified.
	//
	// TODO: use interface{} so plain http requests can be specified?
	GetExec() string
	GetTags() map[string]string

	// Calculates the VU requirements in different stages of the executor's
	// execution, including any extensions caused by waiting for iterations to
	// finish with graceful stops or ramp-downs.
	GetExecutionRequirements(*ExecutionTuple) []ExecutionStep
	GetScenarioOptions() *ScenarioOptions

	// Return a human-readable description of the executor
	GetDescription(*ExecutionTuple) string

	NewExecutor(*ExecutionState, *logrus.Entry) (Executor, error)

	// HasWork reports whether there is any work for the executor to do with a given segment.
	HasWork(*ExecutionTuple) bool
}

ExecutorConfig is an interface that should be implemented by all executor config types

func GetParsedExecutorConfig 

func GetParsedExecutorConfig(name, configType string, rawJSON []byte) (result ExecutorConfig, err error)

GetParsedExecutorConfig returns a struct instance corresponding to the supplied config type. It will be fully initialized - with both the default values of the type, as well as with whatever the user had specified in the JSON

type ExecutorConfigConstructor 

type ExecutorConfigConstructor func(name string, rawJSON []byte) (ExecutorConfig, error)

ExecutorConfigConstructor is a simple function that returns a concrete Config instance with the specified name and all default values correctly initialized

type Group 

type Group struct {
	// Arbitrary name of the group.
	Name string `json:"name"`

	// A group may belong to another group, which may belong to another group, etc. The Path
	// describes the hierarchy leading down to this group, with the segments delimited by '::'.
	// As an example: a group "Inner" inside a group named "Outer" would have a path of
	// "::Outer::Inner". The empty first item is the root group, which is always named "".
	Parent *Group `json:"-"`
	Path   string `json:"path"`

	// A group's ID is a hash of the Path. It is deterministic between different k6
	// instances of the same version, but should be treated as opaque - the hash function
	// or length may change.
	ID string `json:"id"`

	// Groups and checks that are children of this group.
	Groups        map[string]*Group `json:"groups"`
	OrderedGroups []*Group          `json:"-"`

	Checks        map[string]*Check `json:"checks"`
	OrderedChecks []*Check          `json:"-"`
	// contains filtered or unexported fields
}

A Group is an organisational block, that samples and checks may be tagged with.

For more information, refer to the js/modules/k6.K6.Group() function.

func NewGroup 

func NewGroup(name string, parent *Group) (*Group, error)

Creates a new group with the given name and parent group.

The root group must be created with the name "" and parent set to nil; this is the only case where a nil parent or empty name is allowed.

func (*Group) Check 

func (g *Group) Check(name string) (*Check, error)

Check creates a child check belonging to this group. This is safe to call from multiple goroutines simultaneously.

func (*Group) Group 

func (g *Group) Group(name string) (*Group, error)

Group creates a child group belonging to this group. This is safe to call from multiple goroutines simultaneously.

type IPNet 

type IPNet struct {
	net.IPNet
}

IPNet is a wrapper around net.IPNet for JSON unmarshalling

func ParseCIDR 

func ParseCIDR(s string) (*IPNet, error)

ParseCIDR creates an IPNet out of a CIDR string

func (*IPNet) MarshalText 

func (ipnet *IPNet) MarshalText() ([]byte, error)

MarshalText encodes the IPNet representation using CIDR notation.

func (*IPNet) UnmarshalText 

func (ipnet *IPNet) UnmarshalText(b []byte) error

UnmarshalText populates the IPNet from the given CIDR

type InitVUFunc 

type InitVUFunc func(context.Context, *logrus.Entry) (InitializedVU, error)

InitVUFunc is just a shorthand so we don't have to type the function signature every time.

type InitializedVU 

type InitializedVU interface {
	// Fully activate the VU so it will be able to run code
	Activate(*VUActivationParams) ActiveVU

	// GetID returns the unique VU ID
	GetID() uint64
}

InitializedVU represents a virtual user ready for work. It needs to be activated (i.e. given a context) before it can actually be used. Activation also requires a callback function, which will be called when the supplied context is done. That way, VUs can be returned to a pool and reused.

type LiveUpdatableExecutor 

type LiveUpdatableExecutor interface {
	UpdateConfig(ctx context.Context, newConfig interface{}) error
}

LiveUpdatableExecutor should be implemented for the executors whose configuration can be modified in the middle of the test execution. Currently, only the manual execution executor implements it.

type MultiSlotLimiter 

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

MultiSlotLimiter can restrict the concurrent execution of different groups of tasks to the given `slots` limit. Each group is represented with a string ID.

func NewMultiSlotLimiter 

func NewMultiSlotLimiter(slots int) *MultiSlotLimiter

NewMultiSlotLimiter initializes and returns a new MultiSlotLimiter with the given slot count TODO: move to lib and use something better than a mutex? sync.Map perhaps?

func (*MultiSlotLimiter) Slot 

func (l *MultiSlotLimiter) Slot(s string) SlotLimiter

Slot is used to retrieve the corresponding slot to the given string ID. If no slot with that ID exists, it creates it and saves it for future use. It is safe to call this method concurrently.

type Options 

type Options struct {
	// Should the test start in a paused state?
	Paused null.Bool `json:"paused" envconfig:"K6_PAUSED"`

	// Initial values for VUs, max VUs, duration cap, iteration cap, and stages.
	// See the Runner or Executor interfaces for more information.
	VUs        null.Int           `json:"vus" envconfig:"K6_VUS"`
	Duration   types.NullDuration `json:"duration" envconfig:"K6_DURATION"`
	Iterations null.Int           `json:"iterations" envconfig:"K6_ITERATIONS"`
	Stages     []Stage            `json:"stages" envconfig:"K6_STAGES"`

	// TODO: remove the `ignored:"true"` from the field tags, it's there so that
	// the envconfig library will ignore those fields.
	//
	// We should support specifying execution segments via environment
	// variables, but we currently can't, because envconfig has this nasty bug
	// (among others): https://github.com/kelseyhightower/envconfig/issues/113
	Scenarios                ScenarioConfigs           `json:"scenarios" ignored:"true"`
	ExecutionSegment         *ExecutionSegment         `json:"executionSegment" ignored:"true"`
	ExecutionSegmentSequence *ExecutionSegmentSequence `json:"executionSegmentSequence" ignored:"true"`

	// Timeouts for the setup() and teardown() functions
	NoSetup         null.Bool          `json:"noSetup" envconfig:"K6_NO_SETUP"`
	SetupTimeout    types.NullDuration `json:"setupTimeout" envconfig:"K6_SETUP_TIMEOUT"`
	NoTeardown      null.Bool          `json:"noTeardown" envconfig:"K6_NO_TEARDOWN"`
	TeardownTimeout types.NullDuration `json:"teardownTimeout" envconfig:"K6_TEARDOWN_TIMEOUT"`

	// Limit HTTP requests per second.
	RPS null.Int `json:"rps" envconfig:"K6_RPS"`

	// DNS handling configuration.
	DNS types.DNSConfig `json:"dns" envconfig:"K6_DNS"`

	// How many HTTP redirects do we follow?
	MaxRedirects null.Int `json:"maxRedirects" envconfig:"K6_MAX_REDIRECTS"`

	// Default User Agent string for HTTP requests.
	UserAgent null.String `json:"userAgent" envconfig:"K6_USER_AGENT"`

	// How many batch requests are allowed in parallel, in total and per host?
	Batch        null.Int `json:"batch" envconfig:"K6_BATCH"`
	BatchPerHost null.Int `json:"batchPerHost" envconfig:"K6_BATCH_PER_HOST"`

	// Should all HTTP requests and responses be logged (excluding body)?
	HTTPDebug null.String `json:"httpDebug" envconfig:"K6_HTTP_DEBUG"`

	// Accept invalid or untrusted TLS certificates.
	InsecureSkipTLSVerify null.Bool `json:"insecureSkipTLSVerify" envconfig:"K6_INSECURE_SKIP_TLS_VERIFY"`

	// Specify TLS versions and cipher suites, and present client certificates.
	TLSCipherSuites *TLSCipherSuites `json:"tlsCipherSuites" envconfig:"K6_TLS_CIPHER_SUITES"`
	TLSVersion      *TLSVersions     `json:"tlsVersion" ignored:"true"`
	TLSAuth         []*TLSAuth       `json:"tlsAuth" envconfig:"K6_TLSAUTH"`

	// Throw warnings (eg. failed HTTP requests) as errors instead of simply logging them.
	Throw null.Bool `json:"throw" envconfig:"K6_THROW"`

	// Define thresholds; these take the form of 'metric=["snippet1", "snippet2"]'.
	// To create a threshold on a derived metric based on tag queries ("submetrics"), create a
	// metric on a nonexistent metric named 'real_metric{tagA:valueA,tagB:valueB}'.
	Thresholds map[string]metrics.Thresholds `json:"thresholds" envconfig:"K6_THRESHOLDS"`

	// Blacklist IP ranges that tests may not contact. Mainly useful in hosted setups.
	BlacklistIPs []*IPNet `json:"blacklistIPs" envconfig:"K6_BLACKLIST_IPS"`

	// Block hostname patterns that tests may not contact.
	BlockedHostnames types.NullHostnameTrie `json:"blockHostnames" envconfig:"K6_BLOCK_HOSTNAMES"`

	// Hosts overrides dns entries for given hosts
	Hosts types.NullHosts `json:"hosts" envconfig:"K6_HOSTS"`

	// Disable keep-alive connections
	NoConnectionReuse null.Bool `json:"noConnectionReuse" envconfig:"K6_NO_CONNECTION_REUSE"`

	// Do not reuse connections between VU iterations. This gives more realistic results (depending
	// on what you're looking for), but you need to raise various kernel limits or you'll get
	// errors about running out of file handles or sockets, or being unable to bind addresses.
	NoVUConnectionReuse null.Bool `json:"noVUConnectionReuse" envconfig:"K6_NO_VU_CONNECTION_REUSE"`

	// MinIterationDuration can be used to force VUs to pause between iterations if a specific
	// iteration is shorter than the specified value.
	MinIterationDuration types.NullDuration `json:"minIterationDuration" envconfig:"K6_MIN_ITERATION_DURATION"`

	// These values are for third party collectors' benefit.
	// Can't be set through env vars.
	External map[string]json.RawMessage `json:"ext" ignored:"true"`

	// Summary trend stats for trend metrics (response times) in CLI output
	SummaryTrendStats []string `json:"summaryTrendStats" envconfig:"K6_SUMMARY_TREND_STATS"`

	// Summary time unit for summary metrics (response times) in CLI output
	SummaryTimeUnit null.String `json:"summaryTimeUnit" envconfig:"K6_SUMMARY_TIME_UNIT"`

	// Which system tags to include with metrics ("method", "vu" etc.)
	// Use pointer for identifying whether user provide any tag or not.
	SystemTags *metrics.SystemTagSet `json:"systemTags" envconfig:"K6_SYSTEM_TAGS"`

	// Tags are key-value pairs to be applied to all samples for the run.
	RunTags map[string]string `json:"tags" envconfig:"K6_TAGS"`

	// Buffer size of the channel for metric samples; 0 means unbuffered
	MetricSamplesBufferSize null.Int `json:"metricSamplesBufferSize" envconfig:"K6_METRIC_SAMPLES_BUFFER_SIZE"`

	// Do not reset cookies after a VU iteration
	NoCookiesReset null.Bool `json:"noCookiesReset" envconfig:"K6_NO_COOKIES_RESET"`

	// Discard Http Responses Body
	DiscardResponseBodies null.Bool `json:"discardResponseBodies" envconfig:"K6_DISCARD_RESPONSE_BODIES"`

	// Redirect console logging to a file
	ConsoleOutput null.String `json:"-" envconfig:"K6_CONSOLE_OUTPUT"`

	// Specify client IP ranges and/or CIDR from which VUs will make requests
	LocalIPs types.NullIPPool `json:"-" envconfig:"K6_LOCAL_IPS"`
}

func (Options) Apply 

func (o Options) Apply(opts Options) Options

Returns the result of overwriting any fields with any that are set on the argument.

Example: 

a := Options{VUs: null.IntFrom(10)}
b := Options{VUs: null.IntFrom(5)}
a.Apply(b) // Options{VUs: null.IntFrom(5)}

func (Options) ForEachSpecified 

func (o Options) ForEachSpecified(structTag string, callback func(key string, value interface{}))

ForEachSpecified enumerates all struct fields and calls the supplied function with each element that is valid. It panics for any unfamiliar or unexpected fields, so make sure new fields in Options are accounted for.

func (Options) Validate 

func (o Options) Validate() []error

Validate checks if all of the specified options make sense

type PausableExecutor 

type PausableExecutor interface {
	SetPaused(bool) error
}

PausableExecutor should be implemented by the executors that can be paused and resumed in the middle of the test execution. Currently, only the externally controlled executor implements it.

type Runner 

type Runner interface {
	// Creates an Archive of the runner. There should be a corresponding NewFromArchive() function
	// that will restore the runner from the archive.
	MakeArchive() *Archive

	// Spawns a new VU. It's fine to make this function rather heavy, if it means a performance
	// improvement at runtime. Remember, this is called once per VU and normally only at the start
	// of a test - RunOnce() may be called hundreds of thousands of times, and must be fast.
	NewVU(ctx context.Context, idLocal, idGlobal uint64, out chan<- metrics.SampleContainer) (InitializedVU, error)

	// Runs pre-test setup, if applicable.
	Setup(ctx context.Context, out chan<- metrics.SampleContainer) error

	// Returns json representation of the setup data if setup() is specified and run, nil otherwise
	GetSetupData() []byte

	// Saves the externally supplied setup data as json in the runner
	SetSetupData([]byte)

	// Runs post-test teardown, if applicable.
	Teardown(ctx context.Context, out chan<- metrics.SampleContainer) error

	// Returns the default (root) Group.
	GetDefaultGroup() *Group

	// Get and set options. The initial value will be whatever the script specifies (for JS,
	// `export let options = {}`); cmd/run.go will mix this in with CLI-, config- and env-provided
	// values and write it back to the runner.
	GetOptions() Options
	SetOptions(opts Options) error

	// Returns whether the given name is an exported and executable
	// function in the script.
	IsExecutable(string) bool

	HandleSummary(context.Context, *Summary) (map[string]io.Reader, error)
}

A Runner is a factory for VUs. It should precompute as much as possible upon creation (parse ASTs, load files into memory, etc.), so that spawning VUs becomes as fast as possible. The Runner doesn't actually *do* anything in itself, the ExecutionScheduler is responsible for wrapping and scheduling these VUs for execution.

TODO: Rename this to something more obvious? This name made sense a very long time ago.

interfacebloat: We may evaluate in the future to move out some methods; but considering how central it is, it would require a huge effort.

type RuntimeOptions 

type RuntimeOptions struct {
	TestType null.String `json:"-"`

	// Whether to pass the actual system environment variables to the JS runtime
	IncludeSystemEnvVars null.Bool `json:"includeSystemEnvVars"`

	// JS compatibility mode: "extended" (Goja+Babel) or "base" (plain Goja)
	//
	// TODO: when we resolve https://github.com/k6io/k6/issues/883, we probably
	// should use the CompatibilityMode type directly... but by then, we'd need to have
	// some way of knowing if the value has been set by the user or if we're using the
	// default one, so we can handle `k6 run --compatibility-mode=base es6_extended_archive.tar`
	CompatibilityMode null.String `json:"compatibilityMode"`

	// Environment variables passed onto the runner
	Env map[string]string `json:"env"`

	NoThresholds  null.Bool   `json:"noThresholds"`
	NoSummary     null.Bool   `json:"noSummary"`
	SummaryExport null.String `json:"summaryExport"`
	KeyWriter     null.String `json:"-"`
}

RuntimeOptions are settings passed onto the goja JS runtime

type ScenarioConfigs 

type ScenarioConfigs map[string]ExecutorConfig

ScenarioConfigs can contain mixed executor config types

func (ScenarioConfigs) GetFullExecutionRequirements 

func (scs ScenarioConfigs) GetFullExecutionRequirements(et *ExecutionTuple) []ExecutionStep

GetFullExecutionRequirements combines the execution requirements from all of the configured executors. It takes into account their start times and their individual VU requirements and calculates the total VU requirements for each moment in the test execution.

func (ScenarioConfigs) GetSortedConfigs 

func (scs ScenarioConfigs) GetSortedConfigs() []ExecutorConfig

GetSortedConfigs returns a slice with the executor configurations, sorted in a consistent and predictable manner. It is useful when we want or have to avoid using maps with string keys (and tons of string lookups in them) and avoid the unpredictable iterations over Go maps. Slices allow us constant-time lookups and ordered iterations.

The configs in the returned slice will be sorted by their start times in an ascending order, and alphabetically by their names (which are unique) if there are ties.

func (*ScenarioConfigs) UnmarshalJSON 

func (scs *ScenarioConfigs) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface in a two-step manner, creating the correct type of configs based on the `type` property.

func (ScenarioConfigs) Validate 

func (scs ScenarioConfigs) Validate() (errors []error)

Validate checks if all of the specified executor options make sense

type ScenarioOptions 

type ScenarioOptions struct {
	Browser map[string]any `json:"browser"`
}

ScenarioOptions are options specific to a scenario. These include k6 browser options, which are validated by the browser module, and not by k6 core.

type ScenarioState 

type ScenarioState struct {
	Name, Executor string
	StartTime      time.Time
	ProgressFn     func() (float64, []string)
}

ScenarioState holds runtime scenario information returned by the k6/execution JS module.

func GetScenarioState 

func GetScenarioState(ctx context.Context) *ScenarioState

GetScenarioState returns a ScenarioState from ctx.

type SegmentedIndex 

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

SegmentedIndex is an iterator that returns both the scaled and the unscaled sequential values according to the given ExecutionTuple. It is not thread-safe, concurrent access has to be externally synchronized.

See the documentation for ExecutionTuple above for a visual explanation of how this iterator actually works.

func NewSegmentedIndex 

func NewSegmentedIndex(et *ExecutionTuple) *SegmentedIndex

NewSegmentedIndex returns a pointer to a new SegmentedIndex instance, given an ExecutionTuple.

func (*SegmentedIndex) GoTo 

func (s *SegmentedIndex) GoTo(value int64) (int64, int64)

GoTo sets the scaled index to its biggest value for which the corresponding unscaled index is smaller or equal to value.

func (*SegmentedIndex) Next 

func (s *SegmentedIndex) Next() (int64, int64)

Next goes to the next scaled index and moves the unscaled one accordingly.

func (*SegmentedIndex) Prev 

func (s *SegmentedIndex) Prev() (int64, int64)

Prev goes to the previous scaled value and sets the unscaled one accordingly. Calling Prev when s.scaled == 0 is undefined.

type SlotLimiter 

type SlotLimiter chan struct{}

SlotLimiter can restrict the concurrent execution of tasks to the given `slots` limit

func NewSlotLimiter 

func NewSlotLimiter(slots int) SlotLimiter

NewSlotLimiter initializes and returns a new SlotLimiter with the given slot count

func (SlotLimiter) Begin 

func (sl SlotLimiter) Begin()

Begin uses up a slot to denote the start of a task exeuction. It's a noop if the number of slots is 0, and if no slots are available, it blocks and waits.

func (SlotLimiter) End 

func (sl SlotLimiter) End()

End restores a slot and should be called at the end of a taks execution, preferably from a defer statement right after Begin()

type Stage 

type Stage StageFields

A Stage defines a step in a test's timeline.

func (Stage) MarshalJSON 

func (s Stage) MarshalJSON() ([]byte, error)

func (*Stage) UnmarshalJSON 

func (s *Stage) UnmarshalJSON(b []byte) error

For some reason, implementing UnmarshalText makes encoding/json treat the type as a string.

func (*Stage) UnmarshalText 

func (s *Stage) UnmarshalText(b []byte) error

type StageFields 

type StageFields struct {
	// Duration of the stage.
	Duration types.NullDuration `json:"duration"`

	// If Valid, the VU count will be linearly interpolated towards this value.
	Target null.Int `json:"target"`
}

StageFields defines the fields used for a Stage; this is a dumb hack to make the JSON code cleaner. pls fix.

type State 

type State struct {
	// Global options and built-in metrics.
	//
	// TODO: remove them from here, the built-in metrics and the script options
	// are not part of a VU's unique "state", they are global and the same for
	// all VUs. Figure out how to thread them some other way, e.g. through the
	// TestPreInitState. The Samples channel might also benefit from that...
	Options        Options
	BuiltinMetrics *metrics.BuiltinMetrics

	// Logger instance for every VU.
	Logger logrus.FieldLogger

	// Current group; all emitted metrics are tagged with this.
	Group *Group

	// Networking equipment.
	Dialer DialContexter

	// TODO: move a lot of the things below to the k6/http ModuleInstance, see
	// https://github.com/grafana/k6/issues/2293.
	Transport http.RoundTripper
	CookieJar *cookiejar.Jar
	TLSConfig *tls.Config

	// Rate limits.
	RPSLimit *rate.Limiter

	// Sample channel, possibly buffered
	Samples chan<- metrics.SampleContainer

	// Buffer pool; use instead of allocating fresh buffers when possible.
	BufferPool *BufferPool

	VUID, VUIDGlobal uint64
	Iteration        int64

	// TODO: rename this field with one more representative
	// because it includes now also the metadata.
	Tags *VUStateTags

	// These will be assigned on VU activation.
	// Returns the iteration number of this VU in the current scenario.
	GetScenarioVUIter func() uint64
	// Returns the iteration number across all VUs in the current scenario
	// unique to this single k6 instance.
	// TODO: Maybe this doesn't belong here but in ScenarioState?
	GetScenarioLocalVUIter func() uint64
	// Returns the iteration number across all VUs in the current scenario
	// unique globally across k6 instances (taking into account execution
	// segments).
	GetScenarioGlobalVUIter func() uint64
}

State provides the volatile state for a VU.

TODO: rename to VUState or, better yet, move to some other Go package outside of lib/, where it's more obvious that this is the VU state.

type Summary 

type Summary struct {
	Metrics         map[string]*metrics.Metric
	RootGroup       *Group
	TestRunDuration time.Duration // TODO: use lib.ExecutionState-based interface instead?
	NoColor         bool          // TODO: drop this when noColor is part of the (runtime) options
	UIState         UIState
}

Summary contains all of the data the summary handler gets.

type TLSAuth 

type TLSAuth struct {
	TLSAuthFields
	// contains filtered or unexported fields
}

Defines a TLS client certificate to present to certain hosts.

func (*TLSAuth) Certificate 

func (c *TLSAuth) Certificate() (*tls.Certificate, error)

func (*TLSAuth) UnmarshalJSON 

func (c *TLSAuth) UnmarshalJSON(data []byte) error

type TLSAuthFields 

type TLSAuthFields struct {
	// Certificate and key as a PEM-encoded string, including "-----BEGIN CERTIFICATE-----".
	Cert     string      `json:"cert"`
	Key      string      `json:"key"`
	Password null.String `json:"password"`

	// Domains to present the certificate to. May contain wildcards, eg. "*.example.com".
	Domains []string `json:"domains"`
}

Fields for TLSAuth. Unmarshalling hack.

type TLSCipherSuites 

type TLSCipherSuites []uint16

A list of TLS cipher suites. Marshals and unmarshals from a list of names, eg. "TLS_ECDHE_RSA_WITH_RC4_128_SHA".

func (*TLSCipherSuites) MarshalJSON 

func (s *TLSCipherSuites) MarshalJSON() ([]byte, error)

MarshalJSON will return the JSON representation according to supported TLS cipher suites

func (*TLSCipherSuites) UnmarshalJSON 

func (s *TLSCipherSuites) UnmarshalJSON(data []byte) error

type TLSVersion 

type TLSVersion int

Describes a TLS version. Serialised to/from JSON as a string, eg. "tls1.2".

func (TLSVersion) MarshalJSON 

func (v TLSVersion) MarshalJSON() ([]byte, error)

func (*TLSVersion) UnmarshalJSON 

func (v *TLSVersion) UnmarshalJSON(data []byte) error

type TLSVersions 

type TLSVersions TLSVersionsFields

Describes a set (min/max) of TLS versions.

func (*TLSVersions) UnmarshalJSON 

func (v *TLSVersions) UnmarshalJSON(data []byte) error

type TLSVersionsFields 

type TLSVersionsFields struct {
	Min TLSVersion `json:"min" ignored:"true"` // Minimum allowed version, 0 = any.
	Max TLSVersion `json:"max" ignored:"true"` // Maximum allowed version, 0 = any.
}

Fields for TLSVersions. Unmarshalling hack.

type TestPreInitState 

type TestPreInitState struct {
	RuntimeOptions RuntimeOptions
	Registry       *metrics.Registry
	BuiltinMetrics *metrics.BuiltinMetrics
	Events         *event.System
	KeyLogger      io.Writer
	LookupEnv      func(key string) (val string, ok bool)
	Logger         logrus.FieldLogger
}

TestPreInitState contains all of the state that can be gathered and built before the test run is initialized.

type TestRunState 

type TestRunState struct {
	*TestPreInitState

	Options Options
	Runner  Runner // TODO: rename to something better, see type comment
	RunTags *metrics.TagSet
}

TestRunState contains the pre-init state as well as all of the state and options that are necessary for actually running the test.

type UIState 

type UIState struct {
	IsStdOutTTY bool
	IsStdErrTTY bool
}

UIState describes the state of the UI, which might influence what handleSummary() returns.

type VUActivationParams 

type VUActivationParams struct {
	RunContext               context.Context
	DeactivateCallback       func(InitializedVU)
	Env, Tags                map[string]string
	Exec, Scenario           string
	GetNextIterationCounters func() (uint64, uint64)
}

VUActivationParams are supplied by each executor when it retrieves a VU from the buffer pool and activates it for use.

type VUStateTags 

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

VUStateTags wraps the current VU's tags and ensures a thread-safe way to access and modify them exists. This is necessary because the VU tags and metadata can be modified from the JS scripts via the `vu.tags` API in the `k6/execution` built-in module.

func NewVUStateTags 

func NewVUStateTags(tags *metrics.TagSet) *VUStateTags

NewVUStateTags initializes a new VUStateTags and returns it. It's important that tags is not nil and initialized via metrics.Registry.RootTagSet().

func (*VUStateTags) GetCurrentValues 

func (tg *VUStateTags) GetCurrentValues() metrics.TagsAndMeta

GetCurrentValues returns the current value of the VU tags and a copy of the metadata (if any) in a thread-safe way.

func (*VUStateTags) Modify 

func (tg *VUStateTags) Modify(callback func(tagsAndMeta *metrics.TagsAndMeta))

Modify allows the thread-safe modification of the current VU tags and metadata.

Source Files

View all Source files

Directories

Path Synopsis
Package fsext provides extended file system functions
 Package fsext provides extended file system functions
grpcext
Package grpcext allows gRPC requests collecting stats info.
 Package grpcext allows gRPC requests collecting stats info.
httpext
httpmultibin
Package httpmultibin is indended only for use in tests, do not import in production code!
 Package httpmultibin is indended only for use in tests, do not import in production code!
httpmultibin/grpc_any_testing
httpmultibin/grpc_testing
minirunner
mockoutput
mockresolver
Package types contains types used in the codebase Most of the types have a Null prefix like gopkg.in/guregu/null.v3 and UnmarshalJSON and MarshalJSON methods.
 Package types contains types used in the codebase Most of the types have a Null prefix like gopkg.in/guregu/null.v3 and UnmarshalJSON and MarshalJSON methods.

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.