promql

package
v0.49.0-rc.0 Latest Latest
Warning

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

 Go to latest Published: Dec 12, 2023 License: Apache-2.0 Imports: 46 Imported by: 1,486

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrValidationAtModifierDisabled     = errors.New("@ modifier is disabled")
	ErrValidationNegativeOffsetDisabled = errors.New("negative offset is disabled")
)
View Source 
var AtModifierUnsafeFunctions = map[string]struct{}{

	"days_in_month": {}, "day_of_month": {}, "day_of_week": {}, "day_of_year": {},
	"hour": {}, "minute": {}, "month": {}, "year": {},
	"predict_linear": {}, "time": {},

	"timestamp": {},
}

AtModifierUnsafeFunctions are the functions whose result can vary if evaluation time is changed when the arguments are step invariant. It also includes functions that use the timestamps of the passed instant vector argument to calculate a result since that can also change with change in eval time.

View Source 
var FunctionCalls = map[string]FunctionCall{
	"abs":                funcAbs,
	"absent":             funcAbsent,
	"absent_over_time":   funcAbsentOverTime,
	"acos":               funcAcos,
	"acosh":              funcAcosh,
	"asin":               funcAsin,
	"asinh":              funcAsinh,
	"atan":               funcAtan,
	"atanh":              funcAtanh,
	"avg_over_time":      funcAvgOverTime,
	"ceil":               funcCeil,
	"changes":            funcChanges,
	"clamp":              funcClamp,
	"clamp_max":          funcClampMax,
	"clamp_min":          funcClampMin,
	"cos":                funcCos,
	"cosh":               funcCosh,
	"count_over_time":    funcCountOverTime,
	"days_in_month":      funcDaysInMonth,
	"day_of_month":       funcDayOfMonth,
	"day_of_week":        funcDayOfWeek,
	"day_of_year":        funcDayOfYear,
	"deg":                funcDeg,
	"delta":              funcDelta,
	"deriv":              funcDeriv,
	"exp":                funcExp,
	"floor":              funcFloor,
	"histogram_count":    funcHistogramCount,
	"histogram_fraction": funcHistogramFraction,
	"histogram_quantile": funcHistogramQuantile,
	"histogram_sum":      funcHistogramSum,
	"histogram_stddev":   funcHistogramStdDev,
	"histogram_stdvar":   funcHistogramStdVar,
	"holt_winters":       funcHoltWinters,
	"hour":               funcHour,
	"idelta":             funcIdelta,
	"increase":           funcIncrease,
	"irate":              funcIrate,
	"label_replace":      funcLabelReplace,
	"label_join":         funcLabelJoin,
	"ln":                 funcLn,
	"log10":              funcLog10,
	"log2":               funcLog2,
	"last_over_time":     funcLastOverTime,
	"mad_over_time":      funcMadOverTime,
	"max_over_time":      funcMaxOverTime,
	"min_over_time":      funcMinOverTime,
	"minute":             funcMinute,
	"month":              funcMonth,
	"pi":                 funcPi,
	"predict_linear":     funcPredictLinear,
	"present_over_time":  funcPresentOverTime,
	"quantile_over_time": funcQuantileOverTime,
	"rad":                funcRad,
	"rate":               funcRate,
	"resets":             funcResets,
	"round":              funcRound,
	"scalar":             funcScalar,
	"sgn":                funcSgn,
	"sin":                funcSin,
	"sinh":               funcSinh,
	"sort":               funcSort,
	"sort_desc":          funcSortDesc,
	"sort_by_label":      funcSortByLabel,
	"sort_by_label_desc": funcSortByLabelDesc,
	"sqrt":               funcSqrt,
	"stddev_over_time":   funcStddevOverTime,
	"stdvar_over_time":   funcStdvarOverTime,
	"sum_over_time":      funcSumOverTime,
	"tan":                funcTan,
	"tanh":               funcTanh,
	"time":               funcTime,
	"timestamp":          funcTimestamp,
	"vector":             funcVector,
	"year":               funcYear,
}

FunctionCalls is a list of all functions supported by PromQL, including their types.

Functions

func FindMinMaxTime added in v0.49.0 

func FindMinMaxTime(s *parser.EvalStmt) (int64, int64)

FindMinMaxTime returns the time in milliseconds of the earliest and latest point in time the statement will try to process. This takes into account offsets, @ modifiers, and range selectors. If the statement does not select series, then FindMinMaxTime returns (0, 0).

