Help us shape the future of Go! Take the 2026 Go Developer Survey

promql

package
v1.8.1 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