logql

package
v0.11.0 Latest Latest
Warning

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

Go to latest
Published: Oct 2, 2026 License: Apache-2.0 Imports: 21 Imported by: 0

Documentation

Overview

Package logql implements the LogQL subset published in docs/logql-subset.md without Loki code.

Index

Constants

View Source
const (
	DefaultMaxLines    = 1000
	DefaultMaxBytes    = 1 << 20
	DefaultQuerySeries = 500
	DefaultMaxSamples  = 50000
)

Default investigation limits, applied when a Limits field is zero.

View Source
const (
	LimitLines   = "max_lines"
	LimitBytes   = "max_bytes"
	LimitSeries  = "max_series"
	LimitSamples = "max_samples"
	LimitTimeout = "timeout"
)

Truncation reasons reported in Result.Limited.

View Source
const (
	// DefaultMaxSeries bounds rule counter cardinality when the budget sets none.
	DefaultMaxSeries = 1000
	// DefaultCounterBytes is the rule counter memory budget when the budget sets none.
	DefaultCounterBytes = 4 << 20
)
View Source
const LogsQLValueField = "value"

LogsQLValueField is the field holding the sample value in translated metric queries.

View Source
const SubsetDoc = "docs/logql-subset.md"

SubsetDoc is the published reference for the supported grammar.

Variables

This section is empty.

Functions

func InjectScope

func InjectScope(query string, m []*labels.Matcher) (string, error)

InjectScope ANDs m into every stream selector of the parsed query and re-serializes it; nothing is replaced.

func ToLogsQL

func ToLogsQL(query string) (string, error)

ToLogsQL translates the subset to LogsQL (metric queries as instant stats queries) or returns a TranslationError.

Types

type AggOp

type AggOp string

AggOp is a vector aggregation operator.

const (
	AggSum   AggOp = "sum"
	AggCount AggOp = "count"
	AggMin   AggOp = "min"
	AggMax   AggOp = "max"
	AggAvg   AggOp = "avg"
	AggTopK  AggOp = "topk"
)

type BinaryExpr

type BinaryExpr struct {
	Op         BinaryOp
	ReturnBool bool
	LHS, RHS   Expr
}

BinaryExpr applies Op between a vector and a scalar or two scalars.

func (*BinaryExpr) String

func (e *BinaryExpr) String() string

type BinaryOp

type BinaryOp string

BinaryOp is an arithmetic or comparison operator.

const (
	OpAdd BinaryOp = "+"
	OpSub BinaryOp = "-"
	OpMul BinaryOp = "*"
	OpDiv BinaryOp = "/"
	OpMod BinaryOp = "%"
	OpPow BinaryOp = "^"
	OpEq  BinaryOp = "=="
	OpNeq BinaryOp = "!="
	OpGt  BinaryOp = ">"
	OpGte BinaryOp = ">="
	OpLt  BinaryOp = "<"
	OpLte BinaryOp = "<="
)

type BudgetError

type BudgetError struct {
	Buckets      int
	MaxSeries    int
	Required     int
	CounterBytes int
}

BudgetError reports a rule whose counters cannot fit its memory budget.

func (*BudgetError) Error

func (e *BudgetError) Error() string

type CompareOp

type CompareOp string

CompareOp is a comparison operator.

const (
	CmpEq  CompareOp = "=="
	CmpNeq CompareOp = "!="
	CmpGt  CompareOp = ">"
	CmpGte CompareOp = ">="
	CmpLt  CompareOp = "<"
	CmpLte CompareOp = "<="
)

type Direction

type Direction int

Direction orders log query results.

const (
	// Backward returns the newest lines first.
	Backward Direction = iota
	// Forward returns the oldest lines first.
	Forward
)

type Expr

type Expr interface {
	String() string
	// contains filtered or unexported methods
}

Expr is a parsed LogQL expression. String returns the canonical form, which re-parses to an identical AST.

func ParseExpr

func ParseExpr(s string) (Expr, error)

ParseExpr parses a LogQL query in the supported subset.

type Grouping

type Grouping struct {
	Without bool
	Labels  []string
}

Grouping is a by or without clause; Labels is nil when empty.

func (*Grouping) String

func (g *Grouping) String() string

type JSONParam

type JSONParam struct {
	Label string
	Path  string
}

JSONParam extracts the value at Path into label Label.

type JSONStage

type JSONStage struct {
	Params []JSONParam
}

JSONStage is the json parser, extracting all fields or only Params.

func (*JSONStage) String

func (s *JSONStage) String() string

type LabelFilter

