metricsql

Documentation

Overview

Package metricsql implements MetricsQL parser.

This parser can parse PromQL. Additionally it can parse 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 metricsql.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 PositiveDurationValue(s string, step int64) (int64, error)
• type AggrFuncExpr
  • func (ae *AggrFuncExpr) AppendString(dst []byte) []byte
• type BinaryOpExpr
  • func (be *BinaryOpExpr) AppendString(dst []byte) []byte
• type Expr
  • func Parse(s string) (Expr, error)
• type FuncExpr
  • func (fe *FuncExpr) AppendString(dst []byte) []byte
• type LabelFilter
  • func (lf *LabelFilter) AppendString(dst []byte) []byte
• type MetricExpr
  • func (me *MetricExpr) AppendString(dst []byte) []byte
  • func (me *MetricExpr) IsEmpty() bool
• type ModifierExpr
  • func (me *ModifierExpr) AppendString(dst []byte) []byte
• type NumberExpr
  • func (ne *NumberExpr) AppendString(dst []byte) []byte
• type RollupExpr
  • func (re *RollupExpr) AppendString(dst []byte) []byte
  • func (re *RollupExpr) ForSubquery() bool
• type StringExpr
  • func (se *StringExpr) AppendString(dst []byte) []byte

Examples

• Parse

Functions

func CompileRegexp

func CompileRegexp(re string) (*regexp.Regexp, error)

CompileRegexp returns compile regexp re.

func CompileRegexpAnchored

func CompileRegexpAnchored(re string) (*regexp.Regexp, error)

CompileRegexpAnchored returns compiled regexp `^re$`.

func DurationValue

func DurationValue(s string, step int64) (int64, error)

DurationValue returns the duration in milliseconds for the given s and the given step.

The returned duration value can be negative.

func ExpandWithExprs

func ExpandWithExprs(q string) (string, error)

ExpandWithExprs expands WITH expressions inside q and returns the resulting PromQL without WITH expressions.

func IsBinaryOpCmp

func IsBinaryOpCmp(op string) bool

IsBinaryOpCmp returns true if op is comparison operator such as '==', '!=', etc.

func PositiveDurationValue

func PositiveDurationValue(s string, step int64) (int64, error)

PositiveDurationValue returns the duration in milliseconds for the given s and the given step.

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

func Parse(s string) (Expr, error)

Parse parses MetricsQL query s.

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

func (fe *FuncExpr) AppendString(dst []byte) []byte

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.