promql

package
v2.13.1 Latest Latest
Warning

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

 Go to latest Published: Oct 8, 2023 License: Apache-2.0 Imports: 34 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	ValueTypeNone   = "none"
	ValueTypeVector = "vector"
	ValueTypeScalar = "scalar"
	ValueTypeMatrix = "matrix"
	ValueTypeString = "string"
)

The valid value types.

View Source 
const LowestPrec = 0 // Non-operators.

LowestPrec is a constant for operator precedence in expressions.

Variables

View Source 
var (
	// LookbackDelta determines the time since the last sample after which a time
	// series is considered stale.
	LookbackDelta = 5 * time.Minute

	// DefaultEvaluationInterval is the default evaluation interval of
	// a subquery in milliseconds.
	DefaultEvaluationInterval int64
)

Functions

func GetDefaultEvaluationInterval 

func GetDefaultEvaluationInterval() int64

GetDefaultEvaluationInterval returns the DefaultEvaluationInterval as time.Duration.

func Inspect 

func Inspect(node Node, f inspector)

Inspect traverses an AST in depth-first order: It starts by calling f(node, path); node must not be nil. If f returns a nil error, Inspect invokes f for all the non-nil children of node, recursively.

func ParseMetric 

func ParseMetric(input string) (m labels.Labels, err error)

ParseMetric parses the input into a metric

func ParseMetricSelector 

func ParseMetricSelector(input string) (m []*labels.Matcher, err error)

ParseMetricSelector parses the provided textual metric selector into a list of label matchers.

func SetDefaultEvaluationInterval 

func SetDefaultEvaluationInterval(ev time.Duration)

SetDefaultEvaluationInterval sets DefaultEvaluationInterval.

func Tree 

func Tree(node Node) string

Tree returns a string of the tree structure of the given node.

func Walk 

func Walk(v Visitor, node Node, path []Node) error

Walk traverses an AST in depth-first order: It starts by calling v.Visit(node, path); node must not be nil. If the visitor w returned by v.Visit(node, path) is not nil and the visitor returns no error, Walk is invoked recursively with visitor w for each of the non-nil children of node, followed by a call of w.Visit(nil), returning an error As the tree is descended the path of previous nodes is provided.

Types

type ActiveQueryTracker 

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

func NewActiveQueryTracker 

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

func (ActiveQueryTracker) Delete 

func (tracker ActiveQueryTracker) Delete(insertIndex int)

func (ActiveQueryTracker) Insert 

func (tracker ActiveQueryTracker) Insert(query string) int

type AggregateExpr 

type AggregateExpr struct {
	Op       ItemType // The used aggregation operation.
	Expr     Expr     // The Vector expression over which is aggregated.
	Param    Expr     // Parameter used by some aggregators.
	Grouping []string // The labels by which to group the Vector.
	Without  bool     // Whether to drop the given labels rather than keep them.
}

AggregateExpr represents an aggregation operation on a Vector.

func (*AggregateExpr) String 

func (node *AggregateExpr) String() string

func (*AggregateExpr) Type 

func (e *AggregateExpr) Type() ValueType

type BinaryExpr 

type BinaryExpr struct {
	Op       ItemType // The operation of the expression.
	LHS, RHS Expr     // The operands on the respective sides of the operator.

	// The matching behavior for the operation if both operands are Vectors.
	// If they are not this field is nil.
	VectorMatching *VectorMatching

	// If a comparison operator, return 0/1 rather than filtering.
	ReturnBool bool
}

BinaryExpr represents a binary expression between two child expressions.

func (*BinaryExpr) String 

func (node *BinaryExpr) String() string

func (*BinaryExpr) Type 

func (e *BinaryExpr) Type() ValueType

type Call 

type Call struct {
	Func *Function   // The function that was called.
	Args Expressions // Arguments used in the call.
}

Call represents a function call.

func (*Call) String 

func (node *Call) String() string

func (*Call) Type 

