Back to godoc.org

Package runtime

v0.2.3
Latest Go to latest
Published: Jul 21, 2020 | Licenses: Apache-2.0 , MIT | Module: github.com/testground/sdk-go

Overview

Package runtime contains functions and types to interact with the test runtime environment, as formally defined in the system specification.

Index

Package Files

Constants

const (
	EnvTestBranch             = "TEST_BRANCH"
	EnvTestCase               = "TEST_CASE"
	EnvTestGroupID            = "TEST_GROUP_ID"
	EnvTestGroupInstanceCount = "TEST_GROUP_INSTANCE_COUNT"
	EnvTestInstanceCount      = "TEST_INSTANCE_COUNT"
	EnvTestInstanceParams     = "TEST_INSTANCE_PARAMS"
	EnvTestInstanceRole       = "TEST_INSTANCE_ROLE"
	EnvTestOutputsPath        = "TEST_OUTPUTS_PATH"
	EnvTestPlan               = "TEST_PLAN"
	EnvTestRepo               = "TEST_REPO"
	EnvTestRun                = "TEST_RUN"
	EnvTestSidecar            = "TEST_SIDECAR"
	EnvTestStartTime          = "TEST_START_TIME"
	EnvTestSubnet             = "TEST_SUBNET"
	EnvTestTag                = "TEST_TAG"
)
const (
	EventTypeStart   = EventType("start")
	EventTypeMessage = EventType("message")
	EventTypeFinish  = EventType("finish")

	EventOutcomeOK      = EventOutcome("ok")
	EventOutcomeFailed  = EventOutcome("failed")
	EventOutcomeCrashed = EventOutcome("crashed")
)
const EnvInfluxDBURL = "INFLUXDB_URL"
const InitialResettingHistogramSliceCap = 10

Initial slice capacity for the values stored in a ResettingHistogram

Variables

var (
	InfluxBatching       = true
	InfluxBatchLength    = 128
	InfluxBatchInterval  = 1 * time.Second
	InfluxBatchRetryOpts = func(re *RunEnv) []retry.Option {
		return []retry.Option{
			retry.Attempts(5),
			retry.Delay(500 * time.Millisecond),
			retry.OnRetry(func(n uint, err error) {
				re.RecordMessage("failed to send batch to InfluxDB; attempt %d; err: %s", n, err)
			}),
		}
	}
)
var (
	// TestInfluxDBClient sets a client for testing. If this value is set,
	// NewInfluxDBClient will always return it.
	TestInfluxDBClient client.Client
)

func NewInfluxDBClient

func NewInfluxDBClient(re *RunEnv) (client.Client, error)

func ParseKeyValues

func ParseKeyValues(in []string) (res map[string]string, err error)

Copied from github.com/ipfs/testground/pkg/conv, because we don't want the SDK to depend on that package.

func StandardJSONConfig

func StandardJSONConfig() zap.Config

StandardJSONConfig returns a zap.Config with JSON encoding, debug verbosity, caller and stacktraces disabled, and with timestamps encoded as nanos after epoch.

type Batcher

type Batcher interface {
	io.Closer

	WritePoint(p *client.Point)
}

type Counter

type Counter = metrics.Counter

Type aliases to hide implementation details in the APIs.

type EWMA

type EWMA = metrics.EWMA

Type aliases to hide implementation details in the APIs.

type Event

type Event struct {
	Type       EventType    `json:"type"`
	Outcome    EventOutcome `json:"outcome,omitempty"`
	Error      string       `json:"error,omitempty"`
	Stacktrace string       `json:"stacktrace,omitempty"`
	Message    string       `json:"message,omitempty"`
	Runenv     *RunParams   `json:"runenv,omitempty"`
}

func (Event) MarshalLogObject

func (e Event) MarshalLogObject(oe zapcore.ObjectEncoder) error

type EventOutcome

type EventOutcome string

type EventType

type EventType string

type Gauge

type Gauge = metrics.GaugeFloat64

Type aliases to hide implementation details in the APIs.

type Histogram

type Histogram = metrics.Histogram

Type aliases to hide implementation details in the APIs.

type IPNet

type IPNet struct {
	net.IPNet
}

func (IPNet) MarshalJSON

func (i IPNet) MarshalJSON() ([]byte, error)

func (*IPNet) UnmarshalJSON

func (i *IPNet) UnmarshalJSON(data []byte) error

type Meter

type Meter = metrics.Meter

Type aliases to hide implementation details in the APIs.

type Metric

type Metric struct {
	Timestamp int64                  `json:"ts"`
	Type      MetricType             `json:"type"`
	Name      string                 `json:"name"`
	Measures  map[string]interface{} `json:"measures"`
}

func NewMetric