func HistogramTestExpression added in v0.47.0 

func HistogramTestExpression(h *histogram.FloatHistogram) string

HistogramTestExpression returns TestExpression() for the given histogram or "" if the histogram is nil.

func LoadedStorage added in v0.47.0 

func LoadedStorage(t testutil.T, input string) *teststorage.TestStorage

LoadedStorage returns storage with generated data using the provided load statements. Non-load statements will cause test errors.

func NewOriginContext 

func NewOriginContext(ctx context.Context, data map[string]interface{}) context.Context

NewOriginContext returns a new context with data about the origin attached.

func PreprocessExpr 

func PreprocessExpr(expr parser.Expr, start, end time.Time) parser.Expr

PreprocessExpr wraps all possible step invariant parts of the given expression with StepInvariantExpr. It also resolves the preprocessors.

func RunBuiltinTests added in v0.47.0 

func RunBuiltinTests(t *testing.T, engine engineQuerier)

RunBuiltinTests runs an acceptance test suite against the provided engine.

func RunTest added in v0.47.0 

func RunTest(t testutil.T, input string, engine engineQuerier)

RunTest parses and runs the test against the provided engine.

Types

type ActiveQueryTracker 

type ActiveQueryTracker struct {
	// contains filtered or unexported fields
}

func NewActiveQueryTracker 

func NewActiveQueryTracker(localStoragePath string, maxConcurrent int, logger log.Logger) *ActiveQueryTracker

func (*ActiveQueryTracker) Close added in v0.46.0 

func (tracker *ActiveQueryTracker) Close()

func (ActiveQueryTracker) Delete 

func (tracker ActiveQueryTracker) Delete(insertIndex int)

func (ActiveQueryTracker) GetMaxConcurrent 

func (tracker ActiveQueryTracker) GetMaxConcurrent() int

func (ActiveQueryTracker) Insert 

func (tracker ActiveQueryTracker) Insert(ctx context.Context, query string) (int, error)

type Engine 

type Engine struct {
	// contains filtered or unexported fields
}

Engine handles the lifetime of queries from beginning to end. It is connected to a querier.

func NewEngine 

func NewEngine(opts EngineOpts) *Engine

NewEngine returns a new engine.

func (*Engine) NewInstantQuery 

func (ng *Engine) NewInstantQuery(ctx context.Context, q storage.Queryable, opts QueryOpts, qs string, ts time.Time) (Query, error)

NewInstantQuery returns an evaluation query for the given expression at the given time.

func (*Engine) NewRangeQuery 

func (ng *Engine) NewRangeQuery(ctx context.Context, q storage.Queryable, opts QueryOpts, qs string, start, end time.Time, interval time.Duration) (Query, error)

NewRangeQuery returns an evaluation query for the given time range and with the resolution set by the interval.

func (*Engine) SetQueryLogger 

func (ng *Engine) SetQueryLogger(l QueryLogger)

SetQueryLogger sets the query logger.

type EngineOpts 

type EngineOpts struct {
	Logger             log.Logger
	Reg                prometheus.Registerer
	MaxSamples         int
	Timeout            time.Duration
	ActiveQueryTracker QueryTracker
	// LookbackDelta determines the time since the last sample after which a time
	// series is considered stale.
	LookbackDelta time.Duration

	// NoStepSubqueryIntervalFn is the default evaluation interval of
	// a subquery in milliseconds if no step in range vector was specified `[30m:<step>]`.
	NoStepSubqueryIntervalFn func(rangeMillis int64) int64

	// EnableAtModifier if true enables @ modifier. Disabled otherwise. This
	// is supposed to be enabled for regular PromQL (as of Prometheus v2.33)
	// but the option to disable it is still provided here for those using
	// the Engine outside of Prometheus.
	EnableAtModifier bool

	// EnableNegativeOffset if true enables negative (-) offset
	// values. Disabled otherwise. This is supposed to be enabled for
	// regular PromQL (as of Prometheus v2.33) but the option to disable it
	// is still provided here for those using the Engine outside of
	// Prometheus.
	EnableNegativeOffset bool

	// EnablePerStepStats if true allows for per-step stats to be computed on request. Disabled otherwise.
	EnablePerStepStats bool
}

EngineOpts contains configuration options used when creating a new Engine.