func (e *Call) Type() ValueType

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(q storage.Queryable, 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(q storage.Queryable, 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.

type EngineOpts 

type EngineOpts struct {
	Logger             log.Logger
	Reg                prometheus.Registerer
	MaxConcurrent      int
	MaxSamples         int
	Timeout            time.Duration
	ActiveQueryTracker *ActiveQueryTracker
}

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 {
	// contains filtered or unexported fields
}

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

type EvalStmt 

type EvalStmt struct {
	Expr Expr // Expression to be evaluated.

	// The time boundaries for the evaluation. If Start equals End an instant
	// is evaluated.
	Start, End time.Time
	// Time between two evaluated instants for the range [Start:End].
	Interval time.Duration
}

EvalStmt holds an expression and information on the range it should be evaluated on.

func (*EvalStmt) String 

func (node *EvalStmt) String() string

type Expr 

type Expr interface {
	Node

	// Type returns the type the expression evaluates to. It does not perform
	// in-depth checks as this is done at parsing-time.
	Type() ValueType
	// contains filtered or unexported methods
}

Expr is a generic interface for all expression types.

func ParseExpr 

func ParseExpr(input string) (Expr, error)

ParseExpr returns the expression parsed from the input.

type Expressions 

type Expressions []Expr

Expressions is a list of expression nodes that implements Node.

func (Expressions) String 

func (es Expressions) String() (s string)

type Function 

type Function struct {
	Name       string
	ArgTypes   []ValueType
	Variadic   int
	ReturnType ValueType

	// 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.
	Call func(vals []Value, args Expressions, enh *EvalNodeHelper) Vector
}

Function represents a function of the expression language and is used by function nodes.

type ItemType 

type ItemType int
const (
	ItemError ItemType = iota // Error occurred, value is error message
	ItemEOF
	ItemComment
	ItemIdentifier
	ItemMetricIdentifier
	ItemLeftParen
	ItemRightParen
	ItemLeftBrace
	ItemRightBrace
	ItemLeftBracket
	ItemRightBracket
	ItemComma
	ItemAssign
	ItemColon
	ItemSemicolon
	ItemString
	ItemNumber
	ItemDuration
	ItemBlank
	ItemTimes
	ItemSpace

	// Operators.
	ItemSUB
	ItemADD
	ItemMUL
	ItemMOD
	ItemDIV
	ItemLAND
	ItemLOR
	ItemLUnless
	ItemEQL
	ItemNEQ
	ItemLTE
	ItemLSS
	ItemGTE
	ItemGTR
	ItemEQLRegex
	ItemNEQRegex
	ItemPOW

	// Aggregators.
	ItemAvg
	ItemCount
	ItemSum
	ItemMin
	ItemMax
	ItemStddev
	ItemStdvar
	ItemTopK
	ItemBottomK
	ItemCountValues
	ItemQuantile

	// Keywords.
	ItemOffset
	ItemBy
	ItemWithout
	ItemOn
	ItemIgnoring
	ItemGroupLeft
	ItemGroupRight
	ItemBool
)

func (ItemType) String 

func (i ItemType) String() string

type LazyLoader 

type LazyLoader struct {
	testutil.T
	// 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) (*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 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/zpascal/prometheus/v2/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.

func (Matrix) Type 

func (Matrix) Type() ValueType

type MatrixSelector 

type MatrixSelector struct {
	Name          string
	Range         time.Duration
	Offset        time.Duration
	LabelMatchers []*labels.Matcher
	// contains filtered or unexported fields
}

MatrixSelector represents a Matrix selection.

func (*MatrixSelector) String 

func (node *MatrixSelector) String() string

func (*MatrixSelector) Type 

func (e *MatrixSelector) Type() ValueType

type Node 

type Node interface {
	// String representation of the node that returns the given node when parsed
	// as part of a valid query.
	String() string
}

Node is a generic interface for all nodes in an AST.

Whenever numerous nodes are listed such as in a switch-case statement or a chain of function definitions (e.g. String(), expr(), etc.) convention is to list them as follows:

  • Statements
  • statement types (alphabetical)
  • ...
  • Expressions
  • expression types (alphabetical)
  • ...

type NumberLiteral 

type NumberLiteral struct {
	Val float64
}

NumberLiteral represents a number.

func (*NumberLiteral) String 

func (node *NumberLiteral) String() string

func (*NumberLiteral) Type 

func (e *NumberLiteral) Type() ValueType

type ParenExpr 

type ParenExpr struct {
	Expr Expr
}

ParenExpr wraps an expression so it cannot be disassembled as a consequence of operator precedence.

func (*ParenExpr) String 

func (node *ParenExpr) String() string

func (*ParenExpr) Type 

func (e *ParenExpr) Type() ValueType

type ParseErr 

type ParseErr struct {
	Line, Pos int
	Err       error
}

ParseErr wraps a parsing error with line and position context. If the parsing input was a single line, line will be 0 and omitted from the error string.

func (*ParseErr) Error 

func (e *ParseErr) Error() string

type Point 

type Point struct {
	T int64
	V float64
}

Point represents a single data point for a given timestamp.

func (Point) MarshalJSON 

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

MarshalJSON implements json.Marshaler.

func (Point) String 

func (p Point) String() string

type Pos 

type Pos int

Pos is the position in a string.

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() Statement
	// Stats returns statistics about the lifetime of the query.
	Stats() *stats.QueryTimers
	// Cancel signals that a running query execution should be aborted.
	Cancel()
}

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

type Result 

type Result struct {
	Err      error
	Value    Value
	Warnings storage.Warnings
}

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 {
	Point

	Metric labels.Labels
}

Sample is a single sample belonging to a metric.

func (Sample) MarshalJSON 

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

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() ValueType

type Series 

type Series struct {
	Metric labels.Labels `json:"metric"`
	Points []Point       `json:"values"`
}

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

func (Series) String 

func (s Series) String() string

type Statement 

type Statement interface {
	Node
	// contains filtered or unexported methods
}

Statement is a generic interface for all statements.

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 fromfor series.

func (*StorageSeries) Iterator 

func (ss *StorageSeries) Iterator() storage.SeriesIterator

Iterator returns a new iterator of the data of the series.

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() ValueType

type StringLiteral 

type StringLiteral struct {
	Val string
}

StringLiteral represents a string.

func (*StringLiteral) String 

func (node *StringLiteral) String() string

func (*StringLiteral) Type 

func (e *StringLiteral) Type() ValueType

type SubqueryExpr 

type SubqueryExpr struct {
	Expr   Expr
	Range  time.Duration
	Offset time.Duration
	Step   time.Duration
}

SubqueryExpr represents a subquery.

func (*SubqueryExpr) String 

func (node *SubqueryExpr) String() string

func (*SubqueryExpr) Type 

func (e *SubqueryExpr) Type() ValueType

type Test 

type Test struct {
	testutil.T
	// contains filtered or unexported fields
}

Test is a sequence of read and write commands that are run against a test storage.

func NewTest 

func NewTest(t testutil.T, input string) (*Test, error)

NewTest returns an initialized empty Test.

func (*Test) Close 

func (t *Test) Close()

Close closes resources associated with the Test.

func (*Test) Context 

func (t *Test) Context() context.Context

Context returns the test's context.

func (*Test) QueryEngine 

func (t *Test) QueryEngine() *Engine

QueryEngine returns the test's query engine.

func (*Test) Queryable 

func (t *Test) Queryable() storage.Queryable

Queryable allows querying the test data.

func (*Test) Run 

func (t *Test) Run() error

Run executes the command sequence of the test. Until the maximum error number is reached, evaluation errors do not terminate execution.

func (*Test) Storage 

func (t *Test) Storage() storage.Storage

Storage returns the test's storage.

type UnaryExpr 

type UnaryExpr struct {
	Op   ItemType
	Expr Expr
}

UnaryExpr represents a unary operation on another expression. Currently unary operations are only supported for Scalars.

func (*UnaryExpr) String 

func (node *UnaryExpr) String() string

func (*UnaryExpr) Type 

func (e *UnaryExpr) Type() ValueType

type Value 

type Value interface {
	Type() ValueType
	String() string
}

Value is a generic interface for values resulting from a query evaluation.

type ValueType 

type ValueType string

ValueType describes a type of a value.

type Vector 

type Vector []Sample

Vector is basically only an alias for model.Samples, 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/zpascal/prometheus/v2/issues/4562

func (Vector) String 

func (vec Vector) String() string

func (Vector) Type 

func (Vector) Type() ValueType

type VectorMatchCardinality 

type VectorMatchCardinality int

VectorMatchCardinality describes the cardinality relationship of two Vectors in a binary operation. 

const (
	CardOneToOne VectorMatchCardinality = iota
	CardManyToOne
	CardOneToMany
	CardManyToMany
)

func (VectorMatchCardinality) String 

func (vmc VectorMatchCardinality) String() string

type VectorMatching 

type VectorMatching struct {
	// The cardinality of the two Vectors.
	Card VectorMatchCardinality
	// MatchingLabels contains the labels which define equality of a pair of
	// elements from the Vectors.
	MatchingLabels []string
	// On includes the given label names from matching,
	// rather than excluding them.
	On bool
	// Include contains additional labels that should be included in
	// the result from the side with the lower cardinality.
	Include []string
}

VectorMatching describes how elements from two Vectors in a binary operation are supposed to be matched.

type VectorSelector 

type VectorSelector struct {
	Name          string
	Offset        time.Duration
	LabelMatchers []*labels.Matcher
	// contains filtered or unexported fields
}

VectorSelector represents a Vector selection.

func (*VectorSelector) String 

func (node *VectorSelector) String() string

func (*VectorSelector) Type 

func (e *VectorSelector) Type() ValueType

type Visitor 

type Visitor interface {
	Visit(node Node, path []Node) (w Visitor, err error)
}

Visitor allows visiting a Node and its child nodes. The Visit method is invoked for each node with the path leading to the node provided additionally. If the result visitor w is not nil and no error, Walk visits each of the children of node with the visitor w, followed by a call of w.Visit(nil, nil).

Source Files

View all Source files

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.