Skip to main content

logql/
ast.rs

1//! # LogQL AST
2//!
3//! Abstract syntax tree for parsed LogQL queries. The tree mirrors the
4//! shape of the language: a log query is a stream selector followed by
5//! an optional pipeline; metric queries (added with the metric-query
6//! parser) wrap log queries in range and vector aggregations.
7
8/// A parsed log query: stream selector plus pipeline stages.
9#[derive(Debug, Clone, PartialEq)]
10pub struct LogQuery {
11    pub selector: StreamSelector,
12    pub pipeline: Vec<PipelineStage>,
13}
14
15/// The `{...}` stream selector: a conjunction of label matchers.
16#[derive(Debug, Clone, PartialEq, Default)]
17pub struct StreamSelector {
18    pub matchers: Vec<LabelMatcher>,
19}
20
21/// One label matcher, e.g. `service_name=~"web-.*"`.
22#[derive(Debug, Clone, PartialEq)]
23pub struct LabelMatcher {
24    pub name: String,
25    pub op: MatchOp,
26    pub value: String,
27}
28
29/// Label matching operator.
30#[derive(Debug, Clone, Copy, PartialEq, Eq)]
31#[non_exhaustive]
32pub enum MatchOp {
33    /// `=`
34    Eq,
35    /// `!=`
36    Neq,
37    /// `=~`
38    Re,
39    /// `!~`
40    Nre,
41}
42
43impl std::fmt::Display for MatchOp {
44    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
45        f.write_str(match self {
46            MatchOp::Eq => "=",
47            MatchOp::Neq => "!=",
48            MatchOp::Re => "=~",
49            MatchOp::Nre => "!~",
50        })
51    }
52}
53
54/// One stage of a log pipeline (`|= "err"`, `| json`, `| level="error"`).
55#[derive(Debug, Clone, PartialEq)]
56#[non_exhaustive]
57pub enum PipelineStage {
58    /// Line filter: `|= "err"`, `!= "noise"`, `|~ "re"`, `!~ "re"`.
59    LineFilter(LineFilter),
60    /// `| json` with optional label-extraction expressions.
61    Json(Vec<LabelExtraction>),
62    /// `| logfmt` with optional flags (`--strict`, `--keep-empty`) and
63    /// label-extraction expressions.
64    Logfmt(LogfmtStage),
65    /// `| regexp "(?P<name>re)"` — named-capture extraction.
66    Regexp(String),
67    /// `| pattern "<method> <path>"` — pattern extraction.
68    Pattern(String),
69    /// `| unpack` — promote a packed JSON entry's labels.
70    Unpack,
71    /// `| decolorize` — strip ANSI color codes from the line.
72    Decolorize,
73    /// `| level="error"`, `| status >= 500 and duration > 1s`.
74    LabelFilter(LabelFilterExpr),
75    /// `| line_format "{{.msg}}"`.
76    LineFormat(String),
77    /// `| label_format dst="src", pretty=`{{.x}}``.
78    LabelFormat(Vec<LabelFormat>),
79    /// `| drop label1, method="GET"` — drop labels, optionally only when
80    /// a matcher holds.
81    Drop(Vec<LabelPredicate>),
82    /// `| keep label1, method="GET"` — keep only these labels.
83    Keep(Vec<LabelPredicate>),
84    /// `| distinct label1, label2` — drop consecutive duplicate lines by
85    /// the given labels.
86    Distinct(Vec<String>),
87    /// `| unwrap duration_ms` or `| unwrap duration(latency)`.
88    Unwrap(Unwrap),
89}
90
91/// A line filter: an operator, a match value, and whether the value is
92/// an `ip("...")` matcher rather than a literal/regex.
93#[derive(Debug, Clone, PartialEq)]
94pub struct LineFilter {
95    pub op: LineFilterOp,
96    pub value: String,
97    /// `true` for `|= ip("...")`, matching the line's IP addresses.
98    pub is_ip: bool,
99}
100
101/// A `logfmt` stage: optional flags plus label extractions.
102#[derive(Debug, Clone, Default, PartialEq)]
103pub struct LogfmtStage {
104    /// Flags such as `strict` and `keep-empty` (without the `--`).
105    pub flags: Vec<String>,
106    pub extractions: Vec<LabelExtraction>,
107}
108
109/// One `drop`/`keep` item: a label name, optionally gated by a matcher
110/// (`method="GET"`, `app=~"api.*"`).
111#[derive(Debug, Clone, PartialEq)]
112pub struct LabelPredicate {
113    pub name: String,
114    /// The matcher operator and value, when the item is `name op "value"`
115    /// rather than a bare label name.
116    pub matcher: Option<(MatchOp, String)>,
117}
118
119/// Line filter operators.
120#[derive(Debug, Clone, Copy, PartialEq, Eq)]
121#[non_exhaustive]
122pub enum LineFilterOp {
123    /// `|=`
124    Contains,
125    /// `!=`
126    NotContains,
127    /// `|~`
128    Regex,
129    /// `!~`
130    NotRegex,
131}
132
133/// One label extraction expression for `json`/`logfmt`, e.g.
134/// `status="response.status"` or a bare `level`.
135#[derive(Debug, Clone, PartialEq)]
136pub struct LabelExtraction {
137    /// Destination label name.
138    pub name: String,
139    /// Source expression (JSON path / logfmt key). `None` extracts the
140    /// field whose name equals `name`.
141    pub expr: Option<String>,
142}
143
144/// One `label_format` assignment.
145#[derive(Debug, Clone, PartialEq)]
146pub struct LabelFormat {
147    /// Destination label.
148    pub dst: String,
149    /// Either a rename from another label or a Go-template string.
150    pub value: LabelFormatValue,
151}
152
153/// The right-hand side of a `label_format` assignment.
154#[derive(Debug, Clone, PartialEq)]
155#[non_exhaustive]
156pub enum LabelFormatValue {
157    /// `dst=src_label` — rename/copy from another label.
158    Rename(String),
159    /// `dst="template"` — render a Go template.
160    Template(String),
161}
162
163/// A `by`/`without` grouping clause, shared by vector aggregations and
164/// unwrapped range aggregations.
165#[derive(Debug, Clone, PartialEq, Eq)]
166pub struct Grouping {
167    /// `true` for `without (...)`, `false` for `by (...)`.
168    pub without: bool,
169    /// The labels listed in the clause (may be empty: `by ()`).
170    pub labels: Vec<String>,
171}
172
173/// An `unwrap` stage: the label to unwrap plus an optional conversion.
174#[derive(Debug, Clone, PartialEq)]
175pub struct Unwrap {
176    /// Label whose value is unwrapped into a sample value.
177    pub label: String,
178    /// Conversion function wrapping the label, e.g. `duration` or
179    /// `bytes` in `unwrap duration(latency)`.
180    pub conversion: Option<String>,
181}
182
183/// A label-filter expression: comparisons combined with `and`/`or`.
184///
185/// A comma between predicates is sugar for `and`. `and` binds tighter
186/// than `or`.
187#[derive(Debug, Clone, PartialEq)]
188#[non_exhaustive]
189pub enum LabelFilterExpr {
190    Pred(LabelFilterPred),
191    And(Box<LabelFilterExpr>, Box<LabelFilterExpr>),
192    Or(Box<LabelFilterExpr>, Box<LabelFilterExpr>),
193}
194
195/// A single label-filter comparison, e.g. `status >= 500`.
196#[derive(Debug, Clone, PartialEq)]
197pub struct LabelFilterPred {
198    pub name: String,
199    pub op: FilterOp,
200    pub value: FilterValue,
201}
202
203/// Label-filter comparison operators. String matchers (`=`, `!=`, `=~`,
204/// `!~`) and ordered comparisons (`==`, `>`, `>=`, `<`, `<=`) share this
205/// enum; the parser rejects operator/value combinations that don't fit
206/// (e.g. `=~` against a number).
207#[derive(Debug, Clone, Copy, PartialEq, Eq)]
208#[non_exhaustive]
209pub enum FilterOp {
210    Eq,
211    Neq,
212    Re,
213    Nre,
214    CmpEq,
215    Gt,
216    Gte,
217    Lt,
218    Lte,
219}
220
221/// The right-hand side value of a label filter.
222#[derive(Debug, Clone, PartialEq)]
223#[non_exhaustive]
224pub enum FilterValue {
225    /// A quoted string (used with `=`, `!=`, `=~`, `!~`, and `==`).
226    String(String),
227    /// A numeric literal.
228    Number(f64),
229    /// A duration literal such as `1s` or `500ms`.
230    Duration(std::time::Duration),
231    /// A bytes literal such as `20KB` or `5MB`, in bytes.
232    Bytes(u64),
233    /// An `ip("...")` matcher (single address, CIDR, or range).
234    Ip(String),
235}
236
237#[cfg(test)]
238mod tests {
239    use super::*;
240
241    /// `MatchOp` renders back into a stream selector, so the text must be the
242    /// operator as written rather than the variant name.
243    #[test]
244    fn match_ops_display_as_their_operators() {
245        assert_eq!(MatchOp::Eq.to_string(), "=");
246        assert_eq!(MatchOp::Neq.to_string(), "!=");
247        assert_eq!(MatchOp::Re.to_string(), "=~");
248        assert_eq!(MatchOp::Nre.to_string(), "!~");
249    }
250}