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 RegisterExtension(name string, c Constructor)
• type Constructor
• type Manager
  • func NewManager(outputs []Output, logger logrus.FieldLogger, testStopCallback func(error)) *Manager
  • func (om *Manager) Start(samplesChan chan metrics.SampleContainer) (wait func(), finish func(error), err error)
• 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 WithStopWithTestError
• type WithTestRunStop
• type WithThresholds

Functions

func RegisterExtension

func RegisterExtension(name string, c Constructor)

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

Types

type Constructor

type Constructor func(Params) (Output, error)

Constructor returns an instance of an output extension module.

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

func (om *Manager) Start(samplesChan chan metrics.SampleContainer) (wait func(), finish func(error), err error)

Start spins up all configured outputs and then starts a new goroutine that pipes metrics from the given samples channel to them.

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.

If all outputs start successfully, this method will return 2 callbacks. The first one, wait(), will block until the samples channel has been closed and all of its buffered metrics have been sent to all outputs. The second callback will call the Stop() or StopWithTestError() method of every output.

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             fsext.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 WithStopWithTestError

type WithStopWithTestError interface {
	Output
	StopWithTestError(testRunErr error) error // nil testRunErr means error-free test run
}

WithStopWithTestError allows output to receive the error value that the test finished with. It could be nil, if the test finished normally.

If this interface is implemented by the output, StopWithError() will be called instead of Stop().

TODO: refactor the main interface to use this method instead of Stop()? Or something else along the lines of https://github.com/grafana/k6/issues/2430 ?

type WithTestRunStop

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

WithTestRunStop is an output that can stop the test run mid-way through, 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.