New in Grafana 9: The Grafana Loki query builder makes writing LogQL queries easier

Grafana 9 launched at GrafanaCONline 2022 in June, and one of the biggest highlights was the introduction of the new Grafana Loki and Prometheus  query builders. 🎉 We believe that both of them are going to be incredibly useful for our Prometheus and Grafana Loki users. 

In this blog post, we will focus on the Grafana Loki query builder and share its new features and improvements with you. There may even be some useful tips and tricks on how to improve your query writing, reading, and editing. 😉

While we believe that this query builder is going to help all of our Grafana Loki users, we think that it is going to be especially useful for those of you who are new to the Loki query language, LogQL. This is because LogQL is extremely powerful, but currently the power comes with understanding its syntax and capabilities. While the more queries you write, the better at LogQL you get, getting started with LogQL can be intimidating.

That is, until now. With the Grafana Loki query builder, we make it easier to start writing simple and complex queries.

How the Grafana Loki query builder helps write queries

Labels filter

Every Grafana Loki query usually starts with choosing which log streams should be included in your query. The stream selector consists of one or more key-value pairs, where each key is a log label and the value is that label’s value.

To select a label, simply click on the label selector. The label selector includes search, so you can also type out the label you are looking for. After you select the label, you can move to value.

In the value dropdown, you will see only values available for your selected label. If you would like to select multiple values, you can change exactly the equal operator (=) to regex match (=~). On the other hand, if you want to omit some values, you can use the not equal (!=) or regex does not match (!~) label matching operator.

To add more label-value combinations, you can use the + button. 

Operations

Now, having selected our log streams, we can start building up our query. There are a couple of ways you can build up your query. 

Add operations using + Operations button

With the Loki query builder, you can add to your query line filters, parsers, functions, aggregations, or even binary operations. To select any (or all) of these, you can click on + Operations and either look through different operation categories or use the search to find the operation you want to use. 

Note: Loki query builder supports simple binary operations like multiple or divide by scalar. Or even binary operations on nested query expressions. 

Every available operation comes with a tooltip on its use case and query syntax. Just click on the information button next to the operation name. 

Moreover, if you click on the arrow next to the name of operation, you get a list of alternative operations in the same category that you can choose from.

Add operations using query patterns

Query patterns is a list of useful operation patterns that can be used to quickly add multiple operations to your query to achieve a specific goal. This can be useful in cases when you know what you would like to achieve, but you are not sure about syntax. Or when you want to speed up your query writing.

To choose the pattern, simply click on the Query patterns button and look through possible options. It includes commonly used patterns for logs and metrics queries.

If you’ve found the pattern you would like to use, click on it. To demonstrate how quickly you can build up a complex query with query patterns, let’s walk through creating a metric query with operations on value inside the log line. 

While creating this from scratch can be intimidating and difficult, with query patterns you can simply click on the Metric query on value inside the log line option. All seven operations that compose this query are added for you. Your job is now to just review these operations and update them if needed. 

During this process, you can use the operation tooltip to learn more about each operation. Or use the list of alternative operations to update the operation you want. As easy as that, we are very quickly able to create complex LogQL queries without worrying too much about syntax.

How the Loki query builder helps edit queries

The Loki visual query builder helps with editing queries in a couple of different ways. First, it couples operations with its parameters. While in query, the operation and its parameters can be many characters apart; in query builders, they are always in one place. So it is much easier to find and edit them.

Secondly, it provides names for parameters. In the case below, where we are renaming the label, you might be wondering which is the original label and which is the renamed label. 

In the query builder, you can see this clearly as they are both specifically identified, which makes it easier for editing correct parameters.

How the Loki query builder helps with understanding queries

While the tooltip for each operation definitely helps with understanding the query, it gives you information only about that specific operation. To learn more about the query as a whole, we’ve added an Explain mode that shows a step-by-step explanation of all query parts and the operations. This is going to help you learn about your query or queries created by your teammates that you are not familiar with.

Switch between Code, Builder, and Explain at any time

You can switch between the Code (text mode), Builder, and Explain mode while having your text changes preserved. This is because the visual builder model is derived from the text query using a full-featured LogQL query parser. 

Help us make the Grafana Loki query builder better

We strongly believe that this is just the beginning for the Grafana Loki query builder. Our goal is to make sure that all of our Grafana Loki users have the best experience while working with their queries. If you have any thoughts, ideas, or feedback on how to make the Loki query builder better for you, please let us know in the GitHub discussion or on our Grafana Labs Community Slack.

If you are interested in seeing the Prometheus and Grafana Loki query builders in action, join us on the Grafana Community call on July 21 at 16:00 UTC, during which the Grafana’s Observability squad will lead discussions about these query builder features. Last but not least, if you would like to participate in Loki query builder’s user research, you can contact our team.

To learn more about all the latest features in Grafana 9, you can watch the “Deep dive into Grafana 9” session from GrafanaCONline 2022 on demand (and for free). 

Grafana Cloud is the easiest way to get started with metrics, logs, traces, and dashboards. We have a generous free forever tier and plans for every use case. Sign up for free now!