traceql

package
v0.49.0 Latest Latest
Warning

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

 Go to latest Published: Jul 31, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package traceql contains TraceQL parser and AST definitions.

Index

Constants

View Source 
const (
	// DefaultCompareTopN is a default [CompareOperation.TopN].
	DefaultCompareTopN = 10
	// MaxCompareTopN is a maximum [CompareOperation.TopN].
	MaxCompareTopN = 1000
)

Variables

This section is empty.

Functions

func ExtractMatchers 

func ExtractMatchers(expr Expr) (SpansetOp, []SpanMatcher)

ExtractMatchers returns SpanMatcher list extracted from Expr.

func IntrinsicNames 

func IntrinsicNames() (r []string)

IntrinsicNames returns a slice of intrinsics.

Types

type AggregateOp 

type AggregateOp int

AggregateOp defines aggregation operator. 

const (
	AggregateOpCount AggregateOp = iota + 1
	AggregateOpMax
	AggregateOpMin
	AggregateOpAvg
	AggregateOpSum
)

func (AggregateOp) String 

func (op AggregateOp) String() string

String implements fmt.Stringer.

type AggregateScalarExpr 

type AggregateScalarExpr struct {
	Op    AggregateOp
	Field FieldExpr // nilable
}

AggregateScalarExpr is an aggregate function.

func (*AggregateScalarExpr) ValueType 

func (s *AggregateScalarExpr) ValueType() StaticType

ValueType returns value type of expression.

type Attribute 

type Attribute struct {
	Name   string
	Scope  AttributeScope
	Prop   SpanProperty
	Parent bool // refers to parent
}

Attribute is a span attribute.

func ParseAttribute 

func ParseAttribute(attr string) (a Attribute, _ error)

ParseAttribute parses attribute from given string.

func (Attribute) String 

func (s Attribute) String() string

String implements fmt.Stringer.

func (*Attribute) ValueType 

func (s *Attribute) ValueType() StaticType

ValueType returns value type of expression.

type AttributeScope 

type AttributeScope uint8

AttributeScope is an attribute scope. 

const (
	ScopeNone AttributeScope = iota
	ScopeResource
	ScopeSpan
	ScopeInstrumentation
	ScopeEvent
	ScopeLink
)

func (AttributeScope) String 

func (s AttributeScope) String() string

String implements fmt.Stringer.

type Autocomplete 

type Autocomplete struct {
	Matchers []SpanMatcher
}

Autocomplete is a AND set of spanset matchers.

func ParseAutocomplete 

func ParseAutocomplete(input string) Autocomplete

ParseAutocomplete parses matchers from potentially uncomplete TraceQL spanset filter from string.

func (Autocomplete) String 

func (c Autocomplete) String() string

String implements fmt.Stringer for Autocomplete.

type BinaryExpr 

type BinaryExpr struct {
	Left  Expr
	Op    SpansetOp
	Right Expr
}

BinaryExpr is a binary expression.

type BinaryFieldExpr 

type BinaryFieldExpr struct {
	Left  FieldExpr
	Op    BinaryOp
	Right FieldExpr
}

BinaryFieldExpr is a binary operation between two field expressions.

func (*BinaryFieldExpr) ValueType 

func (s *BinaryFieldExpr) ValueType() StaticType

ValueType returns value type of expression.

type BinaryOp 

type BinaryOp int

BinaryOp defines binary operator. 

const (
	// Logical ops.
	OpAnd BinaryOp = iota + 1
	OpOr
	// Math ops.
	OpAdd
	OpSub
	OpMul
	OpDiv
	OpMod
	OpPow
	// Comparison ops.
	OpEq
	OpNotEq
	OpRe
	OpNotRe
	OpGt
	OpGte
	OpLt
	OpLte
)

func (BinaryOp) CheckType 

func (op BinaryOp) CheckType(t StaticType) bool

CheckType checks if operator can be applied to given type.

func (BinaryOp) IsArithmetic 

func (op BinaryOp) IsArithmetic() bool

IsArithmetic whether op is arithmetic operator.

func (BinaryOp) IsBoolean 

func (op BinaryOp) IsBoolean() bool

IsBoolean whether op have boolean result.

func (BinaryOp) IsEqual 

func (op BinaryOp) IsEqual() bool

IsEqual whether op is equal operator.

func (BinaryOp) IsLogic 

func (op BinaryOp) IsLogic() bool

IsLogic whether op is logic operator.

func (BinaryOp) IsOrdering 

