Documentation
¶
Overview ¶
Package testcost contains the versioned test-cost measurement and ratchet policy used by the repository's Windows quality gate.
Index ¶
- Constants
- Variables
- func BuildQATaggedHotspotsRequest(options MeasureOptions) (taskrunner.Request, error)
- func BuildQualityChecksRequest(options MeasureOptions) (taskrunner.Request, error)
- func BuildTestUnitRequest(options MeasureOptions) (taskrunner.Request, error)
- func EncodeMeasurement(measurement Measurement) ([]byte, error)
- func EncodePolicy(policy Policy) ([]byte, error)
- func EncodeReport(report Report) ([]byte, error)
- func QATaggedHotspotPackages() []string
- func ResolveParallel(value string, cpus int) int
- func ValidateMeasurement(m Measurement) error
- func ValidatePolicy(p Policy) error
- type AbsoluteBudget
- type CompareOptions
- type CostMeasurement
- type CountBudget
- type MeasureOptions
- type Measurement
- type MeasurementResult
- func Measure(ctx context.Context, target string, options MeasureOptions) (MeasurementResult, error)
- func MeasureQATaggedHotspots(ctx context.Context, options MeasureOptions) (MeasurementResult, error)
- func MeasureQualityChecks(ctx context.Context, options MeasureOptions) (MeasurementResult, error)
- func MeasureTestUnit(ctx context.Context, options MeasureOptions) (MeasurementResult, error)
- type OverallComparison
- type OverallPolicy
- type PackageDelta
- type PackageMeasurement
- type PackageMetrics
- type PackagePolicy
- type Policy
- type ProcessAccounting
- type ProcessBudget
- type ProcessMetrics
- type Report
- type RunMeasurement
- type Runner
- type RunnerFunc
- type Snapshot
- type TargetPolicy
- type TestEvent
- type Violation
- type Warning
Constants ¶
const ( TargetTestUnit = "test-unit" TargetQualityChecks = "quality-checks" TargetQATaggedHotspots = "qa-tagged-hotspots" )
const SchemaVersion = 1
Variables ¶
var ( ErrMissingTarget = errors.New("testcost: target is required") ErrUnknownSchema = errors.New("testcost: unknown schema version") ErrInvalidPolicy = errors.New("testcost: invalid policy") ErrMalformedJSON = errors.New("testcost: malformed JSON") ErrAccountingUnsupported = errors.New("testcost: process accounting is unsupported") ErrAccountingFailure = errors.New("testcost: process accounting failed") ErrMeasurementFailed = errors.New("testcost: measurement command failed") ErrWindowsOnly = errors.New("testcost: measurement is Windows-only") ErrUnsupportedTarget = errors.New("testcost: unsupported target") ErrMissingTempRoot = errors.New("testcost: temp root is required") )
Functions ¶
func BuildQATaggedHotspotsRequest ¶
func BuildQATaggedHotspotsRequest(options MeasureOptions) (taskrunner.Request, error)
func BuildQualityChecksRequest ¶
func BuildQualityChecksRequest(options MeasureOptions) (taskrunner.Request, error)
func BuildTestUnitRequest ¶
func BuildTestUnitRequest(options MeasureOptions) (taskrunner.Request, error)
func EncodeMeasurement ¶
func EncodeMeasurement(measurement Measurement) ([]byte, error)
func EncodePolicy ¶
func EncodeReport ¶
func QATaggedHotspotPackages ¶
func QATaggedHotspotPackages() []string
QATaggedHotspotPackages returns a cloned slice of the hotspot package roots.
func ResolveParallel ¶
func ValidateMeasurement ¶
func ValidateMeasurement(m Measurement) error
func ValidatePolicy ¶
Types ¶
type AbsoluteBudget ¶
type AbsoluteBudget struct {
Ratio float64 `json:"ratio"`
DeltaSeconds float64 `json:"delta_seconds"`
}
AbsoluteBudget uses a ratio multiplier and an absolute delta. The effective limit is max(anchor*ratio, anchor+delta).
type CompareOptions ¶
type CompareOptions struct {
AllowOverride bool
}
type CostMeasurement ¶
type CostMeasurement = Measurement
type CountBudget ¶
type MeasureOptions ¶
type Measurement ¶
type Measurement struct {
SchemaVersion int `json:"schema_version"`
Target string `json:"target"`
Revision string `json:"revision"`
GOOS string `json:"goos"`
GOARCH string `json:"goarch"`
GoVersion string `json:"go_version"`
LogicalCPUs int `json:"logical_cpus"`
TestParallel int `json:"test_parallel"`
WallNanos uint64 `json:"wall_nanos"`
Process ProcessMetrics `json:"process"`
Packages map[string]PackageMetrics `json:"packages,omitempty"`
}
Measurement is the stable v1 JSON schema. Package elapsed values are diagnostics; WallNanos is the process wall time and is never their sum.
func DecodeMeasurement ¶
func DecodeMeasurement(data []byte) (Measurement, error)
func ParseTest2JSON ¶
func ParseTest2JSON(input io.Reader, target ...string) (Measurement, error)
func ParseTestJSON ¶
func ParseTestJSON(input io.Reader, target ...string) (Measurement, error)
ParseTestJSON extracts package-level pass events. It intentionally does not derive process wall time from package elapsed values.
type MeasurementResult ¶
type MeasurementResult struct {
Measurement
Result taskrunner.Result `json:"-"`
StdoutLog string `json:"-"`
StderrLog string `json:"-"`
FailureTail string `json:"-"`
}
MeasurementResult carries the machine-readable measurement and operational paths/diagnostics. The JSON schema is Measurement; internal fields are not serialized.
func Measure ¶
func Measure(ctx context.Context, target string, options MeasureOptions) (MeasurementResult, error)
func MeasureQATaggedHotspots ¶
func MeasureQATaggedHotspots(ctx context.Context, options MeasureOptions) (MeasurementResult, error)
func MeasureQualityChecks ¶
func MeasureQualityChecks(ctx context.Context, options MeasureOptions) (MeasurementResult, error)
func MeasureTestUnit ¶
func MeasureTestUnit(ctx context.Context, options MeasureOptions) (MeasurementResult, error)
type OverallComparison ¶
type OverallPolicy ¶
type OverallPolicy struct {
CPU AbsoluteBudget
Processes ProcessBudget
IOOperations CountBudget
Wall AbsoluteBudget
}
OverallPolicy is a convenience value for callers that build policies in Go; TargetPolicy stores the same fields directly in the v1 JSON shape.
type PackageDelta ¶
type PackageDelta struct {
Package string `json:"package"`
AnchorElapsedNanos uint64 `json:"anchor_elapsed_nanos"`
HeadElapsedNanos uint64 `json:"head_elapsed_nanos"`
DeltaNanos uint64 `json:"delta_nanos"`
BaselineElapsedNanos uint64 `json:"-"`
CurrentElapsedNanos uint64 `json:"-"`
}
func (PackageDelta) MarshalJSON ¶
func (p PackageDelta) MarshalJSON() ([]byte, error)
func (*PackageDelta) UnmarshalJSON ¶
func (p *PackageDelta) UnmarshalJSON(data []byte) error
type PackageMeasurement ¶
type PackageMeasurement = PackageMetrics
type PackageMetrics ¶
type PackageMetrics struct {
ElapsedNanos uint64 `json:"elapsed_nanos"`
}
type PackagePolicy ¶
type PackagePolicy struct {
ExistingRatio float64 `json:"existing_ratio,omitempty"`
ExistingDeltaSeconds float64 `json:"existing_delta_seconds,omitempty"`
ExistingFloorSeconds float64 `json:"existing_floor_seconds,omitempty"`
NewWarnSeconds float64 `json:"new_warn_seconds,omitempty"`
NewFailSeconds float64 `json:"new_fail_seconds,omitempty"`
// contains filtered or unexported fields
}
func (*PackagePolicy) UnmarshalJSON ¶
func (p *PackagePolicy) UnmarshalJSON(data []byte) error
type Policy ¶
type Policy struct {
SchemaVersion int `json:"schema_version"`
AnchorRef string `json:"anchor_ref"`
Targets map[string]TargetPolicy `json:"targets"`
AllowOverride bool `json:"-"`
}
Policy intentionally contains only the three schema-level fields. Override authorization is supplied by CompareOptions or the CLI flag, not persisted in policy JSON.
func DecodePolicy ¶
type ProcessAccounting ¶
type ProcessAccounting = ProcessMetrics
type ProcessBudget ¶
type ProcessMetrics ¶
type ProcessMetrics struct {
UserCPUNanos uint64 `json:"user_cpu_nanos"`
KernelCPUNanos uint64 `json:"kernel_cpu_nanos"`
TotalCPUNanos uint64 `json:"total_cpu_nanos"`
TotalProcesses uint64 `json:"total_processes"`
ActiveProcesses uint64 `json:"active_processes"`
TerminatedProcesses uint64 `json:"terminated_processes"`
PageFaults uint64 `json:"page_faults"`
ReadOperations uint64 `json:"read_operations"`
WriteOperations uint64 `json:"write_operations"`
OtherOperations uint64 `json:"other_operations"`
ReadBytes uint64 `json:"read_bytes"`
WriteBytes uint64 `json:"write_bytes"`
OtherBytes uint64 `json:"other_bytes"`
}
type Report ¶
type Report struct {
SchemaVersion int `json:"schema_version"`
Target string `json:"target"`
Passed bool `json:"passed"`
Overridden bool `json:"overridden"`
Violations []Violation `json:"violations"`
Warnings []Warning `json:"warnings"`
Overall []OverallComparison `json:"overall,omitempty"`
TopDeltas []PackageDelta `json:"top_deltas,omitempty"`
}
func CompareWithOptions ¶
func CompareWithOptions(baseline, current Measurement, policy Policy, options CompareOptions) (Report, error)
type RunMeasurement ¶
type RunMeasurement = MeasurementResult
Measurement is the return type used by the public measurement helpers. Keep this alias to make the shape explicit at call sites.
type Runner ¶
type Runner interface {
Run(context.Context, taskrunner.Request) taskrunner.Result
}
type RunnerFunc ¶
type RunnerFunc func(context.Context, taskrunner.Request) taskrunner.Result
func (RunnerFunc) Run ¶
func (f RunnerFunc) Run(ctx context.Context, request taskrunner.Request) taskrunner.Result
type Snapshot ¶
type Snapshot = Measurement
Snapshot is retained as an API-compatible name for callers of the initial package draft.
type TargetPolicy ¶
type TargetPolicy struct {
CPU AbsoluteBudget `json:"cpu"`
Processes ProcessBudget `json:"processes"`
IOOperations CountBudget `json:"io_operations"`
Wall AbsoluteBudget `json:"wall"`
Package PackagePolicy `json:"packages"`
Packages PackagePolicy `json:"-"`
PackageOverrides map[string]PackagePolicy `json:"package_overrides,omitempty"`
}