Documentation ¶
Index ¶
- func EvaluateToDuration(e Expression, context EvaluationContext) (time.Duration, error)
- func EvaluateToScalar(e Expression, context EvaluationContext) (float64, error)
- func EvaluateToSeriesList(e Expression, context EvaluationContext) (api.SeriesList, error)
- func EvaluateToString(e Expression, context EvaluationContext) (string, error)
- func StringToDuration(timeString string) (time.Duration, error)
- type ActualExpression
- type Argument
- type ArgumentLengthError
- type ConversionError
- type ConversionFailure
- type DescriptionMode
- type DurationValue
- func (value DurationValue) ToDuration() (time.Duration, *ConversionFailure)
- func (value DurationValue) ToScalar() (float64, *ConversionFailure)
- func (value DurationValue) ToScalarSet() (ScalarSet, *ConversionFailure)
- func (value DurationValue) ToSeriesList(timerange api.Timerange) (api.SeriesList, *ConversionFailure)
- func (value DurationValue) ToString() (string, *ConversionFailure)
- type EvaluationContext
- func (context EvaluationContext) AddNote(note string)
- func (context EvaluationContext) Ctx() context.Context
- func (context EvaluationContext) EvaluateMemoized(expression ActualExpression) (Value, error)
- func (context EvaluationContext) FetchLimitConsume(n int) error
- func (context EvaluationContext) MetricMetadataAPI() metadata.MetricAPI
- func (context EvaluationContext) Notes() []string
- func (context EvaluationContext) Predicate() predicate.Predicate
- func (context EvaluationContext) Profiler() *inspect.Profiler
- func (context EvaluationContext) RegistryGetFunction(name string) (Function, bool)
- func (context EvaluationContext) SampleMethod() timeseries.SampleMethod
- func (context EvaluationContext) Timerange() api.Timerange
- func (context EvaluationContext) TimeseriesStorageAPI() timeseries.StorageAPI
- func (context EvaluationContext) WithAdditionalConstraint(p predicate.Predicate) EvaluationContext
- func (context EvaluationContext) WithTimerange(t api.Timerange) EvaluationContext
- type EvaluationContextBuilder
- type EvaluationNotes
- type Expression
- type FetchCounter
- type Function
- type Groups
- type LimitError
- type LiteralExpression
- type MetricFunction
- type Option
- type OptionName
- type Registry
- type ScalarSet
- func (set ScalarSet) ToDuration() (time.Duration, *ConversionFailure)
- func (set ScalarSet) ToScalar() (float64, *ConversionFailure)
- func (set ScalarSet) ToScalarSet() (ScalarSet, *ConversionFailure)
- func (set ScalarSet) ToSeriesList(timerange api.Timerange) (api.SeriesList, *ConversionFailure)
- func (set ScalarSet) ToString() (string, *ConversionFailure)
- type ScalarValue
- func (value ScalarValue) ToDuration() (time.Duration, *ConversionFailure)
- func (value ScalarValue) ToScalar() (float64, *ConversionFailure)
- func (value ScalarValue) ToScalarSet() (ScalarSet, *ConversionFailure)
- func (value ScalarValue) ToSeriesList(timerange api.Timerange) (api.SeriesList, *ConversionFailure)
- func (value ScalarValue) ToString() (string, *ConversionFailure)
- type SeriesListValue
- func (list SeriesListValue) ToDuration() (time.Duration, *ConversionFailure)
- func (list SeriesListValue) ToScalar() (float64, *ConversionFailure)
- func (list SeriesListValue) ToScalarSet() (ScalarSet, *ConversionFailure)
- func (list SeriesListValue) ToSeriesList(time api.Timerange) (api.SeriesList, *ConversionFailure)
- func (list SeriesListValue) ToString() (string, *ConversionFailure)
- type Slot
- type StringMemoizationMode
- type StringNameMode
- type StringQueryMode
- type StringValue
- func (value StringValue) ToDuration() (time.Duration, *ConversionFailure)
- func (value StringValue) ToScalar() (float64, *ConversionFailure)
- func (value StringValue) ToScalarSet() (ScalarSet, *ConversionFailure)
- func (value StringValue) ToSeriesList(time api.Timerange) (api.SeriesList, *ConversionFailure)
- func (value StringValue) ToString() (string, *ConversionFailure)
- type TaggedScalar
- type Value
- type WidestMode
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EvaluateToDuration ¶
func EvaluateToDuration(e Expression, context EvaluationContext) (time.Duration, error)
EvaluateToDuration is a helper function that takes an Expression and makes it a duration.
func EvaluateToScalar ¶
func EvaluateToScalar(e Expression, context EvaluationContext) (float64, error)
EvaluateToScalar is a helper function that takes an Expression and makes it a scalar.
func EvaluateToSeriesList ¶
func EvaluateToSeriesList(e Expression, context EvaluationContext) (api.SeriesList, error)
EvaluateToSeriesList is a helper function that takes an Expression and makes it a series list.
func EvaluateToString ¶
func EvaluateToString(e Expression, context EvaluationContext) (string, error)
EvaluateToString is a helper function that takes an Expression and makes it a string.
Types ¶
type ActualExpression ¶
type ActualExpression interface { // Evaluate the given expression. ActualEvaluate(context EvaluationContext) (Value, error) ExpressionDescription(DescriptionMode) string }
An ActualExpression is how expressions are internally implemented by the library, but not how they should be consumed.
type ArgumentLengthError ¶
ArgumentLengthError is a kind of error that describes when a function is given too many or too few arguments.
func (ArgumentLengthError) Error ¶
func (err ArgumentLengthError) Error() string
Error gives a detailed description of the error.
type ConversionError ¶
type ConversionError struct { From string // the original data type To string // the type that attempted to convert to Context string // a short string representation of the value }
ConversionError represents an error converting between two items of different types.
func (ConversionError) Error ¶
func (e ConversionError) Error() string
Error gives a readable description of the error.
type ConversionFailure ¶
type ConversionFailure struct { From string // the original data type To string // the type that it attempted to convert to }
func (*ConversionFailure) WithContext ¶
func (c *ConversionFailure) WithContext(context string) ConversionError
WithContext adds enough context to make the ConversionFailure into an error.
type DescriptionMode ¶
type DescriptionMode interface{}
DescriptionMode indicates how the expression should be evaluated.
func StringMemoization ¶
func StringMemoization() DescriptionMode
StringMemoization is not for humans and intended to give a unique name to every expression
func StringName ¶
func StringName() DescriptionMode
StringName is for human readability and respects aliases
func StringQuery ¶
func StringQuery() DescriptionMode
StringQuery is for humans but ignores aliases, presenting the query as written
type DurationValue ¶
type DurationValue struct {
// contains filtered or unexported fields
}
DurationValue is a duration with a (usually) human-written name.
func NewDurationValue ¶
func NewDurationValue(name string, duration time.Duration) DurationValue
NewDurationValue creates a duration value with the given name and duration.
func (DurationValue) ToDuration ¶
func (value DurationValue) ToDuration() (time.Duration, *ConversionFailure)
ToDuration is a conversion function.
func (DurationValue) ToScalar ¶
func (value DurationValue) ToScalar() (float64, *ConversionFailure)
ToScalar is a conversion function.
func (DurationValue) ToScalarSet ¶
func (value DurationValue) ToScalarSet() (ScalarSet, *ConversionFailure)
func (DurationValue) ToSeriesList ¶
func (value DurationValue) ToSeriesList(timerange api.Timerange) (api.SeriesList, *ConversionFailure)
ToSeriesList is a conversion function.
func (DurationValue) ToString ¶
func (value DurationValue) ToString() (string, *ConversionFailure)
ToString is a conversion function.
type EvaluationContext ¶
type EvaluationContext struct {
// contains filtered or unexported fields
}
EvaluationContext holds all information relevant to executing a single query.
func (EvaluationContext) AddNote ¶
func (context EvaluationContext) AddNote(note string)
AddNote adds a note to the evaluation context.
func (EvaluationContext) Ctx ¶
func (context EvaluationContext) Ctx() context.Context
Ctx returns the underlying Context instance for the evaluation.
func (EvaluationContext) EvaluateMemoized ¶
func (context EvaluationContext) EvaluateMemoized(expression ActualExpression) (Value, error)
EvaluateMemoized evaluates the given ActualExpression using the memoization map internal to the context.
func (EvaluationContext) FetchLimitConsume ¶
func (context EvaluationContext) FetchLimitConsume(n int) error
FetchLimitConsume tries to consume the amount of resources from the limit, returning a non-nil error if this would overdraw the alloted limit.
func (EvaluationContext) MetricMetadataAPI ¶
func (context EvaluationContext) MetricMetadataAPI() metadata.MetricAPI
MetricMetadataAPI returns the underlying metadata.MetricAPI.
func (EvaluationContext) Notes ¶
func (context EvaluationContext) Notes() []string
Notes returns all notes added to the evaluation context.
func (EvaluationContext) Predicate ¶
func (context EvaluationContext) Predicate() predicate.Predicate
Predicate returns the underlying predicate.Predicate.
func (EvaluationContext) Profiler ¶
func (context EvaluationContext) Profiler() *inspect.Profiler
Profiler returns the underlying inspect.Profiler instance.
func (EvaluationContext) RegistryGetFunction ¶
func (context EvaluationContext) RegistryGetFunction(name string) (Function, bool)
RegistryGetFunction gets the function of the provided name, return true if the function could be found and false otherwise.
func (EvaluationContext) SampleMethod ¶
func (context EvaluationContext) SampleMethod() timeseries.SampleMethod
SampleMethod returns the underlying timeseries.SampleMethod.
func (EvaluationContext) Timerange ¶
func (context EvaluationContext) Timerange() api.Timerange
Timerange returns the underlying api.Timerange.
func (EvaluationContext) TimeseriesStorageAPI ¶
func (context EvaluationContext) TimeseriesStorageAPI() timeseries.StorageAPI
TimeseriesStorageAPI returns the underlying timeseries.StorageAPI.
func (EvaluationContext) WithAdditionalConstraint ¶
func (context EvaluationContext) WithAdditionalConstraint(p predicate.Predicate) EvaluationContext
WithAdditionalConstraint return a new copy of the evaluation context with a distinct memoization map.
func (EvaluationContext) WithTimerange ¶
func (context EvaluationContext) WithTimerange(t api.Timerange) EvaluationContext
WithTimerange duplicates the EvaluationContext but with a new timerange.
type EvaluationContextBuilder ¶
type EvaluationContextBuilder struct { TimeseriesStorageAPI timeseries.StorageAPI // Backend to fetch data from MetricMetadataAPI metadata.MetricAPI // Api to obtain metadata from Registry Registry // Registry stores functions SampleMethod timeseries.SampleMethod // SampleMethod to use when up/downsampling to match the requested resolution FetchLimit FetchCounter // A limit on the number of fetches which may be performed Profiler *inspect.Profiler // A profiler pointer EvaluationNotes *EvaluationNotes // Debug + numerical notes that can be added during evaluation Ctx context.Context // These may be changed in sub-contexts while evaluating the query. Timerange api.Timerange // Timerange to fetch data from Predicate predicate.Predicate // Predicate to apply to TagSets prior to fetching }
An EvaluationContextBuilder is used to create an EvaluationContext because the EvaluationContext's fields are private to prevent accidental modification.
func (EvaluationContextBuilder) Build ¶
func (builder EvaluationContextBuilder) Build() EvaluationContext
Build creates an evaluation context from the provided builder.
type EvaluationNotes ¶
type EvaluationNotes struct {
// contains filtered or unexported fields
}
EvaluationNotes holds notes that were recorded during evaluation.
func (*EvaluationNotes) AddNote ¶
func (notes *EvaluationNotes) AddNote(note string)
AddNote adds a new note to the collection in a threadsafe manner.
func (*EvaluationNotes) Notes ¶
func (notes *EvaluationNotes) Notes() []string
Notes returns the current collection of notes in a threadsafe manner.
type Expression ¶
type Expression interface { Evaluate(context EvaluationContext) (Value, error) ExpressionDescription(DescriptionMode) string }
Expression is a piece of code, which can be evaluated in a given EvaluationContext. EvaluationContext must never be changed in an Evaluate().
If an Expression returns a SeriesList, its timerange must match the context's timerange exactly.
func Memoize ¶
func Memoize(expression ActualExpression) Expression
Memoize takes an ordinary actual expression and turns it into a memoized expression.
type FetchCounter ¶
type FetchCounter struct {
// contains filtered or unexported fields
}
FetchCounter is used to count the number of fetches remaining in a thread-safe manner.
func NewFetchCounter ¶
func NewFetchCounter(n int) FetchCounter
NewFetchCounter creates a FetchCounter with n as the limit.
func (FetchCounter) Consume ¶
func (c FetchCounter) Consume(n int) error
Consume decrements the internal counter and returns whether the result is at least 0. It does so in a threadsafe manner.
func (FetchCounter) Current ¶
func (c FetchCounter) Current() int
Current returns the current number of fetches remaining for the counter.
func (FetchCounter) Limit ¶
func (c FetchCounter) Limit() int
Limit returns the max # of fetches allowed by this counter.
type Function ¶
type Function interface { Run(EvaluationContext, []Expression, Groups) (Value, error) Name() string }
The Function interface defines a metric function. It is given several (unevaluated) expressions as input, and evaluates to a Value.
type Groups ¶
type Groups struct { List []string // the tags to group by Collapses bool // whether to "collapse by" instead of "group by" }
Groups holds grouping information - which tags to group by (if any), and whether to `collapse` (Collapses = true) or `group` (Collapses = false)
type LimitError ¶
type LimitError interface { Actual() interface{} // actual from the system which triggered this error. Limit() interface{} // configured limit error }
LimitError is returned if an error occurs where limits are surpassed.
func NewLimitError ¶
func NewLimitError(message string, actual interface{}, limit interface{}) LimitError
NewLimitError uses its parameters to create a LimitError.
type LiteralExpression ¶
type LiteralExpression interface {
Literal() interface{}
}
A LiteralExpression is an expression that holds a literal value. Returning `nil` indicates that your particular instance doesn't actually hold any literal value.
type MetricFunction ¶
type MetricFunction struct { FunctionName string // Name is the name of the function, used in its registration. MinArguments int // MinArguments is the minimum number of arguments the function allows. MaxArguments int // MaxArguments is the maximum number of arguments the function allows. -1 indicates an unlimited number. AllowsGroupBy bool // Whether the function allows a 'group by' clause. Compute func(EvaluationContext, []Expression, Groups) (Value, error) Widen func(WidestMode, []Expression) time.Time // Optional; returns new Earliest }
MetricFunction holds a generic function object with information about its parameters.
func MakeFunction ¶
func MakeFunction(name string, function interface{}, options ...Option) MetricFunction
MakeFunction is a convenient way to use type-safe functions to construct MetricFunctions without manually checking parameters.
func (MetricFunction) Name ¶
func (f MetricFunction) Name() string
Name returns the MetricFunction's name.
func (MetricFunction) Run ¶
func (f MetricFunction) Run(context EvaluationContext, arguments []Expression, groups Groups) (Value, error)
Run evaluates the given MetricFunction on its arguments. It performs error-checking against the supplies number of arguments and/or group-by clause.
type Option ¶
type Option struct { Name OptionName // Name identifies the option type Value interface{} // Value is the value associated with the option }
An Option is an annotation used to add extra functionality to the generated MetricFunction.
type OptionName ¶
type OptionName int
An OptionName identifies an option passed to MakeFunction
const ( InvalidOption OptionName = iota // InvalidOption represents an invalid option WidenBy // WidenBy indicates that the given duration Argument index, or the number of Slots should be used to extend the timerange in the query into the past by the given amount. ShiftBy // ShiftBy indicates that the given duration Argument index, or the number of Slots should be used to shift the timerange in the query (positive is forward in time into the future, negative is backward in time to the past) )
func (OptionName) String ¶
func (n OptionName) String() string
String makes the option name human-readable.
type Registry ¶
type Registry interface { GetFunction(string) (Function, bool) // returns an instance of a Function All() []string // all the registered functions }
The Registry interface defines a mapping from names to Functions and provides a way to get the full list of functions defined.
type ScalarSet ¶
type ScalarSet []TaggedScalar
func EvaluateToScalarSet ¶
func EvaluateToScalarSet(e Expression, context EvaluationContext) (ScalarSet, error)
EvaluateToScalarSet is a helper function that takes an Expression and makes it a scalar set.
func (ScalarSet) ToDuration ¶
func (set ScalarSet) ToDuration() (time.Duration, *ConversionFailure)
func (ScalarSet) ToScalar ¶
func (set ScalarSet) ToScalar() (float64, *ConversionFailure)
func (ScalarSet) ToScalarSet ¶
func (set ScalarSet) ToScalarSet() (ScalarSet, *ConversionFailure)
func (ScalarSet) ToSeriesList ¶
func (set ScalarSet) ToSeriesList(timerange api.Timerange) (api.SeriesList, *ConversionFailure)
func (ScalarSet) ToString ¶
func (set ScalarSet) ToString() (string, *ConversionFailure)
type ScalarValue ¶
type ScalarValue float64
A ScalarValue holds a float and can be converted to a serieslist
func (ScalarValue) ToDuration ¶
func (value ScalarValue) ToDuration() (time.Duration, *ConversionFailure)
ToDuration is a conversion function. Scalars cannot be converted to durations.
func (ScalarValue) ToScalar ¶
func (value ScalarValue) ToScalar() (float64, *ConversionFailure)
ToScalar is a conversion function.
func (ScalarValue) ToScalarSet ¶
func (value ScalarValue) ToScalarSet() (ScalarSet, *ConversionFailure)
ToScalarSet is a conversion function.
func (ScalarValue) ToSeriesList ¶
func (value ScalarValue) ToSeriesList(timerange api.Timerange) (api.SeriesList, *ConversionFailure)
ToSeriesList is a conversion function. The scalar becomes a constant value for the timerange.
func (ScalarValue) ToString ¶
func (value ScalarValue) ToString() (string, *ConversionFailure)
ToString is a conversion function. Numbers become formatted.
type SeriesListValue ¶
type SeriesListValue api.SeriesList
A SeriesListValue holds a SeriesList.
func (SeriesListValue) ToDuration ¶
func (list SeriesListValue) ToDuration() (time.Duration, *ConversionFailure)
ToDuration is a conversion function to implement the Value interface.
func (SeriesListValue) ToScalar ¶
func (list SeriesListValue) ToScalar() (float64, *ConversionFailure)
ToScalar is a conversion function to implement the Value interface.
func (SeriesListValue) ToScalarSet ¶
func (list SeriesListValue) ToScalarSet() (ScalarSet, *ConversionFailure)
ToScalarSet is a conversion function to implement the Value interface.
func (SeriesListValue) ToSeriesList ¶
func (list SeriesListValue) ToSeriesList(time api.Timerange) (api.SeriesList, *ConversionFailure)
ToSeriesList is an identity function that allows SeriesList to implement the Value interface.
func (SeriesListValue) ToString ¶
func (list SeriesListValue) ToString() (string, *ConversionFailure)
ToString is a conversion function to implement the Value interface.
type StringMemoizationMode ¶
type StringMemoizationMode struct{}
type StringNameMode ¶
type StringNameMode struct{}
type StringQueryMode ¶
type StringQueryMode struct{}
type StringValue ¶
type StringValue string
A StringValue holds a string
func (StringValue) ToDuration ¶
func (value StringValue) ToDuration() (time.Duration, *ConversionFailure)
ToDuration is a conversion function.
func (StringValue) ToScalar ¶
func (value StringValue) ToScalar() (float64, *ConversionFailure)
ToScalar is a conversion function.
func (StringValue) ToScalarSet ¶
func (value StringValue) ToScalarSet() (ScalarSet, *ConversionFailure)
ToScalarSet is a conversion function.
func (StringValue) ToSeriesList ¶
func (value StringValue) ToSeriesList(time api.Timerange) (api.SeriesList, *ConversionFailure)
ToSeriesList is a conversion function.
func (StringValue) ToString ¶
func (value StringValue) ToString() (string, *ConversionFailure)
ToString is a conversion function.
type TaggedScalar ¶
func (TaggedScalar) MarshalJSON ¶
func (ts TaggedScalar) MarshalJSON() ([]byte, error)
MarshalJSON for TaggedScalar marshals NaN or infinity to null.
type Value ¶
type Value interface { ToSeriesList(api.Timerange) (api.SeriesList, *ConversionFailure) ToString() (string, *ConversionFailure) ToScalar() (float64, *ConversionFailure) ToScalarSet() (ScalarSet, *ConversionFailure) ToDuration() (time.Duration, *ConversionFailure) }
Value is the result of evaluating an expression. They can be floating point values, strings, or series lists.
func EvaluateMany ¶
func EvaluateMany(context EvaluationContext, expressions []Expression) ([]Value, error)
EvaluateMany evaluates a list of expressions using a single EvaluationContext. If any evaluation errors, EvaluateMany will propagate that error. The resulting values will be in the order corresponding to the provided expressions.