type LabelFilter interface {
	String() string
	// contains filtered or unexported methods
}

LabelFilter is a label filter expression.

type LabelFilterBinary

type LabelFilterBinary struct {
	Or          bool
	Left, Right LabelFilter
}

LabelFilterBinary combines two label filters with and (Or false) or or (Or true).

func (*LabelFilterBinary) String

func (f *LabelFilterBinary) String() string

type LabelFilterNumeric

type LabelFilterNumeric struct {
	Name  string
	Op    CompareOp
	Kind  NumericKind
	Value float64
}

LabelFilterNumeric compares a label parsed as Kind with Value (nanoseconds for durations, bytes for sizes).

func (*LabelFilterNumeric) String

func (f *LabelFilterNumeric) String() string

type LabelFilterStage

type LabelFilterStage struct {
	Filter LabelFilter
}

LabelFilterStage filters lines by labels.

func (*LabelFilterStage) String

func (s *LabelFilterStage) String() string

type LabelFilterString

type LabelFilterString struct {
	Matcher *labels.Matcher
}

LabelFilterString compares a label with a string matcher.

func (*LabelFilterString) String

func (f *LabelFilterString) String() string

type Limits

type Limits struct {
	Start, End time.Time
	// Step selects a range metric query; zero evaluates a metric query at End only.
	Step       time.Duration
	Direction  Direction
	MaxLines   int
	MaxBytes   int
	MaxSeries  int
	MaxSamples int
	Timeout    time.Duration
}

Limits bounds an investigation query (PRD I3). Start and End are required.

type Line

type Line struct {
	Labels map[string]string
	Time   time.Time
	Text   string
}

Line is one log line with its stream labels.

type LineFilter

type LineFilter struct {
	Op    LineFilterOp
	Match string
}

LineFilter keeps lines containing (or matching) Match.

func (*LineFilter) String

func (f *LineFilter) String() string

type LineFilterOp

type LineFilterOp string

LineFilterOp is a line filter operator.

const (
	LineContains    LineFilterOp = "|="
	LineNotContains LineFilterOp = "!="
	LineMatchRegexp LineFilterOp = "|~"
	LineNotRegexp   LineFilterOp = "!~"
)

type LineSource

type LineSource interface {
	Scan(ctx context.Context, req SourceRequest, yield func(Line) bool) error
}

LineSource streams candidate lines in any order; yield returning false stops the scan.

type LineSourceFunc

type LineSourceFunc func(ctx context.Context, req SourceRequest, yield func(Line) bool) error

LineSourceFunc adapts a function to LineSource.

func (LineSourceFunc) Scan

func (f LineSourceFunc) Scan(ctx context.Context, req SourceRequest, yield func(Line) bool) error

Scan calls f.

type Lines

type Lines []Line

Lines is an in-memory LineSource yielding lines in slice order.

func (Lines) Scan

func (ls Lines) Scan(ctx context.Context, req SourceRequest, yield func(Line) bool) error

Scan yields the lines of selected streams within the request range.

type LogExpr

type LogExpr struct {
	Matchers []*labels.Matcher
	Stages   []Stage
}

LogExpr is a stream selector followed by a pipeline.

func (*LogExpr) String

func (e *LogExpr) String() string

type LogfmtStage

type LogfmtStage struct{}

LogfmtStage is the logfmt parser.

func (*LogfmtStage) String

func (*LogfmtStage) String() string

type NumberLiteral

type NumberLiteral struct {
	Value float64
}

NumberLiteral is a scalar literal.

func (*NumberLiteral) String

func (e *NumberLiteral) String() string

type NumericKind

type NumericKind string

NumericKind selects how a numeric label filter parses label values.

const (
	NumericNumber   NumericKind = "number"
	NumericDuration NumericKind = "duration"
	NumericBytes    NumericKind = "bytes"
)

type ParseError

type ParseError struct {
	Pos int
	Msg string
}

ParseError reports malformed input at a byte offset.

func (*ParseError) Error

func (e *ParseError) Error() string

type PatternStage

type PatternStage struct {
	Pattern string
}

PatternStage is the pattern parser.

func (*PatternStage) String

func (s *PatternStage) String() string

type PipelineError

type PipelineError struct {
	Err string
}

PipelineError reports samples carrying __error__ in a metric evaluation, as Loki does.

func (*PipelineError) Error

func (e *PipelineError) Error() string

type Program

type Program struct {
	// contains filtered or unexported fields
}

Program is a compiled LogQL rule evaluated over per-series time-bucketed counters; lines are never retained.

func CompileRule