type Entry 

type Entry struct {
	Query     string `json:"query"`
	Timestamp int64  `json:"timestamp_sec"`
}

type ErrQueryCanceled 

type ErrQueryCanceled string

ErrQueryCanceled is returned if a query was canceled during processing.

func (ErrQueryCanceled) Error 

func (e ErrQueryCanceled) Error() string

type ErrQueryTimeout 

type ErrQueryTimeout string

ErrQueryTimeout is returned if a query timed out during processing.

func (ErrQueryTimeout) Error 

func (e ErrQueryTimeout) Error() string

type ErrStorage 

type ErrStorage struct{ Err error }

ErrStorage is returned if an error was encountered in the storage layer during query handling.

func (ErrStorage) Error 

func (e ErrStorage) Error() string

type ErrTooManySamples 

type ErrTooManySamples string

ErrTooManySamples is returned if a query would load more than the maximum allowed samples into memory.

func (ErrTooManySamples) Error 

func (e ErrTooManySamples) Error() string

type EvalNodeHelper 

type EvalNodeHelper struct {
	// Evaluation timestamp.
	Ts int64
	// Vector that can be used for output.
	Out Vector

	// Caches.
	// DropMetricName and label_*.
	Dmn map[uint64]labels.Labels
	// contains filtered or unexported fields
}

EvalNodeHelper stores extra information and caches for evaluating a single node across steps.

func (*EvalNodeHelper) DropMetricName 

func (enh *EvalNodeHelper) DropMetricName(l labels.Labels) labels.Labels

DropMetricName is a cached version of DropMetricName.

type EvalSeriesHelper 

type EvalSeriesHelper struct {
	// contains filtered or unexported fields
}

EvalSeriesHelper stores extra information about a series.

type FPoint added in v0.44.0 

type FPoint struct {
	T int64
	F float64
}

FPoint represents a single float data point for a given timestamp.

func (FPoint) MarshalJSON added in v0.44.0 

func (p FPoint) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

JSON marshaling is only needed for the HTTP API. Since FPoint is such a frequently marshaled type, it gets an optimized treatment directly in web/api/v1/api.go. Therefore, this method is unused within Prometheus. It is still provided here as convenience for debugging and for other users of this code. Also note that the different marshaling implementations might lead to slightly different results in terms of formatting and rounding of the timestamp.

func (FPoint) String added in v0.44.0 

func (p FPoint) String() string

type FunctionCall 

type FunctionCall func(vals []parser.Value, args parser.Expressions, enh *EvalNodeHelper) (Vector, annotations.Annotations)

FunctionCall is the type of a PromQL function implementation

vals is a list of the evaluated arguments for the function call.

For range vectors it will be a Matrix with one series, instant vectors a Vector, scalars a Vector with one series whose value is the scalar value,and nil for strings.

args are the original arguments to the function, where you can access matrixSelectors, vectorSelectors, and StringLiterals.

enh.Out is a pre-allocated empty vector that you may use to accumulate output before returning it. The vectors in vals should not be returned.a

Range vector functions need only return a vector with the right value, the metric and timestamp are not needed.

Instant vector functions need only return a vector with the right values and metrics, the timestamp are not needed.

Scalar results should be returned as the value of a sample in a Vector.

type HPoint added in v0.44.0 

type HPoint struct {
	T int64
	H *histogram.FloatHistogram
}

HPoint represents a single histogram data point for a given timestamp. H must never be nil.

func (HPoint) MarshalJSON added in v0.44.0 

func (p HPoint) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

JSON marshaling is only needed for the HTTP API. Since HPoint is such a frequently marshaled type, it gets an optimized treatment directly in web/api/v1/api.go. Therefore, this method is unused within Prometheus. It is still provided here as convenience for debugging and for other users of this code. Also note that the different marshaling implementations might lead to slightly different results in terms of formatting and rounding of the timestamp.

func (HPoint) String added in v0.44.0 

func (p HPoint) String() string

type LazyLoader 

type LazyLoader struct {
	testutil.T

	SubqueryInterval time.Duration
	// contains filtered or unexported fields
}

LazyLoader lazily loads samples into storage. This is specifically implemented for unit testing of rules.

func NewLazyLoader 

func NewLazyLoader(t testutil.T, input string, opts LazyLoaderOpts) (*LazyLoader, error)

