LogQL Supported Features
LogQL is a PromQL-inspired query language implemented by Loki. qryn implementes a growing range of compatible features based on clickhouse queries
There are two types of LogQL queries:
- Log queries return the contents of log lines.
- Metric queries extend log queries to calculate values based on query results.
All LogQL queries contain a log stream selector.
The stream selector determines which log streams to include in a query’s results. The stream selector is specified by one or more comma-separated key-value pairs. Each key is a log label and each value is that label’s value.
Consider this stream selector:
{app="mysql",name="mysql-backup"}
All log streams that have both a label of app whose value is mysql and a label of name whose value is mysql-backup will be included in the query results. A stream may contain other pairs of labels and values, but only the specified pairs within the stream selector are used to determine which streams will be included within the query results.
The = operator after the label name is a label matching operator. The following label matching operators are supported:
- |=: Label contains string
- !=: Label does not contain string
- |~: Label contains a match to the regular expression
- !~: Label does not contain a match to the regular expression
A log pipeline can be appended to a log stream selector to further process and filter log streams. It usually is composed of one or multiple expressions, each expressions is executed in sequence for each log line.
A log pipeline can be composed of:
- Line Filter Expression
- Parser Expression
- Label Filter Expression
- Line Format Expression
- Unwrap Expression
The line filter expressions are used to filter the contents of returned logs, discarding those lines that do not match the case sensitive expression.
The following filter operators are supported:
- |=: Log line contains string
- !=: Log line does not contain string
- |~: Log line contains a match to the regular expression
- !~: Log line does not contain a match to the regular expression
A complete query using this example:
{job="mysql"} |= "error"
Parser expression can parse and extract labels from the log content. Those extracted labels can then be used for filtering using label filter expressions or for metric aggregations.
The json parser operates in two modes:
-
without parameters:
- Adding
| jsonto your pipeline will extract all json properties as labels if the log line is a valid json document. Nested properties are flattened into label keys using the _ separator. {job="0.6611336793589486_json"} | json
- Adding
-
with parameters:
- Using
| json label="expression"in your pipeline will extract only the specified json fields to labels. {job="0.6611336793589486_json"} | json my_field="json_field"
- Using
The regexp parser operates against log string and requires named groups for matching.
Example: extract a new label named token from a string ie: YYYY-MM-DDT00:00:00Z ... Reserving 1.1Mb of memory
{type="clickhouse"} |~"Reserving" | regexp "Reserving (?<token>\\d+.\\d+)"
Label filter expression allows filtering log line using their original and extracted labels. It can contain multiple predicates.
A predicate contains a label identifier, an operation and a value to compare the label with.
Label filters work like label matchers and use the same operations (=,!=,=~,!~).
{job="0.6611336793589486_json"} | json | my_field="VALUE"
Line Format expression allows the re-formatting of parts of a log line. It can extract items from parsed json.
To extract a parameter we use "{{}}" to surround it and extract it as the displayed log line as a result. Any thing can be added to this line format, to allow for additional notes or formatting.
{job="0.6611336793589486_json"} | json | line_format "My field : {{my_field}}"
Creates new log lines of the string "My field: VALUE"
Unwrap Expressions allows for the unwrapping of a value to be used in an aggregation. It can extract any parsed json value.
To extract a value we first parse the log via json and select the field we are interested in. Then using unwrap we unwrap the data for visualization.
avg_over_time({job="0.6611336793589486_json"} | json myField="my_field" | unwrap myField [5s])"
This extracts the value of my_field and aggregates it into an average of 5s buckets over your chosen timeframe.
LogQL supports applying a function to log query results. This powerful feature creates metrics from logs.
A log range aggregation is a query followed by a duration. A function is applied to aggregate the query over the duration. The duration can be placed after the log stream selector or at end of the log pipeline. The functions:
- rate(log-range): calculates the number of entries per second
- count_over_time(log-range): counts the entries for each log stream within the given range.
- bytes_rate(log-range): calculates the number of bytes per second for each stream.
- bytes_over_time(log-range): counts the amount of bytes used by each log stream for a given range.
- absent_over_time(log-range): returns an empty vector if the range vector passed to it has any elements and a 1-element vector with the value 1 if the range vector passed to it has no elements. (absent_over_time is useful for alerting on when no time series and logs stream exist for label combination for a certain amount of time.)
Like PromQL, LogQL supports a subset of built-in aggregation operators that can be used to aggregate the element of a single vector, resulting in a new vector of fewer elements but with aggregated values:
-
sum: Calculate sum over labels -
min: Select minimum over labels -
max: Select maximum over labels -
avg: Calculate the average over labels
Note any clickhouse aggregate function can be used within qryn.
The aggregation operators can either be used to aggregate over all label values or a set of distinct label values by including a without or a by clause:
<aggr-op>([parameter,] <vector expression>) [without|by (<label list>)]
Example:
- sum(count_over_time({label=value}[range])) by (label)