Documentation ¶
Overview ¶
Package runtime contains functions and types to interact with the test runtime environment, as formally defined in the system specification.
Index ¶
- Constants
- Variables
- func Invoke(tc TestCaseFn)
- func InvokeMap(cases map[string]TestCaseFn)
- func NewInfluxDBClient(re *RunEnv) (client.Client, error)
- func ParseKeyValues(in []string) (res map[string]string, err error)
- func StandardJSONConfig() zap.Config
- type Batcher
- type Counter
- type EWMA
- type Event
- type EventOutcome
- type EventType
- type Gauge
- type Histogram
- type IPNet
- type Meter
- type Metric
- type MetricSinkFn
- type MetricType
- type Metrics
- type MetricsApi
- func (m *MetricsApi) Close() error
- func (m *MetricsApi) Counter(name string) Counter
- func (m *MetricsApi) EWMA(name string, alpha float64) EWMA
- func (m *MetricsApi) Gauge(name string) Gauge
- func (m *MetricsApi) GaugeF(name string, f func() float64) Gauge
- func (m *MetricsApi) Histogram(name string, s Sample) Histogram
- func (m *MetricsApi) Meter(name string) Meter
- func (m *MetricsApi) NewExpDecaySample(reservoirSize int, alpha float64) Sample
- func (m *MetricsApi) NewUniformSample(reservoirSize int) Sample
- func (m *MetricsApi) RecordPoint(name string, value float64)
- func (m *MetricsApi) ResettingHistogram(name string) Histogram
- func (m *MetricsApi) SetFrequency(freq time.Duration)
- func (m *MetricsApi) Timer(name string) Timer
- type Point
- type RunEnv
- func (re *RunEnv) Close() error
- func (re *RunEnv) CreateRandomDirectory(directoryPath string, depth uint) (string, error)
- func (re *RunEnv) CreateRandomFile(directoryPath string, size int64) (string, error)
- func (re *RunEnv) CreateRawAsset(name string) (*os.File, error)
- func (re *RunEnv) CreateStructuredAsset(name string, config zap.Config) (*zap.Logger, *zap.SugaredLogger, error)
- func (re *RunEnv) D() *MetricsApi
- func (re *RunEnv) HTTPPeriodicSnapshots(ctx context.Context, addr string, dur time.Duration, outDir string) error
- func (re *RunEnv) R() *MetricsApi
- func (re *RunEnv) RecordCrash(err interface{})
- func (re *RunEnv) RecordFailure(err error)
- func (re *RunEnv) RecordMessage(msg string, a ...interface{})
- func (re *RunEnv) RecordStart()
- func (re *RunEnv) RecordSuccess()
- func (re *RunEnv) SLogger() *zap.SugaredLogger
- type RunParams
- func (rp *RunParams) BooleanParam(name string) bool
- func (rp *RunParams) FloatParam(name string) float64
- func (rp *RunParams) IntParam(name string) int
- func (rp *RunParams) IsParamSet(name string) bool
- func (rp *RunParams) JSONParam(name string, v interface{})
- func (rp *RunParams) MarshalLogObject(oe zapcore.ObjectEncoder) error
- func (rp *RunParams) SizeArrayParam(name string) []uint64
- func (rp *RunParams) SizeParam(name string) uint64
- func (rp *RunParams) StringArrayParam(name string) []string
- func (rp *RunParams) StringParam(name string) string
- func (rp *RunParams) ToEnvVars() map[string]string
- type Sample
- type TestCaseFn
- type Timer
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 ( // These ports are the HTTP ports we'll attempt to bind to. If this instance // is running in a Docker container, binding to 6060 is safe. If it's a // local:exec run, these ports belong to the host, so starting more than one // instance will lead to a collision. Therefore we fallback to 0. HTTPPort = 6060 HTTPPortFallback = 0 )
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 HTTPListenAddr string
HTTPListenAddr will be set to the listener address _before_ the test case is invoked. If we were unable to start the listener, this value will be "".
var ( // TestInfluxDBClient sets a client for testing. If this value is set, // NewInfluxDBClient will always return it. TestInfluxDBClient client.Client )
Functions ¶
func InvokeMap ¶
func InvokeMap(cases map[string]TestCaseFn)
InvokeMap takes a map of test case names and their functions, and calls the matched test case, or panics if the name is unrecognised.
func ParseKeyValues ¶
Copied from github.com/ipfs/testground/pkg/conv, because we don't want the SDK to depend on that package.
func StandardJSONConfig ¶
StandardJSONConfig returns a zap.Config with JSON encoding, debug verbosity, caller and stacktraces disabled, and with timestamps encoded as nanos after epoch.
Types ¶
type Counter ¶
type Counter = metrics.Counter
Type aliases to hide implementation details in the APIs.
type EWMA ¶ added in v0.2.0
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 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 Meter ¶ added in v0.2.0
type Meter = metrics.Meter
Type aliases to hide implementation details in the APIs.
type Metric ¶ added in v0.2.0
type Metric struct { Timestamp int64 `json:"ts"` Type MetricType `json:"type"` Name string `json:"name"` Measures map[string]interface{} `json:"measures"` }
type MetricSinkFn ¶ added in v0.2.0
type MetricType ¶ added in v0.2.0
type MetricType int
const ( MetricPoint MetricType = iota MetricCounter MetricEWMA MetricGauge MetricHistogram MetricMeter MetricTimer )
func (MetricType) MarshalJSON ¶ added in v0.2.0
func (mt MetricType) MarshalJSON() ([]byte, error)
func (MetricType) String ¶ added in v0.2.0
func (mt MetricType) String() string
func (*MetricType) UnmarshalJSON ¶ added in v0.2.0
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) D ¶ added in v0.2.0
func (m *Metrics) D() *MetricsApi
func (*Metrics) R ¶ added in v0.2.0
func (m *Metrics) R() *MetricsApi
type MetricsApi ¶ added in v0.2.0
type MetricsApi struct {
// contains filtered or unexported fields
}
func (*MetricsApi) Close ¶ added in v0.2.0
func (m *MetricsApi) Close() error
func (*MetricsApi) Counter ¶ added in v0.2.0
func (m *MetricsApi) Counter(name string) Counter
func (*MetricsApi) EWMA ¶ added in v0.2.0
func (m *MetricsApi) EWMA(name string, alpha float64) EWMA
func (*MetricsApi) Gauge ¶ added in v0.2.0
func (m *MetricsApi) Gauge(name string) Gauge
func (*MetricsApi) GaugeF ¶ added in v0.2.0
func (m *MetricsApi) GaugeF(name string, f func() float64) Gauge
func (*MetricsApi) Histogram ¶ added in v0.2.0
func (m *MetricsApi) Histogram(name string, s Sample) Histogram
func (*MetricsApi) Meter ¶ added in v0.2.0
func (m *MetricsApi) Meter(name string) Meter
func (*MetricsApi) NewExpDecaySample ¶ added in v0.2.0
func (m *MetricsApi) NewExpDecaySample(reservoirSize int, alpha float64) Sample
func (*MetricsApi) NewUniformSample ¶ added in v0.2.0
func (m *MetricsApi) NewUniformSample(reservoirSize int) Sample
func (*MetricsApi) RecordPoint ¶ added in v0.2.0
func (m *MetricsApi) RecordPoint(name string, value float64)
func (*MetricsApi) ResettingHistogram ¶ added in v0.2.2
func (m *MetricsApi) ResettingHistogram(name string) Histogram
func (*MetricsApi) SetFrequency ¶ added in v0.2.0
func (m *MetricsApi) SetFrequency(freq time.Duration)
func (*MetricsApi) Timer ¶ added in v0.2.0
func (m *MetricsApi) Timer(name string) Timer
type Point ¶ added in v0.2.0
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 ParseRunEnv ¶
ParseRunEnv parses a list of environment variables into a RunEnv.
func RandomTestRunEnv ¶ added in v0.2.0
RandomTestRunEnv generates a random RunEnv for testing purposes.
func (*RunEnv) CreateRandomDirectory ¶
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 ¶
CreateRandomFile creates a file of the specified size (in bytes) within the specified directory path and returns its path.
func (*RunEnv) CreateRawAsset ¶
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 ¶ added in v0.2.0
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 ¶ added in v0.2.0
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 ¶
RecordFailure records that the calling instance failed with the supplied error.
func (*RunEnv) RecordMessage ¶
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 ¶
ParseRunParams parses a list of environment variables into a RunParams.
func (*RunParams) BooleanParam ¶
BooleanParam returns the Boolean value of the parameter, or false if not passed
func (*RunParams) FloatParam ¶ added in v0.2.0
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 ¶
IntParam returns an int parameter, or -1 if the parameter is not set or the conversion failed. It panics on error.
func (*RunParams) IsParamSet ¶
IsParamSet checks if a certain parameter is set.
func (*RunParams) JSONParam ¶
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) SizeArrayParam ¶
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) StringArrayParam ¶
StringArrayParam returns an array of string parameter, or an empty array if it does not exist. It panics on error.
func (*RunParams) StringParam ¶
StringParam returns a string parameter, or "" if the parameter is not set.
type Sample ¶ added in v0.2.0
type Sample = metrics.Sample
Type aliases to hide implementation details in the APIs.