promql

package
v1.8.3 Latest Latest
Warning

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

Go to latest
Published: Oct 20, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package promql implements a PromQL subset: selectors, range functions, aggregations and binary operators.

Index

Constants

View Source
const DefaultLookback = 5 * time.Minute

DefaultLookback is how far back an instant selector looks for a sample.

View Source
const MaxRangeSteps = 11000

MaxRangeSteps bounds a range query's resolution like Prometheus.

View Source
const NameLabel = "__name__"

NameLabel is the label that carries the metric name.

Variables

View Source
var ErrEval = errors.New("execution error")

ErrEval marks an evaluation failure.

View Source
var ErrSyntax = errors.New("parse error")

ErrSyntax marks a parse failure.

Functions

func Fingerprint

func Fingerprint(l Labels) string

Fingerprint is a canonical string for a label set.

func MatchesAll

func MatchesAll(lbls Labels, ms []*Matcher) bool

MatchesAll reports whether lbls satisfies every matcher.

func ParseDuration

func ParseDuration(s string) (time.Duration, error)

ParseDuration parses a PromQL duration such as 5m or 1h30m.

func ResultType

func ResultType(v Value) string

ResultType names a value's Prometheus resultType.

Types

type Aggregation

type Aggregation struct {
	Expr     Expr
	Param    Expr
	Op       string
	Grouping []string
	Without  bool
}

Aggregation reduces a vector across series.

type Binary

type Binary struct {
	L, R        Expr
	Op          string
	MatchLabels []string
	On          bool
	ReturnBool  bool
}

Binary combines two operands.

type Call

type Call struct {
	Func string
	Args []Expr
}

Call is a function application.

type Engine

type Engine struct {
	Store    Storage
	Lookback time.Duration
}

Engine evaluates expressions against a Storage.

func (*Engine) Instant

func (e *Engine) Instant(src string, ts time.Time) (Value, error)

Instant evaluates src at ts.

func (*Engine) Range

func (e *Engine) Range(src string, start, end time.Time, step time.Duration) (Matrix, error)

Range evaluates src at every step in [start, end].

type Expr

type Expr interface {
	// contains filtered or unexported methods
}

Expr is a parsed PromQL expression.

func Parse

func Parse(src string) (Expr, error)

Parse parses a PromQL expression.

type Labels

type Labels map[string]string

Labels is a label set.

type MatchType

type MatchType int

MatchType selects how a Matcher compares a label value.

const (
	MatchEqual MatchType = iota
	MatchNotEqual
	MatchRegexp
	MatchNotRegexp
)

Matcher comparison kinds.

type Matcher

type Matcher struct {
	Name  string
	Value string
	Type  MatchType
	// contains filtered or unexported fields
}

Matcher filters series by one label.

func NewMatcher

func NewMatcher(t MatchType, name, value string) (*Matcher, error)

NewMatcher builds a matcher; regular expressions are fully anchored like Prometheus.

func (*Matcher) Matches

func (m *Matcher) Matches(v string) bool

Matches reports whether v satisfies the matcher; an absent label is the empty string.

type Matrix

type Matrix []Series

Matrix is a set of series with ranges of samples.

type MatrixSelector

type MatrixSelector struct {
	VS    *VectorSelector
	Range time.Duration
}

MatrixSelector selects a window of samples per series.

type NumberLit

type NumberLit struct{ V float64 }

NumberLit is a scalar literal.

type Sample

type Sample struct {
	T int64   `json:"t"`
	V float64 `json:"v"`
}

Sample is one timestamped value; T is Unix milliseconds.

type Scalar

type Scalar struct {
	T int64
	V float64
}

Scalar is a single number.

type Series

type Series struct {
	Labels  Labels
	Samples []Sample
}

Series is a labelled run of samples ordered by time.

type Storage

type Storage interface {
	// Select returns series matching ms with at least the samples in [minT, maxT] (Unix ms).
	Select(ms []*Matcher, minT, maxT int64) []Series
}

Storage supplies series to the engine.

type StringLit

type StringLit struct{ V string }

StringLit is a string literal.

type StringValue

type StringValue struct {
	V string
	T int64
}

StringValue is a string result.

type Unary

type Unary struct{ X Expr }

Unary negates its operand.

type Value

type Value interface {
	// contains filtered or unexported methods
}

Value is the result of evaluating an expression.

type Vector

type Vector []VectorSample

Vector is a set of instant samples.

type VectorSample

type VectorSample struct {
	Metric Labels
	T      int64
	V      float64
}

VectorSample is one instant sample of a labelled series.

type VectorSelector

type VectorSelector struct {
	Name     string
	Matchers []*Matcher
	Offset   time.Duration
}

VectorSelector selects the latest sample per series.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL