ts

package
Version: v1.4.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 18, 2022 License: Apache-2.0 Imports: 13 Imported by: 8

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrRangeIsInvalid is returned when attempting to slice Series with invalid range
	// endpoints (begin is beyond end).
	ErrRangeIsInvalid = errors.New("requested range is invalid")
)

Functions

func Avg

func Avg(a, b float64, count int) float64

Avg produces a running average.

func EnablePooling

func EnablePooling(valueBuckets, consolidationBuckets []xpool.Bucket)

EnablePooling enables pooling.

func Gcd

func Gcd(a, b int64) int64

Gcd finds the gcd of two values.

func Last

func Last(a, b float64, count int) float64

Last finds the latter of two values.

func Lcm

func Lcm(a, b int64) int64

Lcm finds the lcm of two values.

func Max

func Max(a, b float64, count int) float64

Max finds the max of two values.

func Median added in v1.0.0

func Median(vals []float64, count int) float64

Median finds the median of a slice of values.

func Min

func Min(a, b float64, count int) float64

Min finds the min of two values.

func Mul

func Mul(a, b float64, count int) float64

Mul multiplies two values.

func NumSteps

func NumSteps(start, end time.Time, millisPerStep int) int

NumSteps calculates the number of steps of a given size between two times.

func Pow added in v1.0.1

func Pow(a, b float64, count int) float64

Pow returns the first value to the power of the second value

func Sum

func Sum(a, b float64, count int) float64

Sum sums two values.

Types

type AggregationFunc

type AggregationFunc func(a, b float64) float64

An AggregationFunc combines two data values at a given point.

type ConsolidatedValue

type ConsolidatedValue struct {
	// StartTime is the start time of the time window covered by this
	// consolidation
	StartTime time.Time

	// EndTime is the end time of the time window covered by this
	// consolidation
	EndTime time.Time

	// Values is the statistics for that consolidated time window
	Values stats.Statistics
}

ConsolidatedValue represents a time window of consolidated data

type ConsolidatedValuesByStartTime

type ConsolidatedValuesByStartTime []ConsolidatedValue

ConsolidatedValuesByStartTime is a sortable interface for consolidated values

func (ConsolidatedValuesByStartTime) Len

Len is the length of the values

func (ConsolidatedValuesByStartTime) Less

func (p ConsolidatedValuesByStartTime) Less(i, j int) bool

Less compares two values by start time

func (ConsolidatedValuesByStartTime) Swap

func (p ConsolidatedValuesByStartTime) Swap(i, j int)

Swap swaps two values

type Consolidation

type Consolidation interface {
	// AddDatapoint adds an individual datapoint to the consolidation.
	AddDatapoint(timestamp time.Time, value float64)

	// AddDatapoints adds a set of datapoints to the consolidation.
	AddDatapoints(datapoints []Datapoint)

	// AddSeries adds the datapoints for each series to the consolidation.  The
	// stepAggregationFunc is used to combine values from the series if the series
	// has a smaller step size than the consolidation.  For example, an application
	// might want to produce a consolidation which is a minimum of the input timeseries,
	// but where the values in smaller timeseries units are summed together to
	// produce the value to which the consolidation applies.
	// To put it in another way, stepAggregationFunc is used for the series to resize itself
	// rather than for the consolidation
	AddSeries(series *Series, stepAggregationFunc ConsolidationFunc)

	// BuildSeries returns the consolidated Series and optionally finalizes
	// the consolidation returning it to the pool
	BuildSeries(id string, finalize FinalizeOption) *Series

	// Finalize returns the consolidation to the pool
	Finalize()
}

A Consolidation produces a Series whose values are the result of applying a consolidation function to all of the datapoints that fall within each step. It can used to quantize raw datapoints into a given resolution, for example, or to aggregate multiple timeseries at the same or smaller resolutions.

func NewConsolidation

func NewConsolidation(
	ctx context.Context,
	start, end time.Time,
	millisPerStep int,
	cf ConsolidationFunc,
) Consolidation

NewConsolidation creates a new consolidation window.

type ConsolidationApproach

type ConsolidationApproach string

ConsolidationApproach defines an approach to consolidating multiple datapoints

const (
	ConsolidationAvg     ConsolidationApproach = "avg"
	ConsolidationMin     ConsolidationApproach = "min"
	ConsolidationMax     ConsolidationApproach = "max"
	ConsolidationSum     ConsolidationApproach = "sum"
	ConsolidationAverage ConsolidationApproach = "average" // just an alias to avg but for backward-compatibility
	ConsolidationLast    ConsolidationApproach = "last"
)

The standard set of consolidation functions

func (ConsolidationApproach) Func

Func returns the ConsolidationFunc implementing the ConsolidationApproach

func (ConsolidationApproach) SafeFunc