func (op BinaryOp) IsOrdering() bool

IsOrdering whether op is ordering operator.

func (BinaryOp) IsRegex 

func (op BinaryOp) IsRegex() bool

IsRegex whether op is regexp operator.

func (BinaryOp) Precedence 

func (op BinaryOp) Precedence() int

Precedence returns operator precedence.

func (BinaryOp) String 

func (op BinaryOp) String() string

String implements fmt.Stringer.

type BinaryScalarExpr 

type BinaryScalarExpr struct {
	Left  ScalarExpr
	Op    BinaryOp
	Right ScalarExpr
}

BinaryScalarExpr is a binary operation between two scalar expressions.

func (*BinaryScalarExpr) ValueType 

func (s *BinaryScalarExpr) ValueType() StaticType

ValueType returns value type of expression.

type BinarySpansetExpr 

type BinarySpansetExpr struct {
	Left  SpansetExpr
	Op    SpansetOp
	Right SpansetExpr
}

BinarySpansetExpr is a binary operation between two spanset expressions.

type CoalesceOperation 

type CoalesceOperation struct{}

CoalesceOperation is a `colaesce()` operation.

type CompareOperation added in v0.49.0 

type CompareOperation struct {
	// Spanset is a pipeline producing spans to compare.
	Spanset Expr
	// Filter selects spans of the selection group.
	Filter *SpansetFilter
	// TopN limits values returned per attribute.
	TopN int
	// Start and End constrain the selection window, in Unix nanoseconds.
	//
	// Both are zero if unset.
	Start, End int64
}

CompareOperation is a `compare()` metrics aggregation.

It splits spans into a selection matching Filter and a baseline of the rest, returning a series per attribute value found on them.

type Expr 

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

Expr is a TraceQL expression.

func Parse 

func Parse(input string) (Expr, error)

Parse parses TraceQL query from string.

type FieldExpr 

type FieldExpr interface {
	TypedExpr
	// contains filtered or unexported methods
}

FieldExpr is a field expression.

type GroupOperation 

type GroupOperation struct {
	By FieldExpr
}

GroupOperation is a `by()` operation.

type MetricsAggregation added in v0.49.0 

type MetricsAggregation struct {
	Op MetricsOp
	// Spanset is a pipeline producing spans to aggregate.
	Spanset Expr
	// Field is an attribute to aggregate, set if [MetricsOp.TakesField].
	Field *Attribute
	// Parameters are quantiles of [MetricsOpQuantileOverTime].
	Parameters []float64
	// By is a set of attributes to group series by, may be empty.
	By []Attribute
}

MetricsAggregation aggregates a spanset pipeline into a time series.

type MetricsBinaryExpr added in v0.49.0 

type MetricsBinaryExpr struct {
	Left  MetricsExpr
	Op    BinaryOp
	Right MetricsExpr
}

MetricsBinaryExpr is an arithmetic operation between two metrics expressions.

Op is always arithmetic and never OpMod or OpPow.

type MetricsExpr added in v0.49.0 

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

MetricsExpr is a TraceQL metrics query expression.

See https://grafana.com/docs/tempo/latest/traceql/metrics-queries/.

type MetricsFilter added in v0.49.0 

type MetricsFilter struct {
	Op    BinaryOp
	Value *Static
}

MetricsFilter drops series points not matching the comparison.

type MetricsOp added in v0.49.0 

type MetricsOp int

MetricsOp defines a metrics aggregation operator. 

const (
	MetricsOpRate MetricsOp = iota + 1
	MetricsOpCountOverTime
	MetricsOpMinOverTime
	MetricsOpMaxOverTime
	MetricsOpSumOverTime
	MetricsOpAvgOverTime
	MetricsOpQuantileOverTime
	MetricsOpHistogramOverTime
)

func (MetricsOp) String added in v0.49.0 

func (op MetricsOp) String() string

String implements fmt.Stringer.

func (MetricsOp) TakesField added in v0.49.0 

func (op MetricsOp) TakesField() bool

TakesField whether op aggregates over a span attribute.

type MetricsPipeline added in v0.49.0 

type MetricsPipeline struct {
	Expr   MetricsExpr
	Stages []MetricsStage
}

MetricsPipeline applies second stage operations to a metrics expression.

type MetricsScalarOp added in v0.49.0 

type MetricsScalarOp struct {
	Op    BinaryOp
	Value float64
	// ScalarLeft whether the constant is the left operand, as in `2 / ({} | rate())`.
	ScalarLeft bool
}

MetricsScalarOp applies constant arithmetic to every series point.

A duration cannot be used as a scalar operand, so a float carries the value without loss.

type MetricsStage added in v0.49.0 

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

MetricsStage is a metrics query second stage operation.

See https://grafana.com/docs/tempo/latest/traceql/metrics-queries/#multi-stage-metrics-queries.

type MetricsStageOp added in v0.49.0 

type MetricsStageOp int

MetricsStageOp defines a metrics second stage operator. 

const (
	MetricsStageOpTopK MetricsStageOp = iota + 1
	MetricsStageOpBottomK
)

func (MetricsStageOp) String added in v0.49.0 

func (op MetricsStageOp) String() string

String implements fmt.Stringer.

type PipelineStage 

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

PipelineStage is a pipeline stage.

type ScalarExpr 

type ScalarExpr interface {
	TypedExpr
	// contains filtered or unexported methods
}

ScalarExpr is a scalar expression.

type ScalarFilter 

type ScalarFilter struct {
	Left  ScalarExpr
	Op    BinaryOp
	Right ScalarExpr
}

ScalarFilter is a scalar filter.

type SelectOperation 

type SelectOperation struct {
	Args []FieldExpr
}

SelectOperation is a `select()` operation.

type SpanMatcher 

type SpanMatcher struct {
	Attribute Attribute
	Op        BinaryOp // could be zero, look for spans with such attribute
	Static    Static
}

SpanMatcher defines span predicate to select.

func (SpanMatcher) String 

func (m SpanMatcher) String() string

String implements fmt.Stringer.

type SpanProperty 

type SpanProperty uint8

SpanProperty is a span property. 

const (
	SpanAttribute SpanProperty = iota
	SpanDuration
	SpanChildCount
	SpanName
	SpanStatus
	SpanKind
	SpanParent
	RootSpanName
	RootServiceName
	TraceDuration
	// Scoped intrinsics added with TraceQL v2.
	SpanStatusMessage
	NestedSetLeft
	NestedSetRight
	NestedSetParent
	SpanID
	ParentID
	TraceID
	EventName
	EventTimeSinceStart
	LinkTraceID
	LinkSpanID
	InstrumentationName
	InstrumentationVersion
)

type SpansetExpr 

type SpansetExpr interface {
	PipelineStage
	// contains filtered or unexported methods
}

SpansetExpr is a spanset expression.

type SpansetFilter 

type SpansetFilter struct {
	Expr FieldExpr // if filter is empty, expr is True
}

SpansetFilter is a spanset filter.

type SpansetOp 

type SpansetOp int

SpansetOp defines spanset operator. 

const (
	SpansetOpAnd SpansetOp = iota + 1
	SpansetOpChild
	SpansetOpDescendant
	SpansetOpUnion
	SpansetOpSibling
	SpansetOpParent
	SpansetOpAncestor
	SpansetOpNotChild
	SpansetOpNotParent
	SpansetOpNotDescendant
	SpansetOpNotAncestor
	SpansetOpNotSibling
	SpansetOpUnionChild
	SpansetOpUnionParent
	SpansetOpUnionDescendant
	SpansetOpUnionAncestor
	SpansetOpUnionSibling
)

func (SpansetOp) IsStructural added in v0.49.0 

func (op SpansetOp) IsStructural() bool

IsStructural whether op relates two spansets by their position in the trace tree, rather than by set membership.

func (SpansetOp) Precedence 

func (op SpansetOp) Precedence() int

Precedence returns operator precedence.

func (SpansetOp) String 

func (op SpansetOp) String() string

String implements fmt.Stringer.

type SpansetPipeline 

type SpansetPipeline struct {
	Pipeline []PipelineStage
}

SpansetPipeline is a spanset pipeline.

type Static 

type Static struct {
	Type StaticType
	Data uint64 // stores everything, except strings
	Str  string
}

Static is a constant value.

func (*Static) AsBool 

func (s *Static) AsBool() bool

AsBool returns Bool value.

func (*Static) AsDuration 

func (s *Static) AsDuration() time.Duration

AsDuration returns Duration value.

func (*Static) AsInt 

func (s *Static) AsInt() int64

AsInt returns Int value.

func (*Static) AsNumber 

func (s *Static) AsNumber() float64

AsNumber returns Number value.

func (*Static) AsSpanKind 

func (s *Static) AsSpanKind() ptrace.SpanKind

AsSpanKind returns SpanKind value.