func NewMetric(name string, i interface{}) *Metric

func (*Metric) Release

func (m *Metric) Release()

type MetricSinkFn

type MetricSinkFn func(m *Metric) error

type MetricType

type MetricType int
const (
	MetricPoint MetricType = iota
	MetricCounter
	MetricEWMA
	MetricGauge
	MetricHistogram
	MetricMeter
	MetricTimer
)

func (MetricType) MarshalJSON

func (mt MetricType) MarshalJSON() ([]byte, error)

func (MetricType) String

func (mt MetricType) String() string

func (*MetricType) UnmarshalJSON

func (mt *MetricType) UnmarshalJSON(b []byte) error

UnmarshalJSON is only used for testing; it's inefficient but not relevant.

type Metrics

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

func (*Metrics) Close

func (m *Metrics) Close() error

func (*Metrics) D

func (m *Metrics) D() *MetricsApi

func (*Metrics) R

func (m *Metrics) R() *MetricsApi

type MetricsApi

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

func (*MetricsApi) Close

func (m *MetricsApi) Close() error

func (*MetricsApi) Counter

func (m *MetricsApi) Counter(name string) Counter

func (*MetricsApi) EWMA

func (m *MetricsApi) EWMA(name string, alpha float64) EWMA

func (*MetricsApi) Gauge

func (m *MetricsApi) Gauge(name string) Gauge

func (*MetricsApi) GaugeF

func (m *MetricsApi) GaugeF(name string, f func() float64) Gauge

func (*MetricsApi) Histogram

func (m *MetricsApi) Histogram(name string, s Sample) Histogram

func (*MetricsApi) Meter

func (m *MetricsApi) Meter(name string) Meter

func (*MetricsApi) NewExpDecaySample

func (m *MetricsApi) NewExpDecaySample(reservoirSize int, alpha float64) Sample

func (*MetricsApi) NewUniformSample

func (m *MetricsApi) NewUniformSample(reservoirSize int) Sample

func (*MetricsApi) RecordPoint

func (m *MetricsApi) RecordPoint(name string, value float64)

func (*MetricsApi) ResettingHistogram

func (m *MetricsApi) ResettingHistogram(name string) Histogram

func (*MetricsApi) SetFrequency

func (m *MetricsApi) SetFrequency(freq time.Duration)

func (*MetricsApi) Timer

func (m *MetricsApi) Timer(name string) Timer

type Point

type Point float64

Type aliases to hide implementation details in the APIs.

type RunEnv

type RunEnv struct {
	RunParams
	// contains filtered or unexported fields
}

RunEnv encapsulates the context for this test run.

func CurrentRunEnv

func CurrentRunEnv() *RunEnv

CurrentRunEnv populates a test context from environment vars.

func NewRunEnv

func NewRunEnv(params RunParams) *RunEnv

NewRunEnv constructs a runtime environment from the given runtime parameters.

func ParseRunEnv

func ParseRunEnv(env []string) (*RunEnv, error)

ParseRunEnv parses a list of environment variables into a RunEnv.

func RandomTestRunEnv

func RandomTestRunEnv(t *testing.T) (re *RunEnv, cleanup func())

RandomTestRunEnv generates a random RunEnv for testing purposes.

func (*RunEnv) Close

func (re *RunEnv) Close() error

func (*RunEnv) CreateRandomDirectory

func (re *RunEnv) CreateRandomDirectory(directoryPath string, depth uint) (string, error)

CreateRandomDirectory creates a nested directory with the specified depth within the specified directory path. If depth is zero, the directory path is returned.

func (*RunEnv) CreateRandomFile

func (re *RunEnv) CreateRandomFile(directoryPath string, size int64) (string, error)

CreateRandomFile creates a file of the specified size (in bytes) within the specified directory path and returns its path.

func (*RunEnv) CreateRawAsset

func (re *RunEnv) CreateRawAsset(name string) (*os.File, error)

CreateRawAsset creates an output asset.

Output assets will be saved when the test terminates and available for further investigation. You can also manually create output assets/directories under re.TestOutputsPath.

func (*RunEnv) CreateStructuredAsset

func (re *RunEnv) CreateStructuredAsset(name string, config zap.Config) (*zap.Logger, *zap.SugaredLogger, error)

CreateStructuredAsset creates an output asset and wraps it in zap loggers.

func (*RunEnv) D

func (re *RunEnv) D() *MetricsApi

D returns a metrics object for diagnostics.

func (*RunEnv) HTTPPeriodicSnapshots

func (re *RunEnv) HTTPPeriodicSnapshots(ctx context.Context, addr string, dur time.Duration, outDir string) error

HTTPPeriodicSnapshots periodically fetches the snapshots from the given address and outputs them to the out directory. Every file will be in the format timestamp.out.