func (ca ConsolidationApproach) SafeFunc() (ConsolidationFunc, bool)

SafeFunc returns a boolean indicating whether this is a valid consolidation approach, and if so, the corresponding ConsolidationFunc.

type ConsolidationFunc

type ConsolidationFunc func(existing, toAdd float64, count int) float64

A ConsolidationFunc consolidates values at a given point in time. It takes the current consolidated value, the new value to add to the consolidation, and a count of the number of values that have already been consolidated.

type CustomStatistics

type CustomStatistics interface {
	CalcStatistics() stats.Statistics
}

CustomStatistics are for values that do custom statistics calculations

type Datapoint

type Datapoint struct {
	Timestamp time.Time
	Value     float64
}

A Datapoint is a single data value reported at a given time

func (Datapoint) ValueIsNaN

func (d Datapoint) ValueIsNaN() bool

ValueIsNaN returns true iff underlying value is NaN

type Datapoints

type Datapoints []Datapoint

Datapoints is a list of datapoints that implement the stats.Values interface.

func (Datapoints) AllNaN

func (d Datapoints) AllNaN() bool

AllNaN returns true if all the values are NaN

func (Datapoints) Len

func (d Datapoints) Len() int

Len is the length of the array.

func (Datapoints) ValueAt

func (d Datapoints) ValueAt(n int) float64

ValueAt returns the value at the nth element.

type DatapointsByTimestamp

type DatapointsByTimestamp []Datapoint

DatapointsByTimestamp is a sortable interface for datapoints

func (DatapointsByTimestamp) Len

func (p DatapointsByTimestamp) Len() int

Len is the length of the datapoints

func (DatapointsByTimestamp) Less

func (p DatapointsByTimestamp) Less(i, j int) bool

Less compares two datapoints by timestamp

func (DatapointsByTimestamp) Swap

func (p DatapointsByTimestamp) Swap(i, j int)

Swap swaps two datapoints

type Direction

type Direction int

Direction signifies ascending or descending order

const (
	// Ascending order
	Ascending Direction = iota
	// Descending order
	Descending
)

type FinalizeOption

type FinalizeOption int

FinalizeOption specifies the option to finalize or avoid finalizing

const (
	// NoFinalize will avoid finalizing the subject
	NoFinalize FinalizeOption = iota
	// Finalize will finalize the subject
	Finalize
)

type MutableSeries

type MutableSeries struct {
	Series
}

A MutableSeries is a Series that allows updates

func NewMutableSeries

func NewMutableSeries(
	ctx context.Context,
	name string,
	startTime time.Time,
	vals MutableValues) *MutableSeries

NewMutableSeries returns a new mutable Series at the given start time and backed by the provided storage

func (*MutableSeries) SetValueAt

func (b *MutableSeries) SetValueAt(i int, v float64)

SetValueAt sets the value at the given step

func (*MutableSeries) SetValueAtTime

func (b *MutableSeries) SetValueAtTime(t time.Time, v float64)

SetValueAtTime sets the value at the step containing the given time

type MutableValues

type MutableValues interface {
	Values

	// Resets the values
	Reset()

	// Sets the value at the given entry
	SetValueAt(n int, v float64)
}

MutableValues is the interface for values that can be updated

func NewValues

func NewValues(ctx context.Context, millisPerStep, numSteps int) MutableValues

NewValues returns MutableValues supporting the given number of values at the requested granularity. The values start off as NaN

func NewZeroValues

func NewZeroValues(ctx context.Context, millisPerStep, numSteps int) MutableValues

NewZeroValues returns a MutableValues supporting the given number of values at the requested granularity. The values start off initialized at 0

type PostConsolidationFunc

type PostConsolidationFunc func(timestamp time.Time, value float64)

PostConsolidationFunc is a function that takes a tuple of time and value after consolidation.

type Series

type Series struct {

	// The Specification is the path that was used to generate this timeseries,
	// typically either the query, or the function stack used to transform
	// specific results.
	Specification string
	// contains filtered or unexported fields
}

A Series is the public interface to a block of timeseries values. Each block has a start time, a logical number of steps, and a step size indicating the number of milliseconds represented by each point.

func LTTB

func LTTB(b *Series, start time.Time, end time.Time, millisPerStep int) *Series

LTTB down-samples the data to contain only threshold number of points that have the same visual shape as the original data. Inspired from https://github.com/dgryski/go-lttb which is based on https://skemman.is/bitstream/1946/15343/3/SS_MSthesis.pdf

func NewSeries

func NewSeries(ctx context.Context, name string, startTime time.Time, vals Values) *Series

NewSeries creates a new Series at a given start time, backed by the provided values

func (*Series) AllNaN

func (b *Series) AllNaN() bool