func CompileRule(expr string, b bundle.Budget) (*Program, error)

CompileRule validates a metric query against the subset and its counter budget.

func (*Program) Eval

func (p *Program) Eval(ts time.Time) (promql.Vector, error)

Eval computes the rule expression over the counters in the window ending at ts.

func (*Program) Expr

func (p *Program) Expr() Expr

Expr returns the parsed rule expression.

func (*Program) Matches

func (p *Program) Matches(streamLabels map[string]string) bool

Matches reports whether a stream is selected by the rule, for the tailer's stream filter.

func (*Program) MemoryBytes

func (p *Program) MemoryBytes() int

MemoryBytes is the counter memory reserved for the rule at its cardinality bound.

func (*Program) Observe

func (p *Program) Observe(streamLabels map[string]string, ts time.Time, line string) (matched bool)

Observe applies the pipeline to one line and counts it; the line is never retained.

func (*Program) Status

func (p *Program) Status() Status

Status reports live counter usage and cardinality drops.

func (*Program) Window

func (p *Program) Window() time.Duration

Window is the counter window, the rule's range.

type RangeAggregation

type RangeAggregation struct {
	Op    RangeOp
	Log   *LogExpr
	Range time.Duration
}

RangeAggregation aggregates a log query over a range window.

func (*RangeAggregation) String

func (e *RangeAggregation) String() string

type RangeOp

type RangeOp string

RangeOp is a log range aggregation.

const (
	RangeCount RangeOp = "count_over_time"
	RangeRate  RangeOp = "rate"
	RangeBytes RangeOp = "bytes_over_time"
)

type RegexpStage

type RegexpStage struct {
	Pattern string
}

RegexpStage is the regexp parser.

func (*RegexpStage) String

func (s *RegexpStage) String() string

type Result

type Result struct {
	Type         ResultType
	Lines        []ResultLine
	Vector       promql.Vector
	Matrix       promql.Matrix
	Start, End   time.Time
	Step         time.Duration
	Truncated    bool
	Limited      []string
	ScannedLines int64
	ScannedBytes int64
	ResultBytes  int
}

Result is a bounded investigation result; Truncated is set with the limits that cut it.

func RunQuery

func RunQuery(ctx context.Context, query string, src LineSource, lim Limits) (*Result, error)

RunQuery evaluates a query over src within lim, retaining nothing; a timeout returns a partial result marked LimitTimeout.

type ResultLine

type ResultLine struct {
	Time   time.Time
	Labels labels.Labels
	Text   string
}

ResultLine is one matching line with its stream and extracted labels.

type ResultType

type ResultType string

ResultType is the shape of a query result.

const (
	ResultStreams ResultType = "streams"
	ResultVector  ResultType = "vector"
	ResultMatrix  ResultType = "matrix"
)

type SourceRequest

type SourceRequest struct {
	Matchers   []*labels.Matcher
	Start, End time.Time
}

SourceRequest names the streams and the inclusive time range a query can use.

func (SourceRequest) Match

func (r SourceRequest) Match(streamLabels map[string]string) bool

Match reports whether a stream is selected by the request matchers.

type Stage

type Stage interface {
	String() string
	// contains filtered or unexported methods
}

Stage is one pipeline stage.

type Status

type Status struct {
	Series    int
	MaxSeries int
	// LiveBytes is the counter bucket memory in use; LabelBytes is the size of the series keys.
	LiveBytes  int
	LabelBytes int
	// DroppedLines counts matched lines not counted because their series exceeded MaxSeries.
	DroppedLines uint64
	// LateLines counts matched lines older than the counter window.
	LateLines uint64
	LastDrop  time.Time
	// BudgetLimited is true while a cardinality drop lies within the current window.
	BudgetLimited bool
}

Status reports counter usage and budget-limited drops (PRD R9).

type TranslationError

type TranslationError struct {
	Construct string
	Reason    string
}

TranslationError reports a LogQL construct without an exact LogsQL mapping.

func (*TranslationError) Error

func (e *TranslationError) Error() string

type UnsupportedError

type UnsupportedError struct {
	Pos       int
	Construct string
}

UnsupportedError reports a valid LogQL construct outside the published subset.

func (*UnsupportedError) Error

func (e *UnsupportedError) Error() string

type VectorAggregation

type VectorAggregation struct {
	Op       AggOp
	Param    int
	Grouping *Grouping
	Expr     Expr
}

VectorAggregation aggregates a vector; Param is k for topk.

func (*VectorAggregation) String

func (e *VectorAggregation) String() string

Jump to

Keyboard shortcuts

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