output

Documentation

Overview

Package output contains the interfaces that k6 outputs (and output extensions) have to implement, as well as some helpers to make their implementation and management easier.

Index

• func GetExtensions() map[string]func(Params) (Output, error)
• func RegisterExtension(name string, mod func(Params) (Output, error))
• type Manager
  • func NewManager(outputs []Output, logger logrus.FieldLogger, testStopCallback func(error)) *Manager
  • func (om *Manager) AddMetricSamples(sampleContainers []metrics.SampleContainer)
  • func (om *Manager) SetRunStatus(status lib.RunStatus)
  • func (om *Manager) StartOutputs() error
  • func (om *Manager) StopOutputs()
• type Output
• type Params
• type PeriodicFlusher
  • func NewPeriodicFlusher(period time.Duration, flushCallback func()) (*PeriodicFlusher, error)
  • func (pf *PeriodicFlusher) Stop()
• type SampleBuffer
  • func (sc *SampleBuffer) AddMetricSamples(samples []metrics.SampleContainer)
  • func (sc *SampleBuffer) GetBufferedSamples() []metrics.SampleContainer
• type WithBuiltinMetrics
• type WithRunStatusUpdates
• type WithTestRunStop
• type WithThresholds

Functions

func GetExtensions

func GetExtensions() map[string]func(Params) (Output, error)

GetExtensions returns all registered extensions.

func RegisterExtension

func RegisterExtension(name string, mod func(Params) (Output, error))

RegisterExtension registers the given output extension constructor. This function panics if a module with the same name is already registered.

Types

type Manager

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

Manager can be used to manage multiple outputs at the same time.

func NewManager

func NewManager(outputs []Output, logger logrus.FieldLogger, testStopCallback func(error)) *Manager

NewManager returns a new manager for the given outputs.

func (*Manager) AddMetricSamples

func (om *Manager) AddMetricSamples(sampleContainers []metrics.SampleContainer)

AddMetricSamples is a temporary method to make the Manager usable in the current Engine. It needs to be replaced with the full metric pump.

TODO: refactor

func (*Manager) SetRunStatus

func (om *Manager) SetRunStatus(status lib.RunStatus)

SetRunStatus checks which outputs implement the WithRunStatusUpdates interface and sets the provided RunStatus to them.

func (*Manager) StartOutputs

func (om *Manager) StartOutputs() error

StartOutputs spins up all configured outputs. If some output fails to start, it stops the already started ones. This may take some time, since some outputs make initial network requests to set up whatever remote services are going to listen to them.

func (*Manager) StopOutputs

func (om *Manager) StopOutputs()

StopOutputs stops all configured outputs.

type Output

type Output interface {
	// Returns a human-readable description of the output that will be shown in
	// `k6 run`. For extensions it probably should include the version as well.
	Description() string

	// Start is called before the Engine tries to use the output and should be
	// used for any long initialization tasks, as well as for starting a
	// goroutine to asynchronously flush metrics to the output.
	Start() error

	// A method to receive the latest metric samples from the Engine. This
	// method is never called concurrently, so do not do anything blocking here
	// that might take a long time. Preferably, just use the SampleBuffer or
	// something like it to buffer metrics until they are flushed.
	AddMetricSamples(samples []metrics.SampleContainer)

	// Flush all remaining metrics and finalize the test run.
	Stop() error
}

An Output abstracts the process of funneling samples to an external storage backend, such as a file or something like an InfluxDB instance.

N.B: All outputs should have non-blocking AddMetricSamples() methods and should spawn their own goroutine to flush metrics asynchronously.

type Params

type Params struct {
	OutputType     string // --out $OutputType=$ConfigArgument, K6_OUT="$OutputType=$ConfigArgument"
	ConfigArgument string
	JSONConfig     json.RawMessage

	Logger         logrus.FieldLogger
	Environment    map[string]string
	StdOut         io.Writer
	StdErr         io.Writer
	FS             afero.Fs
	ScriptPath     *url.URL
	ScriptOptions  lib.Options
	RuntimeOptions lib.RuntimeOptions
	ExecutionPlan  []lib.ExecutionStep
}

Params contains all possible constructor parameters an output may need.

type PeriodicFlusher

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

PeriodicFlusher is a small helper for asynchronously flushing buffered metric samples on regular intervals. The biggest benefit is having a Stop() method that waits for one last flush before it returns.

func NewPeriodicFlusher

func NewPeriodicFlusher(period time.Duration, flushCallback func()) (*PeriodicFlusher, error)

NewPeriodicFlusher creates a new PeriodicFlusher and starts its goroutine.

func (*PeriodicFlusher) Stop

func (pf *PeriodicFlusher) Stop()

Stop waits for the periodic flusher flush one last time and exit. You can safely call Stop() multiple times from different goroutines, you just can't call it from inside of the flushing function.

type SampleBuffer

type SampleBuffer struct {
	sync.Mutex
	// contains filtered or unexported fields
}

SampleBuffer is a simple thread-safe buffer for metric samples. It should be used by most outputs, since we generally want to flush metric samples to the remote service asynchronously. We want to do it only every several seconds, and we don't want to block the Engine in the meantime.

func (*SampleBuffer) AddMetricSamples

func (sc *SampleBuffer) AddMetricSamples(samples []metrics.SampleContainer)

AddMetricSamples adds the given metric samples to the internal buffer.

func (*SampleBuffer) GetBufferedSamples

func (sc *SampleBuffer) GetBufferedSamples() []metrics.SampleContainer

GetBufferedSamples returns the currently buffered metric samples and makes a new internal buffer with some hopefully realistic size. If the internal buffer is empty, it will return nil.

type WithBuiltinMetrics

type WithBuiltinMetrics interface {
	Output
	SetBuiltinMetrics(builtinMetrics *metrics.BuiltinMetrics)
}

WithBuiltinMetrics means the output can receive the builtin metrics.

type WithRunStatusUpdates

type WithRunStatusUpdates interface {
	Output
	SetRunStatus(latestStatus lib.RunStatus)
}

WithRunStatusUpdates means the output can receive test run status updates.

type WithTestRunStop

type WithTestRunStop interface {
	Output
	SetTestRunStopCallback(func(error))
}

WithTestRunStop is an output that can stop the Engine mid-test, interrupting the whole test run execution if some internal condition occurs, completely independently from the thresholds. It requires a callback function which expects an error and triggers the Engine to stop.

type WithThresholds

type WithThresholds interface {
	Output
	SetThresholds(map[string]metrics.Thresholds)
}

WithThresholds is an output that requires the Engine to give it the thresholds before it can be started.