AllNaN returns true if the timeseries is all NaNs

func (*Series) CalcStatistics

func (b *Series) CalcStatistics() stats.Statistics

CalcStatistics calculates a standard aggregation across the block values

func (*Series) ConsolidationFunc

func (b *Series) ConsolidationFunc() ConsolidationFunc

ConsolidationFunc returns the consolidation function for the series, or the averaging function is none specified.

func (*Series) Contains

func (b *Series) Contains(t time.Time) bool

Contains checks whether the given series contains the provided time

func (*Series) DerivedSeries

func (b *Series) DerivedSeries(startTime time.Time, vals Values) *Series

DerivedSeries returns a series derived from the current series with different datapoints

func (*Series) Duration

func (b *Series) Duration() time.Duration

Duration returns the Duration covered by the block

func (*Series) EndTime

func (b *Series) EndTime() time.Time

EndTime returns the time the block ends

func (*Series) EndTimeForStep

func (b *Series) EndTimeForStep(n int) time.Time

EndTimeForStep returns the time at which the given step end

func (*Series) IntersectAndResize

func (b *Series) IntersectAndResize(
	start, end time.Time,
	millisPerStep int,
	stepAggregator ConsolidationFunc,
) (*Series, error)

IntersectAndResize returns a new time series with a different millisPerStep that spans the intersection of the underlying timeseries and the provided start and end time parameters

func (*Series) IsConsolidationFuncSet

func (b *Series) IsConsolidationFuncSet() bool

IsConsolidationFuncSet if the consolidationFunc is set

func (*Series) Len

func (b *Series) Len() int

Len returns the number of values in the time series. Used for aggregation

func (*Series) MillisPerStep

func (b *Series) MillisPerStep() int

MillisPerStep returns the number of milliseconds per step

func (*Series) Name

func (b *Series) Name() string

Name returns the name of the timeseries block

func (*Series) NeedsResizeToMaxDataPoints added in v1.2.0

func (b *Series) NeedsResizeToMaxDataPoints(maxDataPoints int64) bool

NeedsResizeToMaxDataPoints returns whether the series needs resizing to max datapoints.

func (*Series) RenamedTo

func (b *Series) RenamedTo(name string) *Series

RenamedTo returns a new timeseries with the same values but a different name

func (*Series) ResizeToMaxDataPoints added in v1.2.0

func (b *Series) ResizeToMaxDataPoints(
	maxDataPoints int64,
	stepAggregator ConsolidationFunc,
) (*Series, bool)

ResizeToMaxDataPoints resizes the series to fit max datapoints and returns true if a series was resized or false if it did not need to be resized.

func (*Series) ResizeToMaxDataPointsMillisPerStep added in v1.2.0

func (b *Series) ResizeToMaxDataPointsMillisPerStep(
	maxDataPoints int64,
) (int, bool)

ResizeToMaxDataPointsMillisPerStep returns the new milliseconds per second required if a series needs resizing and true, or if does not need resize for max datapoints then it returns 0 and false.

func (*Series) Resolution

func (b *Series) Resolution() time.Duration

Resolution returns resolution per step

func (*Series) SafeAvg

func (b *Series) SafeAvg() float64

SafeAvg returns the average of the values of a series, excluding NaNs.

func (*Series) SafeLastValue

func (b *Series) SafeLastValue() float64

SafeLastValue returns the last datapoint of a series that's not an NaN.

func (*Series) SafeMax

func (b *Series) SafeMax() float64

SafeMax returns the maximum value of a series that's not an NaN.

func (*Series) SafeMin

func (b *Series) SafeMin() float64

SafeMin returns the minimum value of a series that's not an NaN.

func (*Series) SafeStdDev

func (b *Series) SafeStdDev() float64

SafeStdDev returns the standard deviation of the values of a series, excluding NaNs.

func (*Series) SafeSum

func (b *Series) SafeSum() float64

SafeSum returns the sum of the values of a series, excluding NaNs.

func (*Series) SafeValues

func (b *Series) SafeValues() []float64

SafeValues returns all non-NaN values in the series.

func (*Series) SetConsolidationFunc

func (b *Series) SetConsolidationFunc(cf ConsolidationFunc)

SetConsolidationFunc sets the consolidation function for the series

func (*Series) Shift

func (b *Series) Shift(shift time.Duration) *Series

Shift returns a new timeseries with the same values but a different startTime

func (*Series) Slice

func (b *Series) Slice(begin, end int) (*Series, error)

Slice returns a new Series composed from a subset of values in the original Series

func (*Series) StartTime

func (b *Series) StartTime() time.Time

StartTime returns the time the block starts

func (*Series) StartTimeForStep

func (b *Series) StartTimeForStep(n int) time.Time

StartTimeForStep returns the time at which the given step starts

