Skip to main content

logql/
metric.rs

1//! # LogQL Metric Query AST
2//!
3//! Metric queries turn log streams into numeric time series. They wrap a
4//! [`LogQuery`](crate::ast::LogQuery) in a range aggregation (`rate`,
5//! `count_over_time`, ...), optionally nest it in a vector aggregation
6//! (`sum by (...)`, `topk`, ...), and combine results with binary
7//! operators.
8
9use crate::ast::{Grouping, LogQuery, Unwrap};
10use std::time::Duration;
11
12/// A parsed LogQL metric query.
13#[derive(Debug, Clone, PartialEq)]
14#[non_exhaustive]
15pub enum MetricQuery {
16    /// A range aggregation over a log selector, e.g. `rate({a="b"}[5m])`.
17    Range(Box<RangeAggregation>),
18    /// A vector aggregation over an inner metric query, e.g.
19    /// `sum by (level) (rate(...))`.
20    Vector(Box<VectorAggregation>),
21    /// A binary operation between two metric queries or scalars.
22    Binary(Box<BinaryExpr>),
23    /// A scalar literal (e.g. the `2` in `rate(...) * 2`).
24    Literal(f64),
25    /// `vector(<scalar>)` — a scalar promoted to an instant vector, used
26    /// for fallbacks like `... or vector(0)`.
27    VectorLiteral(f64),
28    /// `label_replace(v, dst, replacement, src, regex)` — rewrite a label
29    /// from a regex capture of another label.
30    LabelReplace(Box<LabelReplace>),
31}
32
33/// A `label_replace(v, dst, replacement, src, regex)` call.
34#[derive(Debug, Clone, PartialEq)]
35pub struct LabelReplace {
36    /// The inner metric query whose labels are rewritten.
37    pub inner: MetricQuery,
38    /// Destination label name.
39    pub dst_label: String,
40    /// Replacement template referencing regex capture groups (`$1`).
41    pub replacement: String,
42    /// Source label the regex is matched against.
43    pub src_label: String,
44    /// Regex applied to the source label's value.
45    pub regex: String,
46}
47
48/// A range aggregation: a range function applied to a ranged log query.
49#[derive(Debug, Clone, PartialEq)]
50pub struct RangeAggregation {
51    pub function: RangeFunction,
52    /// The log selector and pipeline being aggregated.
53    pub log_query: LogQuery,
54    /// The range window, e.g. `5m` in `[5m]`.
55    pub range: Duration,
56    /// Optional `offset <duration>` time shift.
57    pub offset: Option<Duration>,
58    /// Optional `| unwrap <label>` for value extraction (required by the
59    /// `*_over_time` functions that operate on extracted samples).
60    pub unwrap: Option<Unwrap>,
61    /// Scalar parameter for `quantile_over_time(<q>, ...)`.
62    pub param: Option<f64>,
63    /// Optional `by`/`without` grouping on unwrapped range aggregations.
64    pub grouping: Option<Grouping>,
65}
66
67/// Range aggregation functions.
68#[derive(Debug, Clone, Copy, PartialEq, Eq)]
69#[non_exhaustive]
70pub enum RangeFunction {
71    Rate,
72    RateCounter,
73    CountOverTime,
74    BytesRate,
75    BytesOverTime,
76    AvgOverTime,
77    SumOverTime,
78    MinOverTime,
79    MaxOverTime,
80    StdvarOverTime,
81    StddevOverTime,
82    QuantileOverTime,
83    FirstOverTime,
84    LastOverTime,
85    AbsentOverTime,
86}
87
88impl RangeFunction {
89    /// Resolve a function name to its variant.
90    pub fn from_name(name: &str) -> Option<Self> {
91        Some(match name {
92            "rate" => RangeFunction::Rate,
93            "rate_counter" => RangeFunction::RateCounter,
94            "count_over_time" => RangeFunction::CountOverTime,
95            "bytes_rate" => RangeFunction::BytesRate,
96            "bytes_over_time" => RangeFunction::BytesOverTime,
97            "avg_over_time" => RangeFunction::AvgOverTime,
98            "sum_over_time" => RangeFunction::SumOverTime,
99            "min_over_time" => RangeFunction::MinOverTime,
100            "max_over_time" => RangeFunction::MaxOverTime,
101            "stdvar_over_time" => RangeFunction::StdvarOverTime,
102            "stddev_over_time" => RangeFunction::StddevOverTime,
103            "quantile_over_time" => RangeFunction::QuantileOverTime,
104            "first_over_time" => RangeFunction::FirstOverTime,
105            "last_over_time" => RangeFunction::LastOverTime,
106            "absent_over_time" => RangeFunction::AbsentOverTime,
107            _ => return None,
108        })
109    }
110
111    /// Whether this function requires a leading scalar parameter, as in
112    /// `quantile_over_time(0.99, ...)`.
113    pub fn takes_param(self) -> bool {
114        matches!(self, RangeFunction::QuantileOverTime)
115    }
116}
117
118/// A vector aggregation over an inner metric query.
119#[derive(Debug, Clone, PartialEq)]
120pub struct VectorAggregation {
121    pub function: AggregationFunction,
122    /// Scalar parameter for `topk`/`bottomk` (the `k`).
123    pub param: Option<f64>,
124    /// Optional `by`/`without` grouping.
125    pub grouping: Option<Grouping>,
126    /// The metric query being aggregated.
127    pub inner: MetricQuery,
128}
129
130/// Vector aggregation functions.
131#[derive(Debug, Clone, Copy, PartialEq, Eq)]
132#[non_exhaustive]
133pub enum AggregationFunction {
134    Sum,
135    Avg,
136    Min,
137    Max,
138    Stddev,
139    Stdvar,
140    Count,
141    Topk,
142    Bottomk,
143    Sort,
144    SortDesc,
145}
146
147impl AggregationFunction {
148    /// Resolve an aggregation name to its variant.
149    pub fn from_name(name: &str) -> Option<Self> {
150        Some(match name {
151            "sum" => AggregationFunction::Sum,
152            "avg" => AggregationFunction::Avg,
153            "min" => AggregationFunction::Min,
154            "max" => AggregationFunction::Max,
155            "stddev" => AggregationFunction::Stddev,
156            "stdvar" => AggregationFunction::Stdvar,
157            "count" => AggregationFunction::Count,
158            "topk" => AggregationFunction::Topk,
159            "bottomk" => AggregationFunction::Bottomk,
160            "sort" => AggregationFunction::Sort,
161            "sort_desc" => AggregationFunction::SortDesc,
162            _ => return None,
163        })
164    }
165
166    /// Whether this aggregation requires a leading scalar parameter, as
167    /// in `topk(5, ...)`.
168    pub fn takes_param(self) -> bool {
169        matches!(
170            self,
171            AggregationFunction::Topk | AggregationFunction::Bottomk
172        )
173    }
174}
175
176/// A binary operation between two metric queries.
177#[derive(Debug, Clone, PartialEq)]
178pub struct BinaryExpr {
179    pub op: BinOp,
180    pub left: MetricQuery,
181    pub right: MetricQuery,
182    /// `true` when a comparison carries the `bool` modifier
183    /// (`> bool 5`), turning the filter into a 0/1 result.
184    pub bool_modifier: bool,
185    /// Optional `on (...)` / `ignoring (...)` vector-matching clause that
186    /// restricts which labels series are matched on.
187    pub matching: Option<VectorMatch>,
188}
189
190/// An `on (...)` / `ignoring (...)` vector-matching clause. `group_left` /
191/// `group_right` (many-to-one) are accepted by the parser but recorded as
192/// flags only; matching is evaluated one-to-one.
193#[derive(Debug, Clone, PartialEq, Eq)]
194pub struct VectorMatch {
195    /// `true` for `on (...)` (match only these labels), `false` for
196    /// `ignoring (...)` (match on all labels except these).
197    pub on: bool,
198    /// The labels named in the clause.
199    pub labels: Vec<String>,
200    /// `true` when a `group_left` / `group_right` modifier was present.
201    pub grouped: bool,
202}
203
204/// Binary operators, grouped by precedence tier (see the parser).
205#[derive(Debug, Clone, Copy, PartialEq, Eq)]
206#[non_exhaustive]
207pub enum BinOp {
208    // Arithmetic
209    Add,
210    Sub,
211    Mul,
212    Div,
213    Mod,
214    Pow,
215    // Comparison
216    Eq,
217    Neq,
218    Gt,
219    Gte,
220    Lt,
221    Lte,
222    // Logical / set
223    And,
224    Or,
225    Unless,
226}
227
228#[cfg(test)]
229mod tests {
230    use super::*;
231
232    /// Every range function the grammar accepts, and whether it takes a
233    /// leading scalar parameter. `quantile_over_time(0.99, …)` is the only one
234    /// that does — getting this wrong silently shifts a query's arguments.
235    #[test]
236    fn range_functions_round_trip_and_declare_their_parameter() {
237        let cases: &[(&str, RangeFunction, bool)] = &[
238            ("rate", RangeFunction::Rate, false),
239            ("count_over_time", RangeFunction::CountOverTime, false),
240            ("bytes_rate", RangeFunction::BytesRate, false),
241            ("bytes_over_time", RangeFunction::BytesOverTime, false),
242            ("sum_over_time", RangeFunction::SumOverTime, false),
243            ("avg_over_time", RangeFunction::AvgOverTime, false),
244            ("min_over_time", RangeFunction::MinOverTime, false),
245            ("max_over_time", RangeFunction::MaxOverTime, false),
246            ("stdvar_over_time", RangeFunction::StdvarOverTime, false),
247            ("stddev_over_time", RangeFunction::StddevOverTime, false),
248            ("first_over_time", RangeFunction::FirstOverTime, false),
249            ("last_over_time", RangeFunction::LastOverTime, false),
250            ("absent_over_time", RangeFunction::AbsentOverTime, false),
251            ("quantile_over_time", RangeFunction::QuantileOverTime, true),
252        ];
253        for (name, expected, takes_param) in cases {
254            assert_eq!(
255                RangeFunction::from_name(name),
256                Some(*expected),
257                "from_name({name:?})"
258            );
259            assert_eq!(expected.takes_param(), *takes_param, "{name} takes_param");
260        }
261    }
262
263    #[test]
264    fn unknown_range_functions_are_rejected() {
265        for name in ["rate_over_time", "histogram_quantile", "sum", ""] {
266            assert_eq!(RangeFunction::from_name(name), None, "{name:?}");
267        }
268    }
269
270    /// `topk`/`bottomk` take the `k`; the rest take no parameter.
271    #[test]
272    fn aggregation_functions_round_trip_and_declare_their_parameter() {
273        let cases: &[(&str, AggregationFunction, bool)] = &[
274            ("sum", AggregationFunction::Sum, false),
275            ("avg", AggregationFunction::Avg, false),
276            ("min", AggregationFunction::Min, false),
277            ("max", AggregationFunction::Max, false),
278            ("count", AggregationFunction::Count, false),
279            ("stddev", AggregationFunction::Stddev, false),
280            ("stdvar", AggregationFunction::Stdvar, false),
281            ("topk", AggregationFunction::Topk, true),
282            ("bottomk", AggregationFunction::Bottomk, true),
283        ];
284        for (name, expected, takes_param) in cases {
285            assert_eq!(
286                AggregationFunction::from_name(name),
287                Some(*expected),
288                "from_name({name:?})"
289            );
290            assert_eq!(expected.takes_param(), *takes_param, "{name} takes_param");
291        }
292    }
293
294    #[test]
295    fn unknown_aggregation_functions_are_rejected() {
296        for name in ["rate", "quantile", "median", ""] {
297            assert_eq!(AggregationFunction::from_name(name), None, "{name:?}");
298        }
299    }
300}