selector

README

Time series selector

Selectors allow selecting and filtering of a set of time series.

Simple Selector

In the simplest form you need to specify only a metric name.

Syntax

 <line>                 ::= <metric_name_pattern>
 <metric_name_pattern>  ::= simple pattern

The metric name pattern syntax is simple pattern.

Examples

This example selects all time series that have the go_memstats_alloc_bytes metric name:

go_memstats_alloc_bytes

This example selects all time series with metric names starts with go_memstats_:

go_memstats_*

This example selects all time series with metric names starts with go_ except go_memstats_:

!go_memstats_* go_*

Advanced Selector

It is possible to filter these time series further by appending a comma separated list of label matchers in curly braces ({}).

Syntax

 <line>                 ::= [ <metric_name_pattern> ]{ <list_of_selectors> }
 <metric_name_pattern>  ::= simple pattern
 <list_of_selectors>    ::= a comma separated list <label_name><op><label_value_pattern>
 <label_name>           ::= an exact label name
 <op>                   ::= [ '=', '!=', '=~', '!~', '=*', '!*' ]
 <label_value_pattern>  ::= a label value pattern, depends on <op>

The metric name pattern syntax is simple pattern.

Label matching operators:

• =: Match labels that are exactly equal to the provided string.
• !=: Match labels that are not equal to the provided string.
• =~: Match labels that regex-match the provided string.
• !~: Match labels that do not regex-match the provided string.
• =*: Match labels that simple-pattern-match the provided string.
• !*: Match labels that do not simple-pattern-match the provided string.

Examples

This example selects all time series that:

• have the node_cooling_device_cur_state metric name and
• label type value not equal to Fan:

node_cooling_device_cur_state{type!="Fan"}

This example selects all time series that:

• have the node_filesystem_size_bytes metric name and
• label device value is either /dev/nvme0n1p1 or /dev/nvme0n1p2 and
• label fstype is equal to ext4

node_filesystem_size_bytes{device=~"/dev/nvme0n1p1$|/dev/nvme0n1p2$",fstype="ext4"}

Label matchers can also be applied to metric names by matching against the internal __name__ label.

For example, the expression node_filesystem_size_bytes is equivalent to {__name__="node_filesystem_size_bytes"}. This allows using all operators (other than =*) for metric names matching.

The following expression selects all metrics that have a name starting with node_:

{__name__=*"node_*"}

Documentation

Index

• Constants
• type Expr
  • func (e Expr) Empty() bool
  • func (e Expr) Parse() (Selector, error)
• type Func
  • func (fn Func) Matches(lbs labels.Labels) bool
• type Selector
  • func And(lhs, rhs Selector, others ...Selector) Selector
  • func Not(s Selector) Selector
  • func Or(lhs, rhs Selector, others ...Selector) Selector
  • func Parse(expr string) (Selector, error)
  • func True() Selector

Constants

const (
	OpEqual             = "="
	OpNegEqual          = "!="
	OpRegexp            = "=~"
	OpNegRegexp         = "!~"
	OpSimplePatterns    = "=*"
	OpNegSimplePatterns = "!*"
)

Types

type Expr

type Expr struct {
	Allow []string `yaml:"allow"`
	Deny  []string `yaml:"deny"`
}

func (Expr) Empty

func (e Expr) Empty() bool

func (Expr) Parse

func (e Expr) Parse() (Selector, error)

type Func

type Func func(lbs labels.Labels) bool

func (Func) Matches

func (fn Func) Matches(lbs labels.Labels) bool

type Selector

type Selector interface {
	Matches(lbs labels.Labels) bool
}

func And

func And(lhs, rhs Selector, others ...Selector) Selector

And returns a selector which returns true only if all of it's sub-selectors return true

func Not

func Not(s Selector) Selector

Not returns a selector which returns the negation of the sub-selector's result

func Or

func Or(lhs, rhs Selector, others ...Selector) Selector

Or returns a selector which returns true if any of it's sub-selectors return true

func Parse

func Parse(expr string) (Selector, error)

func True

func True() Selector

True returns a selector which always returns true