NewLazyLoader returns an initialized empty LazyLoader.

func (*LazyLoader) Close 

func (ll *LazyLoader) Close()

Close closes resources associated with the LazyLoader.

func (*LazyLoader) Context 

func (ll *LazyLoader) Context() context.Context

Context returns the LazyLoader's context.

func (*LazyLoader) QueryEngine 

func (ll *LazyLoader) QueryEngine() *Engine

QueryEngine returns the LazyLoader's query engine.

func (*LazyLoader) Queryable 

func (ll *LazyLoader) Queryable() storage.Queryable

Queryable allows querying the LazyLoader's data. Note: only the samples till the max timestamp used in `WithSamplesTill` can be queried.

func (*LazyLoader) Storage 

func (ll *LazyLoader) Storage() storage.Storage

Storage returns the LazyLoader's storage.

func (*LazyLoader) WithSamplesTill 

func (ll *LazyLoader) WithSamplesTill(ts time.Time, fn func(error))

WithSamplesTill loads the samples till given timestamp and executes the given function.

type LazyLoaderOpts 

type LazyLoaderOpts struct {
	// Both of these must be set to true for regular PromQL (as of
	// Prometheus v2.33). They can still be disabled here for legacy and
	// other uses.
	EnableAtModifier, EnableNegativeOffset bool
}

LazyLoaderOpts are options for the lazy loader.

type Matrix 

type Matrix []Series

Matrix is a slice of Series that implements sort.Interface and has a String method.

func (Matrix) ContainsSameLabelset 

func (m Matrix) ContainsSameLabelset() bool

ContainsSameLabelset checks if a matrix has samples with the same labelset. Such a behavior is semantically undefined. https://github.com/prometheus/prometheus/issues/4562

func (Matrix) Len 

func (m Matrix) Len() int

func (Matrix) Less 

func (m Matrix) Less(i, j int) bool

func (Matrix) String 

func (m Matrix) String() string

func (Matrix) Swap 

func (m Matrix) Swap(i, j int)

func (Matrix) TotalSamples 

func (m Matrix) TotalSamples() int

TotalSamples returns the total number of samples in the series within a matrix. Float samples have a weight of 1 in this number, while histogram samples have a higher weight according to their size compared with the size of a float sample. See HPoint.size for details.

func (Matrix) Type 

func (Matrix) Type() parser.ValueType

type PrometheusQueryOpts added in v0.46.0 

type PrometheusQueryOpts struct {
	// contains filtered or unexported fields
}

func (*PrometheusQueryOpts) EnablePerStepStats added in v0.46.0 

func (p *PrometheusQueryOpts) EnablePerStepStats() bool

func (*PrometheusQueryOpts) LookbackDelta added in v0.46.0 

func (p *PrometheusQueryOpts) LookbackDelta() time.Duration

type Query 

type Query interface {
	// Exec processes the query. Can only be called once.
	Exec(ctx context.Context) *Result
	// Close recovers memory used by the query result.
	Close()
	// Statement returns the parsed statement of the query.
	Statement() parser.Statement
	// Stats returns statistics about the lifetime of the query.
	Stats() *stats.Statistics
	// Cancel signals that a running query execution should be aborted.
	Cancel()
	// String returns the original query string.
	String() string
}

A Query is derived from an a raw query string and can be run against an engine it is associated with.

type QueryLogger 

type QueryLogger interface {
	Log(...interface{}) error
	Close() error
}

QueryLogger is an interface that can be used to log all the queries logged by the engine.

type QueryOpts 

type QueryOpts interface {
	// Enables recording per-step statistics if the engine has it enabled as well. Disabled by default.
	EnablePerStepStats() bool
	// Lookback delta duration for this query.
	LookbackDelta() time.Duration
}

func NewPrometheusQueryOpts added in v0.46.0 

func NewPrometheusQueryOpts(enablePerStepStats bool, lookbackDelta time.Duration) QueryOpts

type QueryOrigin 

type QueryOrigin struct{}

type QueryTracker 

type QueryTracker interface {
	// GetMaxConcurrent returns maximum number of concurrent queries that are allowed by this tracker.
	GetMaxConcurrent() int

	// Insert inserts query into query tracker. This call must block if maximum number of queries is already running.
	// If Insert doesn't return error then returned integer value should be used in subsequent Delete call.
	// Insert should return error if context is finished before query can proceed, and integer value returned in this case should be ignored by caller.
	Insert(ctx context.Context, query string) (int, error)

	// Delete removes query from activity tracker. InsertIndex is value returned by Insert call.
	Delete(insertIndex int)
}

