profileql

Documentation

Overview

Package profileql contains a parser and AST definitions for the Pyroscope profile query language.

A ProfileQL query is a profile-type selector optionally followed by a brace enclosed list of label matchers, mirroring Pyroscope's query syntax (a Prometheus metric selector whose __name__ is the profile type):

process_cpu:cpu:nanoseconds:cpu:nanoseconds{service_name="frontend",env=~"prod|staging"}

Index

• Constants
• func IsValidLabel[S ~string | ~[]byte](s S) error
• type Expr
  • func Parse(input string) (Expr, error)
  • func (e Expr) String() string
• type Label
  • func (l Label) String() string
• type LabelMatcher
  • func (m LabelMatcher) String() string
• type MatchOp
  • func (op MatchOp) IsRegex() bool
  • func (op MatchOp) String() string
• type ParseError
  • func (e *ParseError) Error() string
  • func (e *ParseError) FormatError(p errors.Printer) error
  • func (e *ParseError) Unwrap() error
• type ProfileType
  • func ParseProfileType(id string) (ProfileType, error)
  • func (t ProfileType) ID() string
  • func (t ProfileType) String() string
• type Selector
  • func ParseSelector(input string) (Selector, error)

Constants

const (
	// LabelName is the label holding the profile-type selector, equivalent to
	// Prometheus' __name__ metric name label.
	LabelName = "__name__"
	// LabelServiceName is the conventional service name label.
	LabelServiceName = "service_name"
	// LabelProfileType is the internal label holding the profile type.
	LabelProfileType = "__profile_type__"
)

Functions

func IsValidLabel

func IsValidLabel[S ~string | ~[]byte](s S) error

IsValidLabel validates a label name.

Types

type Expr

type Expr struct {
	// Type is the parsed profile-type selector.
	Type ProfileType
	// Matchers are the label matchers, excluding the profile-type ([LabelName])
	// matcher.
	Matchers []LabelMatcher
}

Expr is a parsed ProfileQL query: a profile-type selector together with a set of label matchers.

The textual form is a profile-type selector optionally followed by a brace enclosed list of label matchers, for example

process_cpu:cpu:nanoseconds:cpu:nanoseconds{service_name="frontend"}

mirroring Pyroscope's query syntax, which is a Prometheus metric selector whose __name__ is the profile type.

func Parse

func Parse(input string) (Expr, error)

Parse parses a ProfileQL query from string.

func (Expr) String

func (e Expr) String() string

String implements fmt.Stringer.

type Label

type Label string

Label is a ProfileQL label name.

func (Label) String

func (l Label) String() string

String implements fmt.Stringer.

type LabelMatcher

type LabelMatcher struct {
	Label Label
	Op    MatchOp        // OpEq, OpNotEq, OpRe, OpNotRe
	Value string         // Equals to value or to the unparsed regexp
	Re    *regexp.Regexp // Equals to nil, if Op is not OpRe or OpNotRe
}

LabelMatcher is a label matching predicate.

func (LabelMatcher) String

func (m LabelMatcher) String() string

String implements fmt.Stringer.

type MatchOp

type MatchOp int

MatchOp defines a label matching operation.

const (
	// OpEq is an equality matcher (=).
	OpEq MatchOp = iota + 1
	// OpNotEq is an inequality matcher (!=).
	OpNotEq
	// OpRe is a regexp matcher (=~).
	OpRe
	// OpNotRe is a negative regexp matcher (!~).
	OpNotRe
)

func (MatchOp) IsRegex

func (op MatchOp) IsRegex() bool

IsRegex returns whether the operation is a regexp matcher.

func (MatchOp) String

func (op MatchOp) String() string

String implements fmt.Stringer.

type ParseError

type ParseError struct {
	Pos scanner.Position
	Err error
}

ParseError is a ProfileQL query parsing error.

func (*ParseError) Error

func (e *ParseError) Error() string

Error implements error.

func (*ParseError) FormatError

func (e *ParseError) FormatError(p errors.Printer) error

FormatError implements errors.Formatter.

func (*ParseError) Unwrap

func (e *ParseError) Unwrap() error

Unwrap implements the errors.Unwrap interface.

type ProfileType

type ProfileType struct {
	// Name is the profile name, e.g. "process_cpu" or "memory".
	Name string
	// SampleType is the sample value type, e.g. "cpu" or "alloc_space".
	SampleType string
	// SampleUnit is the sample value unit, e.g. "nanoseconds" or "bytes".
	SampleUnit string
	// PeriodType is the period type, e.g. "cpu".
	PeriodType string
	// PeriodUnit is the period unit, e.g. "nanoseconds".
	PeriodUnit string
	// Delta denotes that the profile carries delta values.
	Delta bool
}

ProfileType is a parsed profile-type selector.

The textual form is

<name>:<sample_type>:<sample_unit>:<period_type>:<period_unit>[:delta]

for example "process_cpu:cpu:nanoseconds:cpu:nanoseconds".

func ParseProfileType

func ParseProfileType(id string) (ProfileType, error)

ParseProfileType parses a profile-type selector string.

func (ProfileType) ID

func (t ProfileType) ID() string

ID returns the canonical 5-part profile-type identifier, without the delta suffix. This is the value stored in the LabelProfileType label.

func (ProfileType) String

func (t ProfileType) String() string

String implements fmt.Stringer. It reproduces the parsed form, including the delta suffix when set.

type Selector

type Selector struct {
	// Type is the selected profile type, or nil if the selector did not name one.
	Type *ProfileType
	// Matchers are the label matchers, excluding the profile-type selection.
	Matchers []LabelMatcher
}

Selector is the result of parsing a label selector with an optional profile type, as produced by ParseSelector.

func ParseSelector

func ParseSelector(input string) (Selector, error)

ParseSelector parses an optional leading profile-type selector followed by an optional brace-enclosed matcher list, like Parse, but the profile type is optional. It is used where the profile type and label selector are supplied separately (for example by the connect QuerierService), so a bare matcher list such as `{service.name="frontend"}` is valid.