func (*Series) StepAtTime

func (b *Series) StepAtTime(t time.Time) int

StepAtTime returns the step within the block containing the given time

func (*Series) ValueAt

func (b *Series) ValueAt(i int) float64

ValueAt returns the value at a given step. Used for aggregation

func (*Series) ValueAtTime

func (b *Series) ValueAtTime(t time.Time) float64

ValueAtTime returns the value stored at the step representing the given time

type SeriesByName

type SeriesByName []*Series

SeriesByName implements sort.Interface for sorting collections of series by name.

func (SeriesByName) Len

func (a SeriesByName) Len() int

Len returns the length of the series collection

func (SeriesByName) Less

func (a SeriesByName) Less(i, j int) bool

Less determines if a series is ordered before another series by name

func (SeriesByName) Swap

func (a SeriesByName) Swap(i, j int)

Swap swaps two series in the collection

type SeriesByNameAndNaturalNumbers added in v1.2.0

type SeriesByNameAndNaturalNumbers []*Series

SeriesByNameAndNaturalNumbers implements sort.Interface for sorting collections of series by name respecting natural sort order for numbers.

func (SeriesByNameAndNaturalNumbers) Len added in v1.2.0

Len returns the length of the series collection

func (SeriesByNameAndNaturalNumbers) Less added in v1.2.0

func (a SeriesByNameAndNaturalNumbers) Less(i, j int) bool

Less determines if a series is ordered before another series by name nolint: ifshort

func (SeriesByNameAndNaturalNumbers) Swap added in v1.2.0

func (a SeriesByNameAndNaturalNumbers) Swap(i, j int)

Swap swaps two series in the collection

type SeriesList

type SeriesList struct {
	// Values is the list of series.
	Values []*Series
	// SortApplied specifies whether a specific sort order has been applied.
	SortApplied bool
	// Metadata contains any additional metadata indicating information about
	// series execution.
	Metadata block.ResultMetadata
}

A SeriesList is a list of series.

func NewSeriesList added in v0.14.0

func NewSeriesList() SeriesList

NewSeriesList creates a blank series list.

func NewSeriesListWithSeries added in v0.14.0

func NewSeriesListWithSeries(values ...*Series) SeriesList

NewSeriesListWithSeries creates a series list with the given series and default metadata.

func SortSeries

func SortSeries(input SeriesList, sr SeriesReducer, dir Direction) (SeriesList, error)

SortSeries applies a given SeriesReducer to each series in the input list and sorts based on the assigned value

func (SeriesList) Len

func (l SeriesList) Len() int

Len returns the length of the list.

type SeriesReducer

type SeriesReducer func(*Series) float64

SeriesReducer reduces a series to a single value.

type SeriesReducerApproach

type SeriesReducerApproach string

SeriesReducerApproach defines an approach to reduce a series to a single value.

const (
	SeriesReducerAvg    SeriesReducerApproach = "avg"
	SeriesReducerSum    SeriesReducerApproach = "sum"
	SeriesReducerMin    SeriesReducerApproach = "min"
	SeriesReducerMax    SeriesReducerApproach = "max"
	SeriesReducerStdDev SeriesReducerApproach = "stddev"
	SeriesReducerLast   SeriesReducerApproach = "last"

	SeriesReducerAverage SeriesReducerApproach = "average" // alias for "avg"
	SeriesReducerTotal   SeriesReducerApproach = "total"   // alias for "sum"
	SeriesReducerCurrent SeriesReducerApproach = "current" // alias for "last"
)

The standard set of reducers

func (SeriesReducerApproach) Reducer

func (sa SeriesReducerApproach) Reducer() SeriesReducer

Reducer returns the SeriesReducer implementing the SeriesReducerApproach.

func (SeriesReducerApproach) SafeReducer

func (sa SeriesReducerApproach) SafeReducer() (SeriesReducer, bool)

SafeReducer returns a boolean indicating whether it is a valid reducer, and if so, the SeriesReducer implementing the SeriesReducerApproach.

type Values

type Values interface {
	stats.Values

	// The number of millisseconds represented by each index
	MillisPerStep() int

	// Slice of data values in a range
	Slice(begin, end int) Values

	// AllNaN returns true if the values are all NaN
	AllNaN() bool
}

Values holds the values for a timeseries. It provides a minimal interface for storing and retrieving values in the series, with Series providing a more convenient interface for applications to build on top of. Values objects are not specific to a given time, allowing them to be pre-allocated, pooled, and re-used across multiple Series. There are multiple implementations of Values so that we can optimize storage based on the density of the series.

func NewConstantValues

func NewConstantValues(ctx context.Context, value float64, numSteps, millisPerStep int) Values

NewConstantValues returns a block of timeseries values all of which have the same value

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL