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}