func (*RunEnv) R

func (re *RunEnv) R() *MetricsApi

R returns a metrics object for results.

func (*RunEnv) RecordCrash

func (re *RunEnv) RecordCrash(err interface{})

RecordCrash records that the calling instance crashed/panicked with the supplied error.

func (*RunEnv) RecordFailure

func (re *RunEnv) RecordFailure(err error)

RecordFailure records that the calling instance failed with the supplied error.

func (*RunEnv) RecordMessage

func (re *RunEnv) RecordMessage(msg string, a ...interface{})

RecordMessage records an informational message.

func (*RunEnv) RecordStart

func (re *RunEnv) RecordStart()

func (*RunEnv) RecordSuccess

func (re *RunEnv) RecordSuccess()

RecordSuccess records that the calling instance succeeded.

func (*RunEnv) SLogger

func (re *RunEnv) SLogger() *zap.SugaredLogger

type RunParams

type RunParams struct {
	TestPlan string `json:"plan"`
	TestCase string `json:"case"`
	TestRun  string `json:"run"`

	TestRepo   string `json:"repo,omitempty"`
	TestCommit string `json:"commit,omitempty"`
	TestBranch string `json:"branch,omitempty"`
	TestTag    string `json:"tag,omitempty"`

	TestOutputsPath string `json:"outputs_path,omitempty"`

	TestInstanceCount  int               `json:"instances"`
	TestInstanceRole   string            `json:"role,omitempty"`
	TestInstanceParams map[string]string `json:"params,omitempty"`

	TestGroupID            string `json:"group,omitempty"`
	TestGroupInstanceCount int    `json:"group_instances,omitempty"`

	// true if the test has access to the sidecar.
	TestSidecar bool `json:"test_sidecar,omitempty"`

	// The subnet on which this test is running.
	//
	// The test instance can use this to pick an IP address and/or determine
	// the "data" network interface.
	//
	// This will be 127.1.0.0/16 when using the local exec runner.
	TestSubnet    *IPNet    `json:"network,omitempty"`
	TestStartTime time.Time `json:"start_time,omitempty"`
}

RunParams encapsulates the runtime parameters for this test.

func ParseRunParams

func ParseRunParams(env []string) (*RunParams, error)

ParseRunParams parses a list of environment variables into a RunParams.

func (*RunParams) BooleanParam

func (rp *RunParams) BooleanParam(name string) bool

BooleanParam returns the Boolean value of the parameter, or false if not passed

func (*RunParams) FloatParam

func (rp *RunParams) FloatParam(name string) float64

FloatParam returns a float64 parameter, or -1.0 if the parameter is not set or the conversion failed. It panics on error.

func (*RunParams) IntParam

func (rp *RunParams) IntParam(name string) int

IntParam returns an int parameter, or -1 if the parameter is not set or the conversion failed. It panics on error.

func (*RunParams) IsParamSet

func (rp *RunParams) IsParamSet(name string) bool

IsParamSet checks if a certain parameter is set.

func (*RunParams) JSONParam

func (rp *RunParams) JSONParam(name string, v interface{})

JSONParam unmarshals a JSON parameter in an arbitrary interface. It panics on error.

func (*RunParams) MarshalLogObject

func (rp *RunParams) MarshalLogObject(oe zapcore.ObjectEncoder) error

func (*RunParams) PortNumber

func (rp *RunParams) PortNumber(label string, def string) string

PortNumber returns the port number assigned to the provided label, or falls back to the default value if none is assigned.

TODO: we're getting this directly from an environment variable. We may want

to unpack in RunParams first.

func (*RunParams) SizeArrayParam

func (rp *RunParams) SizeArrayParam(name string) []uint64

SizeArrayParam returns an array of uint64 elements which represent sizes, in bytes. If the response is nil, then there was an error parsing the input. It panics on error.

func (*RunParams) SizeParam

func (rp *RunParams) SizeParam(name string) uint64

func (*RunParams) StringArrayParam

func (rp *RunParams) StringArrayParam(name string) []string

StringArrayParam returns an array of string parameter, or an empty array if it does not exist. It panics on error.

func (*RunParams) StringParam

func (rp *RunParams) StringParam(name string) string

StringParam returns a string parameter, or "" if the parameter is not set.

func (*RunParams) ToEnvVars

func (rp *RunParams) ToEnvVars() map[string]string

type Sample

type Sample = metrics.Sample

Type aliases to hide implementation details in the APIs.

type Timer

type Timer = metrics.Timer

Type aliases to hide implementation details in the APIs.

Documentation was rendered with GOOS=linux and GOARCH=amd64.

Jump to identifier

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to identifier