QueryTracker provides access to two features:

1) Tracking of active query. If PromQL engine crashes while executing any query, such query should be present in the tracker on restart, hence logged. After the logging on restart, the tracker gets emptied.

2) Enforcement of the maximum number of concurrent queries.

type Result 

type Result struct {
	Err      error
	Value    parser.Value
	Warnings annotations.Annotations
}

Result holds the resulting value of an execution or an error if any occurred.

func (*Result) Matrix 

func (r *Result) Matrix() (Matrix, error)

Matrix returns a Matrix. An error is returned if the result was an error or the result value is not a Matrix.

func (*Result) Scalar 

func (r *Result) Scalar() (Scalar, error)

Scalar returns a Scalar value. An error is returned if the result was an error or the result value is not a Scalar.

func (*Result) String 

func (r *Result) String() string

func (*Result) Vector 

func (r *Result) Vector() (Vector, error)

Vector returns a Vector if the result value is one. An error is returned if the result was an error or the result value is not a Vector.

type Sample 

type Sample struct {
	T int64
	F float64
	H *histogram.FloatHistogram

	Metric labels.Labels
}

Sample is a single sample belonging to a metric. It represents either a float sample or a histogram sample. If H is nil, it is a float sample. Otherwise, it is a histogram sample.

func (Sample) MarshalJSON 

func (s Sample) MarshalJSON() ([]byte, error)

MarshalJSON is mirrored in web/api/v1/api.go with jsoniter because FPoint and HPoint wouldn't be marshaled with jsoniter otherwise.

func (Sample) String 

func (s Sample) String() string

type Scalar 

type Scalar struct {
	T int64
	V float64
}

Scalar is a data point that's explicitly not associated with a metric.

func (Scalar) MarshalJSON 

func (s Scalar) MarshalJSON() ([]byte, error)

func (Scalar) String 

func (s Scalar) String() string

func (Scalar) Type 

func (Scalar) Type() parser.ValueType

type Series 

type Series struct {
	Metric     labels.Labels `json:"metric"`
	Floats     []FPoint      `json:"values,omitempty"`
	Histograms []HPoint      `json:"histograms,omitempty"`
}

Series is a stream of data points belonging to a metric.

func (Series) String 

func (s Series) String() string

type StorageSeries 

type StorageSeries struct {
	// contains filtered or unexported fields
}

StorageSeries simulates promql.Series as storage.Series.

func NewStorageSeries 

func NewStorageSeries(series Series) *StorageSeries

NewStorageSeries returns a StorageSeries from a Series.

func (*StorageSeries) Iterator 

func (ss *StorageSeries) Iterator(it chunkenc.Iterator) chunkenc.Iterator

Iterator returns a new iterator of the data of the series. In case of multiple samples with the same timestamp, it returns the float samples first.

func (*StorageSeries) Labels 

func (ss *StorageSeries) Labels() labels.Labels

type String 

type String struct {
	T int64
	V string
}

String represents a string value.

func (String) MarshalJSON 

func (s String) MarshalJSON() ([]byte, error)

func (String) String 

func (s String) String() string

func (String) Type 

func (String) Type() parser.ValueType

type Vector 

type Vector []Sample

Vector is basically only an alias for []Sample, but the contract is that in a Vector, all Samples have the same timestamp.

func (Vector) ContainsSameLabelset 

func (vec Vector) ContainsSameLabelset() bool

ContainsSameLabelset checks if a vector has samples with the same labelset Such a behavior is semantically undefined https://github.com/prometheus/prometheus/issues/4562

func (Vector) String 

func (vec Vector) String() string

func (Vector) TotalSamples added in v0.49.0 

func (vec Vector) TotalSamples() int

TotalSamples returns the total number of samples in the series within a vector. Float samples have a weight of 1 in this number, while histogram samples have a higher weight according to their size compared with the size of a float sample. See HPoint.size for details.

func (Vector) Type 

func (Vector) Type() parser.ValueType

Source Files

View all Source files

Directories

Path Synopsis
posrange
posrange is used to report a position in query strings for error and warning messages.
 posrange is used to report a position in query strings for error and warning messages.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.