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 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 CrashEvent
- type EWMA
- type Event
- type FailureEvent
- type Gauge
- type Histogram
- type MessageEvent
- 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 NilSignalEmitter
- type Point
- type RunEnv
- func (re *RunEnv) AttachSyncClient(se SignalEmitter)
- 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) PortNumber(label string, def string) string
- 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 SignalEmitter
- type StageEndEvent
- type StageStartEvent
- type StartEvent
- type SuccessEvent
- 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 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 )
Functions ¶
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 CrashEvent ¶ added in v0.2.6
type CrashEvent struct { TestGroupID string `json:"group"` Error string `json:"error"` Stacktrace string `json:"stacktrace"` }
func (CrashEvent) MarshalLogObject ¶ added in v0.2.6
func (c CrashEvent) MarshalLogObject(oe zapcore.ObjectEncoder) error
func (CrashEvent) Type ¶ added in v0.2.6
func (CrashEvent) Type() string
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 { *StartEvent `json:"start_event,omitempty"` *MessageEvent `json:"message_event,omitempty"` *SuccessEvent `json:"success_event,omitempty"` *FailureEvent `json:"failure_event,omitempty"` *CrashEvent `json:"crash_event,omitempty"` *StageStartEvent `json:"stage_start_event,omitempty"` *StageEndEvent `json:"stage_end_event,omitempty"` }
func (Event) MarshalLogObject ¶
func (e Event) MarshalLogObject(oe zapcore.ObjectEncoder) error
type FailureEvent ¶ added in v0.2.6
func (FailureEvent) MarshalLogObject ¶ added in v0.2.6
func (f FailureEvent) MarshalLogObject(oe zapcore.ObjectEncoder) error
func (FailureEvent) Type ¶ added in v0.2.6
func (FailureEvent) Type() 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 MessageEvent ¶ added in v0.2.6
type MessageEvent struct {
Message string `json:"message"`
}
func (MessageEvent) MarshalLogObject ¶ added in v0.2.6
func (m MessageEvent) MarshalLogObject(oe zapcore.ObjectEncoder) error
func (MessageEvent) Type ¶ added in v0.2.6
func (MessageEvent) Type() string
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
Counter creates a measurement of counter type. The returned type is an alias of go-metrics' Counter type. Refer to godocs there for details.
The format of the metric name is a comma-separated list, where the first element is the metric name, and optionally, an unbounded list of key-value pairs. Example:
requests_received,tag1=value1,tag2=value2,tag3=value3
func (*MetricsApi) EWMA ¶ added in v0.2.0
func (m *MetricsApi) EWMA(name string, alpha float64) EWMA
EWMA creates a measurement of exponential-weighted moving average type. The returned type is an alias of go-metrics' EWMA type. Refer to godocs there for details.
The format of the metric name is a comma-separated list, where the first element is the metric name, and optionally, an unbounded list of key-value pairs. Example:
requests_received,tag1=value1,tag2=value2,tag3=value3
func (*MetricsApi) Gauge ¶ added in v0.2.0
func (m *MetricsApi) Gauge(name string) Gauge
Gauge creates a measurement of gauge type (float64). The returned type is an alias of go-metrics' GaugeFloat64 type. Refer to godocs there for details.
The format of the metric name is a comma-separated list, where the first element is the metric name, and optionally, an unbounded list of key-value pairs. Example:
requests_received,tag1=value1,tag2=value2,tag3=value3
func (*MetricsApi) GaugeF ¶ added in v0.2.0
func (m *MetricsApi) GaugeF(name string, f func() float64) Gauge
GaugeF creates a measurement of functional gauge type (float64). The returned type is an alias of go-metrics' GaugeFloat64 type. Refer to godocs there for details.
The format of the metric name is a comma-separated list, where the first element is the metric name, and optionally, an unbounded list of key-value pairs. Example:
requests_received,tag1=value1,tag2=value2,tag3=value3
func (*MetricsApi) Histogram ¶ added in v0.2.0
func (m *MetricsApi) Histogram(name string, s Sample) Histogram
Histogram creates a measurement of histogram type. The returned type is an alias of go-metrics' Histogram type. Refer to godocs there for details.
The format of the metric name is a comma-separated list, where the first element is the metric name, and optionally, an unbounded list of key-value pairs. Example:
requests_received,tag1=value1,tag2=value2,tag3=value3
func (*MetricsApi) Meter ¶ added in v0.2.0
func (m *MetricsApi) Meter(name string) Meter
Meter creates a measurement of meter type. The returned type is an alias of go-metrics' Meter type. Refer to godocs there for details.
The format of the metric name is a comma-separated list, where the first element is the metric name, and optionally, an unbounded list of key-value pairs. Example:
requests_received,tag1=value1,tag2=value2,tag3=value3
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)
RecordPoint records a float64 point under the provided metric name + tags.
The format of the metric name is a comma-separated list, where the first element is the metric name, and optionally, an unbounded list of key-value pairs. Example:
requests_received,tag1=value1,tag2=value2,tag3=value3
func (*MetricsApi) ResettingHistogram ¶ added in v0.2.2
func (m *MetricsApi) ResettingHistogram(name string) Histogram
ResettingHistogram creates a measurement of histogram type, which cyclically resets to zero when its values are harvested.
The returned type is an alias of go-metrics' Histogram type. Refer to godocs there for details.
The format of the metric name is a comma-separated list, where the first element is the metric name, and optionally, an unbounded list of key-value pairs. Example:
requests_received,tag1=value1,tag2=value2,tag3=value3
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
Timer creates a measurement of timer type. The returned type is an alias of go-metrics' Timer type. Refer to godocs there for details.
The format of the metric name is a comma-separated list, where the first element is the metric name, and optionally, an unbounded list of key-value pairs. Example:
requests_received,tag1=value1,tag2=value2,tag3=value3
type NilSignalEmitter ¶ added in v0.2.6
type NilSignalEmitter struct{}
func (NilSignalEmitter) SignalEvent ¶ added in v0.2.6
func (ne NilSignalEmitter) SignalEvent(ctx context.Context, event *Event) error
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) AttachSyncClient ¶ added in v0.2.6
func (re *RunEnv) AttachSyncClient(se SignalEmitter)
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 *ptypes.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) PortNumber ¶ added in v0.2.3
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 ¶
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.
type SignalEmitter ¶ added in v0.2.6
type StageEndEvent ¶ added in v0.2.6
func (StageEndEvent) MarshalLogObject ¶ added in v0.2.6
func (s StageEndEvent) MarshalLogObject(oe zapcore.ObjectEncoder) error
func (StageEndEvent) Type ¶ added in v0.2.6
func (StageEndEvent) Type() string
type StageStartEvent ¶ added in v0.2.6
func (StageStartEvent) MarshalLogObject ¶ added in v0.2.6
func (s StageStartEvent) MarshalLogObject(oe zapcore.ObjectEncoder) error
func (StageStartEvent) Type ¶ added in v0.2.6
func (StageStartEvent) Type() string
type StartEvent ¶ added in v0.2.6
type StartEvent struct {
Runenv *RunParams `json:"runenv"`
}
func (StartEvent) MarshalLogObject ¶ added in v0.2.6
func (s StartEvent) MarshalLogObject(oe zapcore.ObjectEncoder) error
func (StartEvent) Type ¶ added in v0.2.6
func (StartEvent) Type() string
type SuccessEvent ¶ added in v0.2.6
type SuccessEvent struct {
TestGroupID string `json:"group"`
}
func (SuccessEvent) MarshalLogObject ¶ added in v0.2.6
func (s SuccessEvent) MarshalLogObject(oe zapcore.ObjectEncoder) error
func (SuccessEvent) Type ¶ added in v0.2.6
func (SuccessEvent) Type() string