metricsql

package module
v0.27.0 Latest Latest
Warning

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

 Go to latest Published: Oct 11, 2021 License: Apache-2.0 Imports: 12 Imported by: 26

README

GoDoc Go Report

metricsql

Package metricsql implements MetricsQL and PromQL parser in Go.

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.

See docs for more details.

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/MetricsQL 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

Examples

Constants

This section is empty.

Variables

This section is empty.

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.

Duration in s may be combined, i.e. 2h5m, -2h5m or 2h-5m.

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.

Example 
package main

import (
	"fmt"
	"log"

	"github.com/VictoriaMetrics/metricsql"
)

func main() {
	// mql can contain arbitrary MetricsQL extensions - see https://github.com/VictoriaMetrics/VictoriaMetrics/wiki/MetricsQL
	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 

func IsBinaryOpCmp(op string) bool

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

func IsRollupFunc 

func IsRollupFunc(funcName string) bool

IsRollupFunc returns whether funcName is known rollup function.

func IsTransformFunc 

func IsTransformFunc(funcName string) bool

IsTransformFunc returns whether funcName is known transform function.

func PositiveDurationValue 

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

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

Duration in s may be combined, i.e. 2h5m or 2h-5m.

Error is returned if the duration in s is negative.

func VisitAll added in v0.4.0 

func VisitAll(e Expr, f func(expr Expr))

VisitAll recursively calls f for all the Expr children in e.

It visits leaf children at first and then visits parent nodes. It is safe modifying expr in f.

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

	// Optional limit for the number of output time series.
	// This is MetricsQL extension.
	//
	// Example: `sum(...) by (...) limit 10` would return maximum 10 time series.
	Limit int
}

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 DurationExpr added in v0.16.0 

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

DurationExpr contains the duration

func (*DurationExpr) AppendString added in v0.16.0 

func (de *DurationExpr) AppendString(dst []byte) []byte

AppendString appends string representation of de to dst and returns the result.

func (*DurationExpr) Duration added in v0.16.0 

func (de *DurationExpr) Duration(step int64) int64

Duration returns the duration from de in milliseconds.

type Expr 

type Expr interface {
	// AppendString appends string representation of Expr to dst.
	AppendString(dst []byte) []byte
}

Expr holds any of *Expr types.

func Optimize added in v0.7.0 

func Optimize(e Expr) Expr

Optimize optimizes e in order to improve its performance.

It performs the following optimizations:

func Parse 

func Parse(s string) (Expr, error)

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/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.AppendString(nil))

	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 *DurationExpr

	// Offset contains optional value from `offset` part.
	//
	// For example, `foobar{baz="aa"} offset 5m` will have Offset value `5m`.
	Offset *DurationExpr

	// Step contains optional step value from square brackets.
	//
	// For example, `foobar[1h:3m]` will have Step value '3m'.
	Step *DurationExpr

	// 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.

Source Files

View all Source files

Directories

Path Synopsis

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.