Skip to main content

logql/
lib.rs

1//! # LogQL Front-End
2//!
3//! Lexing, parsing, and syntactic validation for Grafana Loki's LogQL. This
4//! crate recognises a query; it does not execute one. It knows nothing about
5//! columns, catalogs, tenants, or storage, and depends on nothing but
6//! `thiserror` — so the same query string parses identically whatever backend
7//! it is aimed at, and validity can be checked without one at all.
8//!
9//! Published as **`logql-parser`**; the library is imported as `logql`.
10//!
11//! ## The two query forms
12//!
13//! A **log query** starts from a stream selector (`{service_name="api"}`),
14//! optionally followed by a pipeline of line filters, label filters, parser
15//! stages, and formatters:
16//!
17//! ```text
18//! {service_name="api"} |= "error" | json | status >= 500
19//! ```
20//!
21//! A **metric query** wraps one in a range or vector aggregation:
22//!
23//! ```text
24//! sum by (service_name) (rate({service_name="api"} |= "error" [5m]))
25//! ```
26//!
27//! [`parse`] accepts either and returns an [`Expr`] saying which it got;
28//! [`parse_query`] and [`parse_selector`] are the narrower entry points.
29//!
30//! ## Errors carry positions
31//!
32//! [`LexError`] and [`ParseError`] both report 1-based line and column, so a
33//! caller can underline the offending token rather than restating the query.
34//!
35//! ## Modules
36//!
37//! - [`token`]: token type produced by the lexer
38//! - [`lexer`]: hand-rolled tokenizer with line/column error reporting
39//! - [`ast`]: abstract syntax tree for log queries
40//! - [`metric`]: abstract syntax tree for metric queries
41//! - [`parser`]: recursive-descent parser over the token stream
42
43pub mod ast;
44pub mod lexer;
45pub mod metric;
46pub mod parser;
47pub mod token;
48
49pub use ast::{
50    FilterOp, FilterValue, Grouping, LabelExtraction, LabelFilterExpr, LabelFilterPred,
51    LabelFormat, LabelFormatValue, LabelMatcher, LabelPredicate, LineFilter, LineFilterOp,
52    LogQuery, LogfmtStage, MatchOp, PipelineStage, StreamSelector, Unwrap,
53};
54pub use lexer::{LexError, tokenize};
55pub use metric::{
56    AggregationFunction, BinOp, BinaryExpr, LabelReplace, MetricQuery, RangeAggregation,
57    RangeFunction, VectorAggregation, VectorMatch,
58};
59pub use parser::{Expr, ParseError, parse, parse_metric_query, parse_query, parse_selector};
60pub use token::{SpannedToken, Token};