Documentation
¶
Overview ¶
Package metricsql implements MetricsQL parser.
This parser can parse PromQL. Additionally it can parse all the MetricsQL extensions. See https://github.com/VictoriaMetrics/VictoriaMetrics/wiki/ExtendedPromQL for details about MetricsQL extensions.
Usage:
expr, err := metricsql.Parse(`sum(rate(foo{bar="baz"}[5m])) by (job)`)
if err != nil {
// parse error
}
// Now expr contains parsed MetricsQL as `*Expr` structs.
// See Parse examples for more details.
Index ¶
- func CompileRegexp(re string) (*regexp.Regexp, error)
- func CompileRegexpAnchored(re string) (*regexp.Regexp, error)
- func DurationValue(s string, step int64) (int64, error)
- func ExpandWithExprs(q string) (string, error)
- func IsBinaryOpCmp(op string) bool
- func IsRollupFunc(funcName string) bool
- func IsTransformFunc(funcName string) bool
- func PositiveDurationValue(s string, step int64) (int64, error)
- type AggrFuncExpr
- type BinaryOpExpr
- type Expr
- type FuncExpr
- type LabelFilter
- type MetricExpr
- type ModifierExpr
- type NumberExpr
- type RollupExpr
- type StringExpr
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CompileRegexp ¶
CompileRegexp returns compile regexp re.
func CompileRegexpAnchored ¶
CompileRegexpAnchored returns compiled regexp `^re$`.
func DurationValue ¶
DurationValue returns the duration in milliseconds for the given s and the given step.
The returned duration value can be negative.
func ExpandWithExprs ¶
ExpandWithExprs expands WITH expressions inside q and returns the resulting PromQL without WITH expressions.
Example ¶
package main
import (
"fmt"
"log"
"github.com/VictoriaMetrics/VictoriaMetrics/lib/metricsql"
)
func main() {
// mql can contain arbitrary MetricsQL extensions - see https://github.com/VictoriaMetrics/VictoriaMetrics/wiki/ExtendedPromQL
mql := `WITH (
commonFilters = {job="$job", instance="$instance"},
f(a, b) = 100*(a/b),
)
f(disk_free_bytes{commonFilters}, disk_total_bytes{commonFilters})`
// Convert mql to PromQL
pql, err := metricsql.ExpandWithExprs(mql)
if err != nil {
log.Fatalf("cannot expand with expressions: %s", err)
}
fmt.Printf("%s\n", pql)
}
Output: 100 * (disk_free_bytes{job="$job", instance="$instance"} / disk_total_bytes{job="$job", instance="$instance"})
func IsBinaryOpCmp ¶
IsBinaryOpCmp returns true if op is comparison operator such as '==', '!=', etc.
func IsRollupFunc ¶ added in v1.32.0
IsRollupFunc returns whether funcName is known rollup function.
func IsTransformFunc ¶ added in v1.32.0
IsTransformFunc returns whether funcName is known transform function.
Types ¶
type AggrFuncExpr ¶
type AggrFuncExpr struct {
// Name is the function name.
Name string
// Args is the function args.
Args []Expr
// Modifier is optional modifier such as `by (...)` or `without (...)`.
Modifier ModifierExpr
}
AggrFuncExpr represents aggregate function such as `sum(...) by (...)`
func (*AggrFuncExpr) AppendString ¶
func (ae *AggrFuncExpr) AppendString(dst []byte) []byte
AppendString appends string representation of ae to dst and returns the result.
type BinaryOpExpr ¶
type BinaryOpExpr struct {
// Op is the operation itself, i.e. `+`, `-`, `*`, etc.
Op string
// Bool indicates whether `bool` modifier is present.
// For example, `foo >bool bar`.
Bool bool
// GroupModifier contains modifier such as "on" or "ignoring".
GroupModifier ModifierExpr
// JoinModifier contains modifier such as "group_left" or "group_right".
JoinModifier ModifierExpr
// Left contains left arg for the `left op right` expression.
Left Expr
// Right contains right arg for the `left op right` epxression.
Right Expr
}
BinaryOpExpr represents binary operation.
func (*BinaryOpExpr) AppendString ¶
func (be *BinaryOpExpr) AppendString(dst []byte) []byte
AppendString appends string representation of be to dst and returns the result.
type Expr ¶
type Expr interface {
// AppendString appends string representation of Expr to dst.
AppendString(dst []byte) []byte
}
Expr holds any of *Expr types.
func Parse ¶
Parse parses MetricsQL query s.
All the `WITH` expressions are expanded in the returned Expr.
MetricsQL is backwards-compatible with PromQL.
Example ¶
package main
import (
"fmt"
"log"
"github.com/VictoriaMetrics/VictoriaMetrics/lib/metricsql"
)
func main() {
expr, err := metricsql.Parse(`sum(rate(foo{bar="baz"}[5m])) by (x,y)`)
if err != nil {
log.Fatalf("parse error: %s", err)
}
fmt.Printf("parsed expr: %s\n", expr.AppendString(nil))
ae := expr.(*metricsql.AggrFuncExpr)
fmt.Printf("aggr func: name=%s, arg=%s, modifier=%s\n", ae.Name, ae.Args[0].AppendString(nil), ae.Modifier.AppendString(nil))
fe := ae.Args[0].(*metricsql.FuncExpr)
fmt.Printf("func: name=%s, arg=%s\n", fe.Name, fe.Args[0].AppendString(nil))
re := fe.Args[0].(*metricsql.RollupExpr)
fmt.Printf("rollup: expr=%s, window=%s\n", re.Expr.AppendString(nil), re.Window)
me := re.Expr.(*metricsql.MetricExpr)
fmt.Printf("metric: labelFilter1=%s, labelFilter2=%s", me.LabelFilters[0].AppendString(nil), me.LabelFilters[1].AppendString(nil))
}
Output: parsed expr: sum(rate(foo{bar="baz"}[5m])) by (x, y) aggr func: name=sum, arg=rate(foo{bar="baz"}[5m]), modifier=by (x, y) func: name=rate, arg=foo{bar="baz"}[5m] rollup: expr=foo{bar="baz"}, window=5m metric: labelFilter1=__name__="foo", labelFilter2=bar="baz"
type FuncExpr ¶
type FuncExpr struct {
// Name is function name.
Name string
// Args contains function args.
Args []Expr
}
FuncExpr represetns MetricsQL function such as `foo(...)`
func (*FuncExpr) AppendString ¶
AppendString appends string representation of fe to dst and returns the result.
type LabelFilter ¶
type LabelFilter struct {
// Label contains label name for the filter.
Label string
// Value contains unquoted value for the filter.
Value string
// IsNegative reperesents whether the filter is negative, i.e. '!=' or '!~'.
IsNegative bool
// IsRegexp represents whether the filter is regesp, i.e. `=~` or `!~`.
IsRegexp bool
}
LabelFilter represents MetricsQL label filter like `foo="bar"`.
func (*LabelFilter) AppendString ¶
func (lf *LabelFilter) AppendString(dst []byte) []byte
AppendString appends string representation of me to dst and returns the result.
type MetricExpr ¶
type MetricExpr struct {
// LabelFilters contains a list of label filters from curly braces.
// Metric name if present must be the first.
LabelFilters []LabelFilter
// contains filtered or unexported fields
}
MetricExpr represents MetricsQL metric with optional filters, i.e. `foo{...}`.
func (*MetricExpr) AppendString ¶
func (me *MetricExpr) AppendString(dst []byte) []byte
AppendString appends string representation of me to dst and returns the result.
func (*MetricExpr) IsEmpty ¶
func (me *MetricExpr) IsEmpty() bool
IsEmpty returns true of me equals to `{}`.
type ModifierExpr ¶
type ModifierExpr struct {
// Op is modifier operation.
Op string
// Args contains modifier args from parens.
Args []string
}
ModifierExpr represents MetricsQL modifier such as `<op> (...)`
func (*ModifierExpr) AppendString ¶
func (me *ModifierExpr) AppendString(dst []byte) []byte
AppendString appends string representation of me to dst and returns the result.
type NumberExpr ¶
type NumberExpr struct {
// N is the parsed number, i.e. `1.23`, `-234`, etc.
N float64
}
NumberExpr represents number expression.
func (*NumberExpr) AppendString ¶
func (ne *NumberExpr) AppendString(dst []byte) []byte
AppendString appends string representation of ne to dst and returns the result.
type RollupExpr ¶
type RollupExpr struct {
// The expression for the rollup. Usually it is MetricExpr, but may be arbitrary expr
// if subquery is used. https://prometheus.io/blog/2019/01/28/subquery-support/
Expr Expr
// Window contains optional window value from square brackets
//
// For example, `http_requests_total[5m]` will have Window value `5m`.
Window string
// Offset contains optional value from `offset` part.
//
// For example, `foobar{baz="aa"} offset 5m` will have Offset value `5m`.
Offset string
// Step contains optional step value from square brackets.
//
// For example, `foobar[1h:3m]` will have Step value '3m'.
Step string
// If set to true, then `foo[1h:]` would print the same
// instead of `foo[1h]`.
InheritStep bool
}
RollupExpr represents MetricsQL expression, which contains at least `offset` or `[...]` part.
func (*RollupExpr) AppendString ¶
func (re *RollupExpr) AppendString(dst []byte) []byte
AppendString appends string representation of re to dst and returns the result.
func (*RollupExpr) ForSubquery ¶
func (re *RollupExpr) ForSubquery() bool
ForSubquery returns true if re represents subquery.
type StringExpr ¶
type StringExpr struct {
// S contains unquoted value for string expression.
S string
// contains filtered or unexported fields
}
StringExpr represents string expression.
func (*StringExpr) AppendString ¶
func (se *StringExpr) AppendString(dst []byte) []byte
AppendString appends string representation of se to dst and returns the result.