func (*Static) AsSpanStatus 

func (s *Static) AsSpanStatus() ptrace.StatusCode

AsSpanStatus returns SpanStatus value.

func (*Static) AsString 

func (s *Static) AsString() string

AsString returns String value.

func (*Static) Compare 

func (s *Static) Compare(to Static) int

Compare compares two Static values.

func (*Static) IsNil 

func (s *Static) IsNil() bool

IsNil returns true, if static is Nil.

func (*Static) SetBool 

func (s *Static) SetBool(v bool)

SetBool sets Bool value.

func (*Static) SetDuration 

func (s *Static) SetDuration(v time.Duration)

SetDuration sets Duration value.

func (*Static) SetInt 

func (s *Static) SetInt(v int64)

SetInt sets Int value.

func (*Static) SetNil 

func (s *Static) SetNil()

SetNil sets Nil value.

func (*Static) SetNumber 

func (s *Static) SetNumber(v float64)

SetNumber sets Number value.

func (*Static) SetOTELValue 

func (s *Static) SetOTELValue(val pcommon.Value) bool

SetOTELValue sets value from given OpenTelemetry data value.

SetOTELValue returns false, if pcommon.Value cannot be represent as Static.

func (*Static) SetSpanKind 

func (s *Static) SetSpanKind(kind ptrace.SpanKind)

SetSpanKind sets SpanKind value.

func (*Static) SetSpanStatus 

func (s *Static) SetSpanStatus(status ptrace.StatusCode)

SetSpanStatus sets SpanStatus value.

func (*Static) SetString 

func (s *Static) SetString(v string)

SetString sets String value.

func (*Static) ToFloat 

func (s *Static) ToFloat() float64

ToFloat converts numeric Static to a float value.

func (*Static) ValueType 

func (s *Static) ValueType() StaticType

ValueType returns value type of expression.

type StaticType 

type StaticType int

StaticType defines static type. 

const (
	TypeAttribute StaticType = iota
	TypeString
	TypeInt
	TypeNumber
	TypeBool
	TypeNil
	TypeDuration
	TypeSpanStatus
	TypeSpanKind
)

func StaticTypeFromValueType 

func StaticTypeFromValueType(typ pcommon.ValueType) StaticType

StaticTypeFromValueType converts pcommon.ValueType to StaticType.

func (StaticType) CheckOperand 

func (s StaticType) CheckOperand(s2 StaticType) bool

CheckOperand whether is a and b are valid operands.

func (StaticType) IsNumeric 

func (s StaticType) IsNumeric() bool

IsNumeric returns true if type is numeric.

func (StaticType) String 

func (s StaticType) String() string

String implements fmt.Stringer.

type SyntaxError 

type SyntaxError struct {
	Msg string
	Pos scanner.Position
}

SyntaxError is a syntax error.

func (*SyntaxError) Error 

func (e *SyntaxError) Error() string

Error implements error.

type TopKOperation added in v0.49.0 

type TopKOperation struct {
	Op    MetricsStageOp
	Limit int
}

TopKOperation is a `topk()`/`bottomk()` operation, keeping only Limit series with the highest (or lowest) values.

type TypeError 

type TypeError struct {
	Msg string
	Pos scanner.Position
}

TypeError is a type checking error.

func (*TypeError) Error 

func (e *TypeError) Error() string

Error implements error.

type TypedExpr 

type TypedExpr interface {
	ValueType() StaticType
}

TypedExpr is an interface for typed expression.

type UnaryFieldExpr 

type UnaryFieldExpr struct {
	Expr FieldExpr
	Op   UnaryOp
}

UnaryFieldExpr is a unary field expression operation.

func (*UnaryFieldExpr) ValueType 

func (s *UnaryFieldExpr) ValueType() StaticType

ValueType returns value type of expression.

type UnaryOp 

type UnaryOp int

UnaryOp defines unary operator. 

const (
	OpNot UnaryOp = iota + 1
	OpNeg
)

func (UnaryOp) CheckType 

func (op UnaryOp) CheckType(t StaticType) bool

CheckType checks if operator can be applied to given type.

func (UnaryOp) String 

func (op UnaryOp) String() string

String implements fmt.Stringer.

Source Files

View all Source files

Directories

Path Synopsis
Package lexer contains TraceQL lexer.
 Package lexer contains TraceQL lexer.
Package traceqlengine implements TraceQL evaluation engine.
 Package traceqlengine implements TraceQL evaluation engine.

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.