util

Documentation

Index

• Constants
• type Histogram
  • func NewDecayingHistogram(options HistogramOptions, halfLife time.Duration) Histogram
  • func NewHistogram(options HistogramOptions) Histogram
• type HistogramOptions
  • func NewExponentialHistogramOptions(maxValue float64, firstBucketSize float64, ratio float64, epsilon float64) (HistogramOptions, error)
  • func NewLinearHistogramOptions(maxValue float64, bucketSize float64, epsilon float64) (HistogramOptions, error)
• type MockHistogram
  • func (m *MockHistogram) AddSample(value float64, weight float64, time time.Time)
  • func (m *MockHistogram) Equals(other Histogram) bool
  • func (m *MockHistogram) IsEmpty() bool
  • func (m *MockHistogram) LoadFromCheckpoint(checkpoint *vpa_types.HistogramCheckpoint) error
  • func (m *MockHistogram) Merge(other Histogram)
  • func (m *MockHistogram) Percentile(percentile float64) float64
  • func (m *MockHistogram) SaveToChekpoint() (*vpa_types.HistogramCheckpoint, error)
  • func (m *MockHistogram) String() string
  • func (m *MockHistogram) SubtractSample(value float64, weight float64, time time.Time)

Constants

const (
	// MaxCheckpointWeight is the maximum weight that can be stored in
	// HistogramCheckpoint in a single bucket
	MaxCheckpointWeight uint32 = 10000
)

Types

type Histogram

type Histogram interface {
	// Returns an approximation of the given percentile of the distribution.
	// Note: the argument passed to Percentile() is a number between
	// 0 and 1. For example 0.5 corresponds to the median and 0.9 to the
	// 90th percentile.
	// If the histogram is empty, Percentile() returns 0.0.
	Percentile(percentile float64) float64

	// Add a sample with a given value and weight.
	AddSample(value float64, weight float64, time time.Time)

	// Remove a sample with a given value and weight. Note that the total
	// weight of samples with a given value cannot be negative.
	SubtractSample(value float64, weight float64, time time.Time)

	// Add all samples from another histogram. Requires the histograms to be
	// of the exact same type.
	Merge(other Histogram)

	// Returns true if the histogram is empty.
	IsEmpty() bool

	// Returns true if the histogram is equal to another one. The two
	// histograms must use the same HistogramOptions object (not two
	// different copies).
	// If the two histograms are not of the same runtime type returns false.
	Equals(other Histogram) bool

	// Returns a human-readable text description of the histogram.
	String() string

	// SaveToChekpoint returns a representation of the histogram as a
	// HistogramCheckpoint. During conversion buckets with small weights
	// can be omitted.
	SaveToChekpoint() (*vpa_types.HistogramCheckpoint, error)

	// LoadFromCheckpoint loads data from the checkpoint into the histogram
	// by appending samples.
	LoadFromCheckpoint(*vpa_types.HistogramCheckpoint) error
}

Histogram represents an approximate distribution of some variable.

func NewDecayingHistogram

func NewDecayingHistogram(options HistogramOptions, halfLife time.Duration) Histogram

NewDecayingHistogram returns a new DecayingHistogram instance using given options.

func NewHistogram

func NewHistogram(options HistogramOptions) Histogram

NewHistogram returns a new Histogram instance using given options.

type HistogramOptions

type HistogramOptions interface {
	// Returns the number of buckets in the histogram.
	NumBuckets() int
	// Returns the index of the bucket to which the given value falls.
	// If the value is outside of the range covered by the histogram, it
	// returns the closest bucket (either the first or the last one).
	FindBucket(value float64) int
	// Returns the start of the bucket with a given index. If the index is
	// outside the [0..NumBuckets() - 1] range, the result is undefined.
	GetBucketStart(bucket int) float64
	// Returns the minimum weight for a bucket to be considered non-empty.
	Epsilon() float64
}

HistogramOptions define the number and size of buckets of a histogram.

func NewExponentialHistogramOptions

func NewExponentialHistogramOptions(
	maxValue float64, firstBucketSize float64, ratio float64, epsilon float64) (HistogramOptions, error)

NewExponentialHistogramOptions returns HistogramOptions describing a histogram with exponentially growing bucket boundaries. The first bucket covers the range [0..firstBucketSize). Bucket with index n has size equal to firstBucketSize * ratio^n. It follows that the bucket with index n >= 1 starts at:

firstBucketSize * (1 + ratio + ratio^2 + ... + ratio^(n-1)) =
firstBucketSize * (ratio^n - 1) / (ratio - 1).

The last bucket start is larger or equal to maxValue. Requires maxValue > 0, firstBucketSize > 0, ratio > 1, epsilon > 0.

func NewLinearHistogramOptions

func NewLinearHistogramOptions(
	maxValue float64, bucketSize float64, epsilon float64) (HistogramOptions, error)

NewLinearHistogramOptions returns HistogramOptions describing a histogram with a given number of fixed-size buckets, with the first bucket start at 0.0 and the last bucket start larger or equal to maxValue. Requires maxValue > 0, bucketSize > 0, epsilon > 0.

type MockHistogram

type MockHistogram struct {
	mock.Mock
}

MockHistogram is a mock implementation of Histogram interface.

func (*MockHistogram) AddSample

func (m *MockHistogram) AddSample(value float64, weight float64, time time.Time)

AddSample is a mock implementation of Histogram.AddSample.

func (*MockHistogram) Equals

func (m *MockHistogram) Equals(other Histogram) bool

Equals is a mock implementation of Histogram.Equals.

func (*MockHistogram) IsEmpty

func (m *MockHistogram) IsEmpty() bool

IsEmpty is a mock implementation of Histogram.IsEmpty.

func (*MockHistogram) LoadFromCheckpoint

func (m *MockHistogram) LoadFromCheckpoint(checkpoint *vpa_types.HistogramCheckpoint) error

LoadFromCheckpoint is a mock implementation of Histogram.LoadFromCheckpoint.

func (*MockHistogram) Merge

func (m *MockHistogram) Merge(other Histogram)

Merge is a mock implementation of Histogram.Merge.

func (*MockHistogram) Percentile

func (m *MockHistogram) Percentile(percentile float64) float64

Percentile is a mock implementation of Histogram.Percentile.

func (*MockHistogram) SaveToChekpoint

func (m *MockHistogram) SaveToChekpoint() (*vpa_types.HistogramCheckpoint, error)

SaveToChekpoint is a mock implementation of Histogram.SaveToChekpoint.

func (*MockHistogram) String

func (m *MockHistogram) String() string

String is a mock implementation of Histogram.String.

func (*MockHistogram) SubtractSample

func (m *MockHistogram) SubtractSample(value float64, weight float64, time time.Time)

SubtractSample is a mock implementation of Histogram.SubtractSample.